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(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.

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.
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).

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.
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.
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.
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.