gnu.inet.smtp
Class SMTPConnection

java.lang.Object
  extended by gnu.inet.smtp.SMTPConnection

public class SMTPConnection
extends java.lang.Object

An SMTP client. This implements RFC 2821.

Author:
Chris Burdess

Field Summary
protected static int AMBIGUOUS
           
protected static java.lang.String AUTH
           
protected  boolean continuation
          If true, there are more responses to read.
protected static java.lang.String DATA
           
static int DEFAULT_PORT
          The default SMTP port.
protected static java.lang.String EHLO
           
protected static java.lang.String EXPN
           
protected static java.lang.String FINISH_DATA
           
protected  java.lang.String greeting
          The greeting message given by the server.
protected static java.lang.String HELO
           
protected static java.lang.String HELP
           
protected  LineInputStream in
          The input stream used to read responses from the server.
protected static int INFO
           
static java.util.logging.Logger logger
          The logger used for SMTP protocol traces.
protected static java.lang.String MAIL_FROM
           
protected static java.lang.String NOOP
           
protected static int OK
           
protected static int OK_NOT_LOCAL
           
protected static int OK_UNVERIFIED
           
protected  CRLFOutputStream out
          The output stream used to send commands to the server.
protected static java.lang.String QUIT
           
protected static java.lang.String RCPT_TO
           
protected static int READY
           
protected  java.lang.String response
          The last response message received from the server.
protected static java.lang.String RSET
           
protected static int SEND_DATA
           
static java.util.logging.Level SMTP_TRACE
          The network trace level.
protected  java.net.Socket socket
          The underlying socket used for communicating with the server.
protected static java.lang.String SP
           
protected static java.lang.String STARTTLS
           
protected static java.lang.String VRFY
           
 
Constructor Summary
SMTPConnection(java.lang.String host)
          Creates a new connection to the specified host, using the default SMTP port.
SMTPConnection(java.lang.String host, int port)
          Creates a new connection to the specified host, using the specified port.
SMTPConnection(java.lang.String host, int port, int connectionTimeout, int timeout)
          Creates a new connection to the specified host, using the specified port.
SMTPConnection(java.lang.String host, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm)
          Creates a new connection to the specified host, using the specified port.
SMTPConnection(java.lang.String host, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm, boolean init)
          Creates a new connection to the specified host, using the specified port.
 
Method Summary
 boolean authenticate(java.lang.String mechanism, java.lang.String username, java.lang.String password)
          Authenticates the connection using the specified SASL mechanism, username, and password.
 java.io.OutputStream data()
          Requests an output stream to write message data to.
 java.util.List ehlo(java.lang.String hostname)
          Issues an EHLO command.
 java.util.List expn(java.lang.String address)
          Returns a list of valid possibilities for the specified mailing list, or null on failure.
 boolean finishData()
          Completes the DATA procedure.
protected  int getAllResponses()
          Returns the next response from the server.
 java.lang.String getGreeting()
          Returns the server greeting message.
 java.lang.String getLastResponse()
          Returns the text of the last response received from the server.
protected  int getResponse()
          Returns the next response from the server.
protected  javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
          Returns a configured SSLSocketFactory to use in creating new SSL sockets.
 boolean helo(java.lang.String hostname)
          Issues a HELO command.
 java.util.List help(java.lang.String arg)
          Returns some useful information about the specified parameter.
 void init()
          Initialises the connection.
 boolean mailFrom(java.lang.String reversePath, ParameterList parameters)
          Execute a MAIL command.
 void noop()
          Issues a NOOP command.
 void quit()
          Close the connection to the server.
 boolean rcptTo(java.lang.String forwardPath, ParameterList parameters)
          Execute a RCPT command.
 void rset()
          Aborts the current mail transaction.
protected  void send(java.lang.String command)
          Send the specified command string to the server.
 boolean starttls()
          Negotiate TLS over the current connection.
 boolean starttls(javax.net.ssl.TrustManager tm)
          Negotiate TLS over the current connection.
 java.util.List vrfy(java.lang.String address)
          Returns a list of valid possibilities for the specified address, or null on failure.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SMTP_TRACE

public static final java.util.logging.Level SMTP_TRACE
The network trace level.


DEFAULT_PORT

public static final int DEFAULT_PORT
The default SMTP port.

See Also:
Constant Field Values

MAIL_FROM

protected static final java.lang.String MAIL_FROM
See Also:
Constant Field Values

RCPT_TO

protected static final java.lang.String RCPT_TO
See Also:
Constant Field Values

SP

protected static final java.lang.String SP
See Also:
Constant Field Values

DATA

protected static final java.lang.String DATA
See Also:
Constant Field Values

FINISH_DATA

protected static final java.lang.String FINISH_DATA
See Also:
Constant Field Values

RSET

protected static final java.lang.String RSET
See Also:
Constant Field Values

VRFY

protected static final java.lang.String VRFY
See Also:
Constant Field Values

EXPN

protected static final java.lang.String EXPN
See Also:
Constant Field Values

HELP

protected static final java.lang.String HELP
See Also:
Constant Field Values

NOOP

protected static final java.lang.String NOOP
See Also:
Constant Field Values

QUIT

protected static final java.lang.String QUIT
See Also:
Constant Field Values

HELO

protected static final java.lang.String HELO
See Also:
Constant Field Values

EHLO

protected static final java.lang.String EHLO
See Also:
Constant Field Values

AUTH

protected static final java.lang.String AUTH
See Also:
Constant Field Values

STARTTLS

protected static final java.lang.String STARTTLS
See Also:
Constant Field Values

INFO

protected static final int INFO
See Also:
Constant Field Values

READY

protected static final int READY
See Also:
Constant Field Values

OK

protected static final int OK
See Also:
Constant Field Values

OK_NOT_LOCAL

protected static final int OK_NOT_LOCAL
See Also:
Constant Field Values

OK_UNVERIFIED

protected static final int OK_UNVERIFIED
See Also:
Constant Field Values

SEND_DATA

protected static final int SEND_DATA
See Also:
Constant Field Values

AMBIGUOUS

protected static final int AMBIGUOUS
See Also:
Constant Field Values

logger

public static final java.util.logging.Logger logger
The logger used for SMTP protocol traces.


socket

protected java.net.Socket socket
The underlying socket used for communicating with the server.


in

protected LineInputStream in
The input stream used to read responses from the server.


out

protected CRLFOutputStream out
The output stream used to send commands to the server.


response

protected java.lang.String response
The last response message received from the server.


continuation

protected boolean continuation
If true, there are more responses to read.


greeting

protected java.lang.String greeting
The greeting message given by the server.

Constructor Detail

SMTPConnection

public SMTPConnection(java.lang.String host)
               throws java.io.IOException
Creates a new connection to the specified host, using the default SMTP port.

Parameters:
host - the server hostname
Throws:
java.io.IOException

SMTPConnection

public SMTPConnection(java.lang.String host,
                      int port)
               throws java.io.IOException
Creates a new connection to the specified host, using the specified port.

Parameters:
host - the server hostname
port - the port to connect to
Throws:
java.io.IOException

SMTPConnection

public SMTPConnection(java.lang.String host,
                      int port,
                      int connectionTimeout,
                      int timeout)
               throws java.io.IOException
Creates a new connection to the specified host, using the specified port.

Parameters:
host - the server hostname
port - the port to connect to
connectionTimeout - the connection timeout in milliseconds
timeout - the I/O timeout in milliseconds
Throws:
java.io.IOException

SMTPConnection

public SMTPConnection(java.lang.String host,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      javax.net.ssl.TrustManager tm)
               throws java.io.IOException
Creates a new connection to the specified host, using the specified port.

Parameters:
host - the server hostname
port - the port to connect to
connectionTimeout - the connection timeout in milliseconds
timeout - the I/O timeout in milliseconds
secure - true to create an SMTPS connection
tm - a trust manager used to check SSL certificates, or null to use the default
Throws:
java.io.IOException

SMTPConnection

public SMTPConnection(java.lang.String host,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      javax.net.ssl.TrustManager tm,
                      boolean init)
               throws java.io.IOException
Creates a new connection to the specified host, using the specified port.

Parameters:
host - the server hostname
port - the port to connect to
connectionTimeout - the connection timeout in milliseconds
timeout - the I/O timeout in milliseconds
secure - true to create an SMTPS connection
tm - a trust manager used to check SSL certificates, or null to use the default
init - initialise the connection
Throws:
java.io.IOException
Method Detail

init

public void init()
          throws java.io.IOException
Initialises the connection. Unless the init parameter was provided with the value false, do not call this method. Otherwise call it only once after e.g. configuring logging.

Throws:
java.io.IOException

getGreeting

public java.lang.String getGreeting()
Returns the server greeting message.


getLastResponse

public java.lang.String getLastResponse()
Returns the text of the last response received from the server.


mailFrom

public boolean mailFrom(java.lang.String reversePath,
                        ParameterList parameters)
                 throws java.io.IOException
Execute a MAIL command.

Parameters:
reversePath - the source mailbox(from address)
parameters - optional ESMTP parameters
Returns:
true if accepted, false otherwise
Throws:
java.io.IOException

rcptTo

public boolean rcptTo(java.lang.String forwardPath,
                      ParameterList parameters)
               throws java.io.IOException
Execute a RCPT command.

Parameters:
forwardPath - the forward-path(recipient address)
parameters - optional ESMTP parameters
Returns:
true if successful, false otherwise
Throws:
java.io.IOException

data

public java.io.OutputStream data()
                          throws java.io.IOException
Requests an output stream to write message data to. When the entire message has been written to the stream, the flush method must be called on the stream. Until then no further methods should be called on the connection. Immediately after this procedure is complete, finishData must be called to complete the transfer and determine its success.

Returns:
a stream for writing messages to
Throws:
java.io.IOException

finishData

public boolean finishData()
                   throws java.io.IOException
Completes the DATA procedure.

Returns:
true id transfer was successful, false otherwise
Throws:
java.io.IOException
See Also:
data()

rset

public void rset()
          throws java.io.IOException
Aborts the current mail transaction.

Throws:
java.io.IOException

vrfy

public java.util.List vrfy(java.lang.String address)
                    throws java.io.IOException
Returns a list of valid possibilities for the specified address, or null on failure.

Parameters:
address - a mailbox, or real name and mailbox
Throws:
java.io.IOException

expn

public java.util.List expn(java.lang.String address)
                    throws java.io.IOException
Returns a list of valid possibilities for the specified mailing list, or null on failure.

Parameters:
address - a mailing list name
Throws:
java.io.IOException

help

public java.util.List help(java.lang.String arg)
                    throws java.io.IOException
Returns some useful information about the specified parameter. Typically this is a command.

Parameters:
arg - the context of the query, or null for general information
Returns:
a list of possibly useful information, or null if the command failed.
Throws:
java.io.IOException

noop

public void noop()
          throws java.io.IOException
Issues a NOOP command. This does nothing, but can be used to keep the connection alive.

Throws:
java.io.IOException

quit

public void quit()
          throws java.io.IOException
Close the connection to the server.

Throws:
java.io.IOException

helo

public boolean helo(java.lang.String hostname)
             throws java.io.IOException
Issues a HELO command.

Parameters:
hostname - the local host name
Throws:
java.io.IOException

ehlo

public java.util.List ehlo(java.lang.String hostname)
                    throws java.io.IOException
Issues an EHLO command. If successful, returns a list of the SMTP extensions supported by the server. Otherwise returns null, and HELO should be called.

Parameters:
hostname - the local host name
Throws:
java.io.IOException

getSSLSocketFactory

protected javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
                                                      throws java.security.GeneralSecurityException
Returns a configured SSLSocketFactory to use in creating new SSL sockets.

Parameters:
tm - an optional trust manager to use
Throws:
java.security.GeneralSecurityException

starttls

public boolean starttls()
                 throws java.io.IOException
Negotiate TLS over the current connection. This depends on many features, such as the JSSE classes being in the classpath. Returns true if successful, false otherwise.

Throws:
java.io.IOException

starttls

public boolean starttls(javax.net.ssl.TrustManager tm)
                 throws java.io.IOException
Negotiate TLS over the current connection. This depends on many features, such as the JSSE classes being in the classpath. Returns true if successful, false otherwise.

Parameters:
tm - the custom trust manager to use
Throws:
java.io.IOException

authenticate

public boolean authenticate(java.lang.String mechanism,
                            java.lang.String username,
                            java.lang.String password)
                     throws java.io.IOException
Authenticates the connection using the specified SASL mechanism, username, and password.

Parameters:
mechanism - a SASL authentication mechanism, e.g. LOGIN, PLAIN, CRAM-MD5, GSSAPI
username - the authentication principal
password - the authentication credentials
Returns:
true if authentication was successful, false otherwise
Throws:
java.io.IOException

send

protected void send(java.lang.String command)
             throws java.io.IOException
Send the specified command string to the server.

Parameters:
command - the command to send
Throws:
java.io.IOException

getResponse

protected int getResponse()
                   throws java.io.IOException
Returns the next response from the server.

Throws:
java.io.IOException

getAllResponses

protected int getAllResponses()
                       throws java.io.IOException
Returns the next response from the server. If the response is a continuation, continues to read responses until continuation ceases. If a different response code from the first is encountered, this causes a protocol exception.

Throws:
java.io.IOException


© Copyright 2003 The Free Software Foundation, all rights reserved