com.sun.mail.smtp

Class SMTPTransport

java.lang.Object

jakarta.mail.Service

jakarta.mail.Transport

com.sun.mail.smtp.SMTPTransport

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

SMTPSSLTransport

public class SMTPTransport
extends Transport

This class implements the Transport abstract class using SMTP for message submission and transport.

See the com.sun.mail.smtp package documentation for further information on the SMTP protocol provider.

This class includes many protected methods that allow a subclass to extend this class and add support for non-standard SMTP commands. The issueCommand(java.lang.String, int) and sendCommand(java.lang.String) methods can be used to send simple SMTP commands. Other methods such as the mailFrom() and data() methods can be overridden to insert new commands before or after the corresponding SMTP commands. For example, a subclass could do this to send the XACT command before sending the DATA command:

        protected OutputStream data() throws MessagingException {
            if (supportsExtension("XACCOUNTING"))
                issueCommand("XACT", 25);
            return super.data();
        }
 

Author:

Max Spivak, Bill Shannon, Dean Gibson (DIGEST-MD5 authentication), Luís Serralheiro (NTLM authentication)

See Also:

ConnectionEvent, TransportEvent

Field Summary

Fields inherited from class jakarta.mail.Service

debug, session, url

Constructor Summary

Constructors

Modifier	Constructor and Description
	SMTPTransport(Session session, URLName urlname) Constructor that takes a Session object and a URLName that represents a specific SMTP server.
protected	SMTPTransport(Session session, URLName urlname, String name, boolean isSSL) Constructor used by this class and by SMTPSSLTransport subclass.

Method Summary

Modifier and Type	Method and Description
protected OutputStream	bdat() Return a stream that will use the SMTP BDAT command to send data.
protected void	checkConnected() Check if we're in the connected state.
void	close() Close the Transport and terminate the connection to the server.
void	connect(Socket socket) Start the SMTP protocol on the given socket, which was already connected by the caller.
protected OutputStream	data() Send the DATA command to the SMTP host and return an OutputStream to which the data is to be written.
protected boolean	ehlo(String domain) Issue the EHLO command.
protected void	finalize() Stop the event dispatcher thread so the queue can be garbage collected.
protected void	finishBdat() Terminate the sent data.
protected void	finishData() Terminate the sent data.
String	getAuthorizationId() Gets the authorization ID to be used for authentication.
String	getExtensionParameter(String ext) Return the parameter the server provided for the specified service extension, or null if the extension isn't supported.
int	getLastReturnCode() Return the return code from the last response we got from the server.
String	getLastServerResponse() Return the last response we got from the server.
String	getLocalHost() Get the name of the local host, for use in the EHLO and HELO commands.
boolean	getNoopStrict() Is the NOOP command required to return a response code of 250 to indicate success?
String	getNTLMDomain() Gets the NTLM domain to be used for NTLM authentication.
boolean	getReportSuccess() Should we report even successful sends by throwing an exception? If so, a SendFailedException will always be thrown and an SMTPAddressSucceededException will be included in the exception chain for each successful address, along with the usual SMTPAddressFailedException for each unsuccessful address.
boolean	getRequireStartTLS() Should we require the STARTTLS command to secure the connection?
boolean	getSASLEnabled() Is SASL authentication enabled?
String[]	getSASLMechanisms() Get the list of SASL mechanisms to consider if SASL authentication is enabled.
String	getSASLRealm() Gets the SASL realm to be used for DIGEST-MD5 authentication.
boolean	getStartTLS() Should we use the STARTTLS command to secure the connection if the server supports it?
boolean	getUseCanonicalHostName() Should SASL use the canonical host name?
boolean	getUseRset() Should we use the RSET command instead of the NOOP command in the @{link #isConnected isConnected} method?
protected void	helo(String domain) Issue the HELO command.
boolean	isConnected() Check whether the transport is connected.
boolean	isSSL() Is this Transport using SSL to connect to the server?
void	issueCommand(String cmd, int expect) Send the command to the server.
protected void	mailFrom() Issue the MAIL FROM: command to start sending a message.
protected void	notifyTransportListeners(int type, Address[] validSent, Address[] validUnsent, Address[] invalid, Message msg) Notify all TransportListeners.
protected boolean	protocolConnect(String host, int port, String user, String password) Performs the actual protocol-specific connection attempt.
protected void	rcptTo() Sends each address to the SMTP host using the RCPT TO: command and copies the address either into the validSentAddr or invalidAddr arrays.
protected int	readServerResponse() Reads server reponse returning the returnCode as the number.
protected void	sendCommand(String cmd) Sends command cmd to the server terminating it with CRLF.
void	sendMessage(Message message, Address[] addresses) Send the Message to the specified list of addresses.
void	setAuthorizationID(String authzid) Sets the authorization ID to be used for authentication.
void	setLocalHost(String localhost) Set the name of the local host, for use in the EHLO and HELO commands.
void	setNoopStrict(boolean noopStrict) Set whether the NOOP command is required to return a response code of 250 to indicate success.
void	setNTLMDomain(String ntlmDomain) Sets the NTLM domain to be used for NTLM authentication.
void	setReportSuccess(boolean reportSuccess) Set whether successful sends should be reported by throwing an exception.
void	setRequireStartTLS(boolean requireStartTLS) Set whether the STARTTLS command should be required.
void	setSASLEnabled(boolean enableSASL) Set whether SASL authentication is enabled.
void	setSASLMechanisms(String[] mechanisms) Set the list of SASL mechanisms to consider if SASL authentication is enabled.
void	setSASLRealm(String saslRealm) Sets the SASL realm to be used for DIGEST-MD5 authentication.
void	setStartTLS(boolean useStartTLS) Set whether the STARTTLS command should be used.
void	setUseCanonicalHostName(boolean useCanonicalHostName) Set whether SASL should use the canonical host name.
void	setUseRset(boolean useRset) Set whether the RSET command should be used instead of the NOOP command in the @{link #isConnected isConnected} method.
protected int	simpleCommand(byte[] cmd) Send the command to the server and return the response code from the server.
int	simpleCommand(String cmd) Send the command to the server and return the response code from the server.
protected void	startTLS() Issue the STARTTLS command and switch the socket to TLS mode if it succeeds.
protected boolean	supportsAuthentication(String auth) Does the server we're connected to support the specified authentication mechanism? Uses the extension information returned by the server from the EHLO command.
boolean	supportsExtension(String ext) Return true if the SMTP server supports the specified service extension.
protected static String	xtext(String s) Convert a string to RFC 1891 xtext format.
protected static String	xtext(String s, boolean utf8) Like xtext(s), but allow UTF-8 strings.

Methods inherited from class jakarta.mail.Transport

addTransportListener, removeTransportListener, send, send, send, send

Methods inherited from class jakarta.mail.Service

addConnectionListener, connect, connect, connect, connect, getURLName, notifyConnectionListeners, queueEvent, removeConnectionListener, setConnected, setURLName, toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SMTPTransport

public SMTPTransport(Session session,
                     URLName urlname)

Constructor that takes a Session object and a URLName that represents a specific SMTP server.

Parameters:

session - the Session

urlname - the URLName of this transport

SMTPTransport

protected SMTPTransport(Session session,
                        URLName urlname,
                        String name,
                        boolean isSSL)

Constructor used by this class and by SMTPSSLTransport subclass.

Parameters:

session - the Session

urlname - the URLName of this transport

name - the protocol name of this transport

isSSL - use SSL to connect?

Method Detail

getLocalHost

public String getLocalHost()

Get the name of the local host, for use in the EHLO and HELO commands. The property mail.smtp.localhost overrides mail.smtp.localaddress, which overrides what InetAddress would tell us.

Returns:

the local host name

setLocalHost

public void setLocalHost(String localhost)

Set the name of the local host, for use in the EHLO and HELO commands.

Parameters:

localhost - the local host name

Since:

JavaMail 1.3.1

connect

public void connect(Socket socket)
             throws MessagingException

Start the SMTP protocol on the given socket, which was already connected by the caller. Useful for implementing the SMTP ATRN command (RFC 2645) where an existing connection is used when the server reverses roles and becomes the client.

Parameters:

socket - the already connected socket

Throws:

MessagingException - for failures

Since:

JavaMail 1.3.3

getAuthorizationId

public String getAuthorizationId()

Gets the authorization ID to be used for authentication.

Returns:

the authorization ID to use for authentication.

Since:

JavaMail 1.4.4

setAuthorizationID

public void setAuthorizationID(String authzid)

Sets the authorization ID to be used for authentication.

Parameters:

authzid - the authorization ID to use for authentication.

Since:

JavaMail 1.4.4

getSASLEnabled

public boolean getSASLEnabled()

Is SASL authentication enabled?

Returns:

true if SASL authentication is enabled

Since:

JavaMail 1.4.4

setSASLEnabled

public void setSASLEnabled(boolean enableSASL)

Set whether SASL authentication is enabled.

Parameters:

enableSASL - should we enable SASL authentication?

Since:

JavaMail 1.4.4

getSASLRealm

public String getSASLRealm()

Gets the SASL realm to be used for DIGEST-MD5 authentication.

Returns:

the name of the realm to use for SASL authentication.

Since:

JavaMail 1.3.1

setSASLRealm

public void setSASLRealm(String saslRealm)

Sets the SASL realm to be used for DIGEST-MD5 authentication.

Parameters:

saslRealm - the name of the realm to use for SASL authentication.

Since:

JavaMail 1.3.1

getUseCanonicalHostName

public boolean getUseCanonicalHostName()

Should SASL use the canonical host name?

Returns:

true if SASL should use the canonical host name

Since:

JavaMail 1.5.2

setUseCanonicalHostName

public void setUseCanonicalHostName(boolean useCanonicalHostName)

Set whether SASL should use the canonical host name.

Parameters:

useCanonicalHostName - should SASL use the canonical host name?

Since:

JavaMail 1.5.2

getSASLMechanisms

public String[] getSASLMechanisms()

Get the list of SASL mechanisms to consider if SASL authentication is enabled. If the list is empty or null, all available SASL mechanisms are considered.

Returns:

the array of SASL mechanisms to consider

Since:

JavaMail 1.4.4

setSASLMechanisms

public void setSASLMechanisms(String[] mechanisms)

Set the list of SASL mechanisms to consider if SASL authentication is enabled. If the list is empty or null, all available SASL mechanisms are considered.

Parameters:

mechanisms - the array of SASL mechanisms to consider

Since:

JavaMail 1.4.4

getNTLMDomain

public String getNTLMDomain()

Gets the NTLM domain to be used for NTLM authentication.

Returns:

the name of the domain to use for NTLM authentication.

Since:

JavaMail 1.4.3

setNTLMDomain

public void setNTLMDomain(String ntlmDomain)

Sets the NTLM domain to be used for NTLM authentication.

Parameters:

ntlmDomain - the name of the domain to use for NTLM authentication.

Since:

JavaMail 1.4.3

getReportSuccess

public boolean getReportSuccess()

Should we report even successful sends by throwing an exception? If so, a SendFailedException will always be thrown and an SMTPAddressSucceededException will be included in the exception chain for each successful address, along with the usual SMTPAddressFailedException for each unsuccessful address.

Returns:

true if an exception will be thrown on successful sends.

Since:

JavaMail 1.3.2

setReportSuccess

public void setReportSuccess(boolean reportSuccess)

Set whether successful sends should be reported by throwing an exception.

Parameters:

reportSuccess - should we throw an exception on success?

Since:

JavaMail 1.3.2

getStartTLS

public boolean getStartTLS()

Should we use the STARTTLS command to secure the connection if the server supports it?

Returns:

true if the STARTTLS command will be used

Since:

JavaMail 1.3.2

setStartTLS

public void setStartTLS(boolean useStartTLS)

Set whether the STARTTLS command should be used.

Parameters:

useStartTLS - should we use the STARTTLS command?

Since:

JavaMail 1.3.2

getRequireStartTLS

public boolean getRequireStartTLS()

Should we require the STARTTLS command to secure the connection?

Returns:

true if the STARTTLS command will be required

Since:

JavaMail 1.4.2

setRequireStartTLS

public void setRequireStartTLS(boolean requireStartTLS)

Set whether the STARTTLS command should be required.

Parameters:

requireStartTLS - should we require the STARTTLS command?

Since:

JavaMail 1.4.2

isSSL

public boolean isSSL()

Is this Transport using SSL to connect to the server?

Returns:

true if using SSL

Since:

JavaMail 1.4.6

getUseRset

public boolean getUseRset()

Should we use the RSET command instead of the NOOP command in the @{link #isConnected isConnected} method?

Returns:

true if RSET will be used

Since:

JavaMail 1.4

setUseRset

public void setUseRset(boolean useRset)

Set whether the RSET command should be used instead of the NOOP command in the @{link #isConnected isConnected} method.

Parameters:

useRset - should we use the RSET command?

Since:

JavaMail 1.4

getNoopStrict

public boolean getNoopStrict()

Is the NOOP command required to return a response code of 250 to indicate success?

Returns:

true if NOOP must return 250

Since:

JavaMail 1.4.3

setNoopStrict

public void setNoopStrict(boolean noopStrict)

Set whether the NOOP command is required to return a response code of 250 to indicate success.

Parameters:

noopStrict - is NOOP required to return 250?

Since:

JavaMail 1.4.3

getLastServerResponse

public String getLastServerResponse()

Return the last response we got from the server. A failed send is often followed by an RSET command, but the response from the RSET command is not saved. Instead, this returns the response from the command before the RSET command.

Returns:

last response from server

Since:

JavaMail 1.3.2

getLastReturnCode

public int getLastReturnCode()

Return the return code from the last response we got from the server.

Returns:

return code from last response from server

Since:

JavaMail 1.4.1

protocolConnect

protected boolean protocolConnect(String host,
                                  int port,
                                  String user,
                                  String password)
                           throws MessagingException

Performs the actual protocol-specific connection attempt. Will attempt to connect to "localhost" if the host was null.

Unless mail.smtp.ehlo is set to false, we'll try to identify ourselves using the ESMTP command EHLO. If mail.smtp.auth is set to true, we insist on having a username and password, and will try to authenticate ourselves if the server supports the AUTH extension (RFC 2554).

Overrides:

protocolConnect in class Service

Parameters:

host - the name of the host to connect to

port - the port to use (-1 means use default port)

user - the name of the user to login as

password - the user's password

Returns:

true if connection successful, false if authentication failed

Throws:

MessagingException - for non-authentication failures

sendMessage

public void sendMessage(Message message,
                        Address[] addresses)
                 throws MessagingException,
                        SendFailedException

Send the Message to the specified list of addresses.

If all the addresses succeed the SMTP check using the RCPT TO: command, we attempt to send the message. A TransportEvent of type MESSAGE_DELIVERED is fired indicating the successful submission of a message to the SMTP host.

If some of the addresses fail the SMTP check, and the mail.smtp.sendpartial property is not set, sending is aborted. The TransportEvent of type MESSAGE_NOT_DELIVERED is fired containing the valid and invalid addresses. The SendFailedException is also thrown.

If some of the addresses fail the SMTP check, and the mail.smtp.sendpartial property is set to true, the message is sent. The TransportEvent of type MESSAGE_PARTIALLY_DELIVERED is fired containing the valid and invalid addresses. The SMTPSendFailedException is also thrown.

MessagingException is thrown if the message can't write out an RFC822-compliant stream using its writeTo method.

Specified by:

sendMessage in class Transport

Parameters:

message - The MimeMessage to be sent

addresses - List of addresses to send this message to

Throws:

SMTPSendFailedException - if the send failed because of an SMTP command error

SendFailedException - if the send failed because of invalid addresses.

MessagingException - if the connection is dead or not in the connected state or if the message is not a MimeMessage.

See Also:

TransportEvent

close

public void close()
           throws MessagingException

Close the Transport and terminate the connection to the server.

Specified by:

close in interface AutoCloseable

Overrides:

close in class Service

Throws:

MessagingException - for errors while closing

See Also:

ConnectionEvent

isConnected

public boolean isConnected()

Check whether the transport is connected. Override superclass method, to actually ping our server connection.

Overrides:

isConnected in class Service

Returns:

true if the service is connected, false if it is not connected

notifyTransportListeners

protected void notifyTransportListeners(int type,
                                        Address[] validSent,
                                        Address[] validUnsent,
                                        Address[] invalid,
                                        Message msg)

Notify all TransportListeners. Keep track of whether notification has been done so as to only notify once per send.

Overrides:

notifyTransportListeners in class Transport

Parameters:

type - the TransportEvent type

validSent - valid addresses to which message was sent

validUnsent - valid addresses to which message was not sent

invalid - the invalid addresses

msg - the message

Since:

JavaMail 1.4.2

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Service

Stop the event dispatcher thread so the queue can be garbage collected.

Overrides:

finalize in class Service

Throws:

Throwable

helo

protected void helo(String domain)
             throws MessagingException

Issue the HELO command.

Parameters:

domain - our domain

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

ehlo

protected boolean ehlo(String domain)
                throws MessagingException

Issue the EHLO command. Collect the returned list of service extensions.

Parameters:

domain - our domain

Returns:

true if command succeeds

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

mailFrom

protected void mailFrom()
                 throws MessagingException

Issue the MAIL FROM: command to start sending a message.

Gets the sender's address in the following order:

1. SMTPMessage.getEnvelopeFrom()
2. mail.smtp.from property
3. From: header in the message
4. System username using the InternetAddress.getLocalAddress() method

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

rcptTo

protected void rcptTo()
               throws MessagingException

Sends each address to the SMTP host using the RCPT TO: command and copies the address either into the validSentAddr or invalidAddr arrays. Sets the sendFailed flag to true if any addresses failed.

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

data

protected OutputStream data()
                     throws MessagingException

Send the DATA command to the SMTP host and return an OutputStream to which the data is to be written.

Returns:

the stream to write to

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

finishData

protected void finishData()
                   throws IOException,
                          MessagingException

Terminate the sent data.

Throws:

IOException - for I/O errors

MessagingException - for other failures

Since:

JavaMail 1.4.1

bdat

protected OutputStream bdat()
                     throws MessagingException

Return a stream that will use the SMTP BDAT command to send data.

Returns:

the stream to write to

Throws:

MessagingException - for failures

Since:

JavaMail 1.6.0

finishBdat

protected void finishBdat()
                   throws IOException,
                          MessagingException

Terminate the sent data.

Throws:

IOException - for I/O errors

MessagingException - for other failures

Since:

JavaMail 1.6.0

startTLS

protected void startTLS()
                 throws MessagingException

Issue the STARTTLS command and switch the socket to TLS mode if it succeeds.

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

issueCommand

public void issueCommand(String cmd,
                         int expect)
                  throws MessagingException

Send the command to the server. If the expected response code is not received, throw a MessagingException.

Parameters:

cmd - the command to send

expect - the expected response code (-1 means don't care)

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

simpleCommand

public int simpleCommand(String cmd)
                  throws MessagingException

Send the command to the server and return the response code from the server.

Parameters:

cmd - the command

Returns:

the response code

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

simpleCommand

protected int simpleCommand(byte[] cmd)
                     throws MessagingException

Send the command to the server and return the response code from the server.

Parameters:

cmd - the command

Returns:

the response code

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

sendCommand

protected void sendCommand(String cmd)
                    throws MessagingException

Sends command cmd to the server terminating it with CRLF.

Parameters:

cmd - the command

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

readServerResponse

protected int readServerResponse()
                          throws MessagingException

Reads server reponse returning the returnCode as the number. Returns -1 on failure. Sets lastServerResponse and lastReturnCode.

Returns:

server response code

Throws:

MessagingException - for failures

Since:

JavaMail 1.4.1

checkConnected

protected void checkConnected()

Check if we're in the connected state. Don't bother checking whether the server is still alive, that will be detected later.

Throws:

IllegalStateException - if not connected

Since:

JavaMail 1.4.1

supportsExtension

public boolean supportsExtension(String ext)

Return true if the SMTP server supports the specified service extension. Extensions are reported as results of the EHLO command when connecting to the server. See RFC 1869 and other RFCs that define specific extensions.

Parameters:

ext - the service extension name

Returns:

true if the extension is supported

Since:

JavaMail 1.3.2

getExtensionParameter

public String getExtensionParameter(String ext)

Return the parameter the server provided for the specified service extension, or null if the extension isn't supported.

Parameters:

ext - the service extension name

Returns:

the extension parameter

Since:

JavaMail 1.3.2

supportsAuthentication

protected boolean supportsAuthentication(String auth)

Does the server we're connected to support the specified authentication mechanism? Uses the extension information returned by the server from the EHLO command.

Parameters:

auth - the authentication mechanism

Returns:

true if the authentication mechanism is supported

Since:

JavaMail 1.4.1

xtext

protected static String xtext(String s)

Convert a string to RFC 1891 xtext format.

     xtext = *( xchar / hexchar )

     xchar = any ASCII CHAR between "!" (33) and "~" (126) inclusive,
          except for "+" and "=".

 ; "hexchar"s are intended to encode octets that cannot appear
 ; as ASCII characters within an esmtp-value.

     hexchar = ASCII "+" immediately followed by two upper case
          hexadecimal digits
 

Parameters:

s - the string to convert

Returns:

the xtext format string

Since:

JavaMail 1.4.1

xtext

protected static String xtext(String s,
                              boolean utf8)

Like xtext(s), but allow UTF-8 strings.

Parameters:

s - the string to convert

utf8 - convert string to UTF-8 first?

Returns:

the xtext format string

Since:

JavaMail 1.6.0