gnu.inet.smtp

Class SMTPConnection


public class SMTPConnection
extends java.lang.Object

An SMTP client. This implements RFC 2821.

Field Summary

protected static int
AMBIGUOUS
protected static String
AUTH
protected static String
DATA
static int
DEFAULT_PORT
The default SMTP port.
protected static String
EHLO
protected static String
EXPN
protected static String
FINISH_DATA
protected static String
HELO
protected static String
HELP
protected static int
INFO
protected static String
MAIL_FROM
protected static String
NOOP
protected static int
OK
protected static int
OK_NOT_LOCAL
protected static int
OK_UNVERIFIED
protected static String
QUIT
protected static String
RCPT_TO
protected static int
READY
protected static String
RSET
protected static int
SEND_DATA
static Level
SMTP_TRACE
The network trace level.
protected static String
SP
protected static String
STARTTLS
protected static String
VRFY
protected boolean
continuation
If true, there are more responses to read.
protected String
greeting
The greeting message given by the server.
protected LineInputStream
in
The input stream used to read responses from the server.
static Logger
logger
The logger used for SMTP protocol traces.
protected CRLFOutputStream
out
The output stream used to send commands to the server.
protected String
response
The last response message received from the server.
protected Socket
socket
The underlying socket used for communicating with the server.

Constructor Summary

SMTPConnection(String host)
Creates a new connection to the specified host, using the default SMTP port.
SMTPConnection(String host, int port)
Creates a new connection to the specified host, using the specified port.
SMTPConnection(String host, int port, int connectionTimeout, int timeout)
Creates a new connection to the specified host, using the specified port.
SMTPConnection(String host, int port, int connectionTimeout, int timeout, boolean secure, TrustManager tm)
Creates a new connection to the specified host, using the specified port.
SMTPConnection(String host, int port, int connectionTimeout, int timeout, boolean secure, TrustManager tm, boolean init)
Creates a new connection to the specified host, using the specified port.

Method Summary

boolean
authenticate(String mechanism, String username, String password)
Authenticates the connection using the specified SASL mechanism, username, and password.
OutputStream
data()
Requests an output stream to write message data to.
List
ehlo(String hostname)
Issues an EHLO command.
List
expn(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.
String
getGreeting()
Returns the server greeting message.
String
getLastResponse()
Returns the text of the last response received from the server.
protected int
getResponse()
Returns the next response from the server.
protected SSLSocketFactory
getSSLSocketFactory(TrustManager tm)
Returns a configured SSLSocketFactory to use in creating new SSL sockets.
boolean
helo(String hostname)
Issues a HELO command.
List
help(String arg)
Returns some useful information about the specified parameter.
void
init()
Initialises the connection.
boolean
mailFrom(String reversePath, ParameterList parameters)
Execute a MAIL command.
void
noop()
Issues a NOOP command.
void
quit()
Close the connection to the server.
boolean
rcptTo(String forwardPath, ParameterList parameters)
Execute a RCPT command.
void
rset()
Aborts the current mail transaction.
protected void
send(String command)
Send the specified command string to the server.
boolean
starttls()
Negotiate TLS over the current connection.
boolean
starttls(TrustManager tm)
Negotiate TLS over the current connection.
List
vrfy(String address)
Returns a list of valid possibilities for the specified address, or null on failure.

Field Details

AMBIGUOUS

protected static final int AMBIGUOUS
Field Value:
553

AUTH

protected static final String AUTH

DATA

protected static final String DATA

DEFAULT_PORT

public static final int DEFAULT_PORT
The default SMTP port.
Field Value:
25

EHLO

protected static final String EHLO

EXPN

protected static final String EXPN

FINISH_DATA

protected static final String FINISH_DATA

HELO

protected static final String HELO

HELP

protected static final String HELP

INFO

protected static final int INFO
Field Value:
214

MAIL_FROM

protected static final String MAIL_FROM

NOOP

protected static final String NOOP

OK

protected static final int OK
Field Value:
250

OK_NOT_LOCAL

protected static final int OK_NOT_LOCAL
Field Value:
251

OK_UNVERIFIED

protected static final int OK_UNVERIFIED
Field Value:
252

QUIT

protected static final String QUIT

RCPT_TO

protected static final String RCPT_TO

READY

protected static final int READY
Field Value:
220

RSET

protected static final String RSET

SEND_DATA

protected static final int SEND_DATA
Field Value:
354

SMTP_TRACE

public static final Level SMTP_TRACE
The network trace level.

SP

protected static final String SP

STARTTLS

protected static final String STARTTLS

VRFY

protected static final String VRFY

continuation

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

greeting

protected String greeting
The greeting message given by the server.

in

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

logger

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

out

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

response

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

socket

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

Constructor Details

SMTPConnection

public SMTPConnection(String host)
            throws IOException
Creates a new connection to the specified host, using the default SMTP port.
Parameters:
host - the server hostname

SMTPConnection

public SMTPConnection(String host,
                      int port)
            throws IOException
Creates a new connection to the specified host, using the specified port.
Parameters:
host - the server hostname
port - the port to connect to

SMTPConnection

public SMTPConnection(String host,
                      int port,
                      int connectionTimeout,
                      int timeout)
            throws 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

SMTPConnection

public SMTPConnection(String host,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      TrustManager tm)
            throws 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

SMTPConnection

public SMTPConnection(String host,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      TrustManager tm,
                      boolean init)
            throws 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

Method Details

authenticate

public boolean authenticate(String mechanism,
                            String username,
                            String password)
            throws 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

data

public OutputStream data()
            throws 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

ehlo

public List ehlo(String hostname)
            throws 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

expn

public List expn(String address)
            throws IOException
Returns a list of valid possibilities for the specified mailing list, or null on failure.
Parameters:
address - a mailing list name

finishData

public boolean finishData()
            throws IOException
Completes the DATA procedure.
Returns:
true id transfer was successful, false otherwise

getAllResponses

protected int getAllResponses()
            throws 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.

getGreeting

public String getGreeting()
Returns the server greeting message.

getLastResponse

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

getResponse

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

getSSLSocketFactory

protected SSLSocketFactory getSSLSocketFactory(TrustManager tm)
            throws GeneralSecurityException
Returns a configured SSLSocketFactory to use in creating new SSL sockets.
Parameters:
tm - an optional trust manager to use

helo

public boolean helo(String hostname)
            throws IOException
Issues a HELO command.
Parameters:
hostname - the local host name

help

public List help(String arg)
            throws 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.

init

public void init()
            throws 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.

mailFrom

public boolean mailFrom(String reversePath,
                        ParameterList parameters)
            throws IOException
Execute a MAIL command.
Parameters:
reversePath - the source mailbox(from address)
parameters - optional ESMTP parameters
Returns:
true if accepted, false otherwise

noop

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

quit

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

rcptTo

public boolean rcptTo(String forwardPath,
                      ParameterList parameters)
            throws IOException
Execute a RCPT command.
Parameters:
forwardPath - the forward-path(recipient address)
parameters - optional ESMTP parameters
Returns:
true if successful, false otherwise

rset

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

send

protected void send(String command)
            throws IOException
Send the specified command string to the server.
Parameters:
command - the command to send

starttls

public boolean starttls()
            throws 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.

starttls

public boolean starttls(TrustManager tm)
            throws 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

vrfy

public List vrfy(String address)
            throws IOException
Returns a list of valid possibilities for the specified address, or null on failure.
Parameters:
address - a mailbox, or real name and mailbox