de.trantor.mail
Class SmtpClient

java.lang.Object
  |
  +--de.trantor.mail.SmtpClient

public class SmtpClient

extends java.lang.Object

Encapsulates the SMTP protocol, as specified in RFC 822. This class is used to send messages across the internet. After an SMTP session has been established using the open() method, an arbitrary number of messages can be sent using the two variants of the sendMessage() method. One variant sends a message already contained in an envelope, the other one creates the envelope on-the-fly. Each SMTP session should be terminated by a call to the close() method.

See Also:

Pop3Client, Envelope, Message

Constructor Summary

SmtpClient(Connection connection, java.lang.String localhost)

SmtpClient(java.lang.String localhost)
Constructs an instance of the SMTP client.

Method Summary

void	close() Ends the SMTP session.
boolean	connected() Returns true, if the client is currently connected to an SMTP server.
boolean	getDebug() Queries whether the SMTP client is in debug mode or not.
void	open(java.lang.String host) Opens a connection to the given server at the well-known port 25.
void	open(java.lang.String host, int port, boolean ssl, java.lang.String user, java.lang.String pass) Opens a connection to the given server at the given port and using secure sockets, if desired.
void	sendMessage(Envelope envelope) Sends a message.
void	sendMessage(Message message) Sends a message.
void	setDebug(boolean value) Controls printing of protocol debugging information to standard output.

Methods inherited from class java.lang.Object

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

Constructor Detail

SmtpClient

public SmtpClient(java.lang.String localhost)

Constructs an instance of the SMTP client. The hostname of the local (!) machine is needed during the initial handshaking of the SMTP protocol. Unfortunately J2ME/MIDP provides no means to find out the name or IP of the local host, so we have to specify it here to be compatible to all possible environments.

Some explanation might be handy here, since the localhost parameter seems to be a source of confusion: Actually, there is *some* value needed during initial SMTP handshaking. The SMTP specification says that this value should identify the client machine, but most servers don't seem to actually use the passed value, but check the client's IP number instead (if it checks something at all). Yet, it is possible that there are hosts that allow access only to "known" clients based on this value. So, in most cases passing null or "localhost" will be ok. If you run into problems with a specific host, try to pass a sensible value here.

SmtpClient

public SmtpClient(Connection connection,
                  java.lang.String localhost)

Method Detail

open

public void open(java.lang.String host)
          throws java.io.IOException,
                 MailException

Opens a connection to the given server at the well-known port 25. No username or password is required, which is ok for most SMTP servers, since SMTP is basically not password-protected.

java.io.IOException

MailException

See Also:

open(String, int, boolean, String, String), close(), connected()

open

public void open(java.lang.String host,
                 int port,
                 boolean ssl,
                 java.lang.String user,
                 java.lang.String pass)
          throws java.io.IOException,
                 MailException

Opens a connection to the given server at the given port and using secure sockets, if desired. In addition, authentication is tried if both the user and the pass parameters are non-null.

A note on authentication: It requires an ESMTP server that actually allows authentication. Only the PLAIN method is supported, which expects the username and password information to be passed in one MIME-encoded string. Other methods are too costly in terms of code, so they're not supported (yet).

java.io.IOException

MailException

See Also:

open(String), close(), connected()

close

public void close()
           throws java.io.IOException,
                  MailException

Ends the SMTP session. This method should be called after access to the SMTP server, in order to close the underlying socket connection and thus free resources.

java.io.IOException

MailException

See Also:

open(java.lang.String), connected()

connected

public boolean connected()

Returns true, if the client is currently connected to an SMTP server.

See Also:

open(java.lang.String), close()

sendMessage

public void sendMessage(Message message)
                 throws java.io.IOException,
                        MailException

Sends a message. This is a convenience method that automatically creates an envelope for the message before sending it to the SMTP server. Note that the message headers must contain a valid "From:" field and at least one of "To:", "CC:" or "BCC:" for the method to work properly. This is because the method attempts to copy envelope addressing information from the message headers.

java.io.IOException

MailException

See Also:

sendMessage(de.trantor.mail.Envelope), Envelope, Message

sendMessage

public void sendMessage(Envelope envelope)
                 throws java.io.IOException,
                        MailException

Sends a message. This method is used to send a message that is already enclosed in an envelope. Note that the envelope must contain a valid sender field and at least one recipient for the method to work properly.

java.io.IOException

MailException

See Also:

sendMessage(de.trantor.mail.Message), Envelope, Message

getDebug

public boolean getDebug()

Queries whether the SMTP client is in debug mode or not.

setDebug

public void setDebug(boolean value)

Controls printing of protocol debugging information to standard output.