| org.apache.commons.net.smtp.SMTP
 org.apache.commons.net.smtp.SMTPClient
| SMTPClient | | public class SMTPClient extends SMTP (Code) | | SMTPClient encapsulates all the functionality necessary to send files
through an SMTP server. This class takes care of all
low level details of interacting with an SMTP server and provides
a convenient higher level interface. As with all classes derived
from
org.apache.commons.net.SocketClient ,
you must first connect to the server with
org.apache.commons.net.SocketClient.connect connect before doing anything, and finally
org.apache.commons.net.SocketClient.disconnect disconnect after you're completely finished interacting with the server.
Then you need to check the SMTP reply code to see if the connection
was successful. For example:
try {
int reply;
client.connect("mail.foobar.com");
System.out.print(client.getReplyString());
// After connection attempt, you should check the reply code to verify
// success.
reply = client.getReplyCode();
if(!SMTPReply.isPositiveCompletion(reply)) {
client.disconnect();
System.err.println("SMTP server refused connection.");
System.exit(1);
}
// Do useful stuff here.
...
} catch(IOException e) {
if(client.isConnected()) {
try {
client.disconnect();
} catch(IOException f) {
// do nothing
}
}
System.err.println("Could not connect to server.");
e.printStackTrace();
System.exit(1);
}
Immediately after connecting is the only real time you need to check the
reply code (because connect is of type void). The convention for all the
SMTP command methods in SMTPClient is such that they either return a
boolean value or some other value.
The boolean methods return true on a successful completion reply from
the SMTP server and false on a reply resulting in an error condition or
failure. The methods returning a value other than boolean return a value
containing the higher level data produced by the SMTP command, or null if a
reply resulted in an error condition or failure. If you want to access
the exact SMTP reply code causing a success or failure, you must call
org.apache.commons.net.smtp.SMTP.getReplyCode getReplyCode after
a success or failure.
You should keep in mind that the SMTP server may choose to prematurely
close a connection for various reasons. The SMTPClient class will detect a
premature SMTP server connection closing when it receives a
org.apache.commons.net.smtp.SMTPReply.SERVICE_NOT_AVAILABLE SMTPReply.SERVICE_NOT_AVAILABLE response to a command.
When that occurs, the method encountering that reply will throw
an
org.apache.commons.net.smtp.SMTPConnectionClosedException .
SMTPConectionClosedException
is a subclass of IOException and therefore need not be
caught separately, but if you are going to catch it separately, its
catch block must appear before the more general IOException
catch block. When you encounter an
org.apache.commons.net.smtp.SMTPConnectionClosedException , you must disconnect the connection with
SMTPClient.disconnect disconnect() to properly clean up the
system resources used by SMTPClient. Before disconnecting, you may check
the last reply code and text with
org.apache.commons.net.smtp.SMTP.getReplyCode getReplyCode ,
org.apache.commons.net.smtp.SMTP.getReplyString getReplyString ,
and
org.apache.commons.net.smtp.SMTP.getReplyStrings getReplyStrings .
Rather than list it separately for each method, we mention here that
every method communicating with the server and throwing an IOException
can also throw a
org.apache.commons.net.MalformedServerReplyException , which is a subclass
of IOException. A MalformedServerReplyException will be thrown when
the reply received from the server deviates enough from the protocol
specification that it cannot be interpreted in a useful manner despite
attempts to be as lenient as possible.
author:
Daniel F. Savarese
See Also: SMTP
See Also: SimpleSMTPHeader
See Also: RelayPath
See Also: SMTPConnectionClosedException
See Also: org.apache.commons.net.MalformedServerReplyException |
| Method Summary | |
| public boolean | addRecipient(RelayPath path)
Add a recipient for a message using the SMTP RCPT command, specifying
a forward relay path. | | public boolean | addRecipient(String address)
Add a recipient for a message using the SMTP RCPT command, the
recipient's email address. | | public boolean | completePendingCommand()
At least one SMTPClient method (
SMTPClient.sendMessageData sendMessageData )
does not complete the entire sequence of SMTP commands to complete a
transaction. | | public String | listHelp()
Fetches the system help information from the server and returns the
full string.
The system help string obtained from the server. | | public String | listHelp(String command)
Fetches the help information for a given command from the server and
returns the full string.
Parameters:
command - The command on which to ask for help. | | public boolean | login(String hostname)
Login to the SMTP server by sending the HELO command with the
given hostname as an argument. | | public boolean | login()
Login to the SMTP server by sending the HELO command with the
client hostname as an argument. | | public boolean | logout()
Logout of the SMTP server by sending the QUIT command.
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. | | public boolean | reset()
Aborts the current mail transaction, resetting all server stored
sender, recipient, and mail data, cleaing all buffers and tables.
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. | | public Writer | sendMessageData()
Send the SMTP DATA command in preparation to send an email message.
This method returns a DotTerminatedMessageWriter instance to which
the message can be written. | | public boolean | sendNoOp()
Sends a NOOP command to the SMTP server. | | public boolean | sendShortMessageData(String message)
A convenience method for sending short messages. | | public boolean | sendSimpleMessage(String sender, String recipient, String message)
A convenience method for a sending short email without having to
explicitly set the sender and recipient(s). | | public boolean | sendSimpleMessage(String sender, String[] recipients, String message)
A convenience method for a sending short email without having to
explicitly set the sender and recipient(s). | | public boolean | setSender(RelayPath path)
Set the sender of a message using the SMTP MAIL command, specifying
a reverse relay path. | | public boolean | setSender(String address)
Set the sender of a message using the SMTP MAIL command, specifying
the sender's email address. | | public boolean | verify(String username)
Verify that a username or email address is valid, i.e., that mail
can be delivered to that mailbox on the server.
Parameters:
username - The username or email address to validate. |
| addRecipient | | public boolean addRecipient(RelayPath path) throws IOException(Code) | | Add a recipient for a message using the SMTP RCPT command, specifying
a forward relay path. The sender must be set first before any
recipients may be specified, otherwise the mail server will reject
your commands.
Parameters:
path - The forward relay path pointing to the recipient. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| addRecipient | | public boolean addRecipient(String address) throws IOException(Code) | | Add a recipient for a message using the SMTP RCPT command, the
recipient's email address. The sender must be set first before any
recipients may be specified, otherwise the mail server will reject
your commands.
Parameters:
address - The recipient's email address. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| completePendingCommand | | public boolean completePendingCommand() throws IOException(Code) | | At least one SMTPClient method (
SMTPClient.sendMessageData sendMessageData )
does not complete the entire sequence of SMTP commands to complete a
transaction. These types of commands require some action by the
programmer after the reception of a positive intermediate command.
After the programmer's code completes its actions, it must call this
method to receive the completion reply from the server and verify the
success of the entire transaction.
For example,
writer = client.sendMessage();
if(writer == null) // failure
return false;
header =
new SimpleSMTPHeader("foobar@foo.com", "foo@foobar.com", "Re: Foo");
writer.write(header.toString());
writer.write("This is just a test");
writer.close();
if(!client.completePendingCommand()) // failure
return false;
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| listHelp | | public String listHelp() throws IOException(Code) | | Fetches the system help information from the server and returns the
full string.
The system help string obtained from the server. null if theinformation could not be obtained.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| listHelp | | public String listHelp(String command) throws IOException(Code) | | Fetches the help information for a given command from the server and
returns the full string.
Parameters:
command - The command on which to ask for help. The command help string obtained from the server. null if theinformation could not be obtained.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| login | | public boolean login(String hostname) throws IOException(Code) | | Login to the SMTP server by sending the HELO command with the
given hostname as an argument. Before performing any mail commands,
you must first login.
Parameters:
hostname - The hostname with which to greet the SMTP server. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| login | | public boolean login() throws IOException(Code) | | Login to the SMTP server by sending the HELO command with the
client hostname as an argument. Before performing any mail commands,
you must first login.
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| logout | | public boolean logout() throws IOException(Code) | | Logout of the SMTP server by sending the QUIT command.
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| reset | | public boolean reset() throws IOException(Code) | | Aborts the current mail transaction, resetting all server stored
sender, recipient, and mail data, cleaing all buffers and tables.
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| sendMessageData | | public Writer sendMessageData() throws IOException(Code) | | Send the SMTP DATA command in preparation to send an email message.
This method returns a DotTerminatedMessageWriter instance to which
the message can be written. Null is returned if the DATA command
fails.
You must not issue any commands to the SMTP server (i.e., call any
(other methods) until you finish writing to the returned Writer
instance and close it. The SMTP protocol uses the same stream for
issuing commands as it does for returning results. Therefore the
returned Writer actually writes directly to the SMTP connection.
After you close the writer, you can execute new commands. If you
do not follow these requirements your program will not work properly.
You can use the provided
org.apache.commons.net.smtp.SimpleSMTPHeader class to construct a bare minimum header.
To construct more complicated headers you should
refer to RFC 822. When the Java Mail API is finalized, you will be
able to use it to compose fully compliant Internet text messages.
The DotTerminatedMessageWriter takes care of doubling line-leading
dots and ending the message with a single dot upon closing, so all
you have to worry about is writing the header and the message.
Upon closing the returned Writer, you need to call
SMTPClient.completePendingCommand completePendingCommand() to finalize the transaction and verify its success or failure from
the server reply.
A DotTerminatedMessageWriter to which the message (includingheader) can be written. Returns null if the command fails.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| sendNoOp | | public boolean sendNoOp() throws IOException(Code) | | Sends a NOOP command to the SMTP server. This is useful for preventing
server timeouts.
True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| sendShortMessageData | | public boolean sendShortMessageData(String message) throws IOException(Code) | | A convenience method for sending short messages. This method fetches
the Writer returned by
SMTPClient.sendMessageData sendMessageData() and writes the specified String to it. After writing the message,
this method calls
SMTPClient.completePendingCommand completePendingCommand() to finalize the transaction and returns
its success or failure.
Parameters:
message - The short email message to send. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| sendSimpleMessage | | public boolean sendSimpleMessage(String sender, String recipient, String message) throws IOException(Code) | | A convenience method for a sending short email without having to
explicitly set the sender and recipient(s). This method
sets the sender and recipient using
SMTPClient.setSender setSender and
SMTPClient.addRecipient addRecipient , and then sends the
message using
SMTPClient.sendShortMessageData sendShortMessageData .
Parameters:
sender - The email address of the sender.
Parameters:
recipient - The email address of the recipient.
Parameters:
message - The short email message to send. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| sendSimpleMessage | | public boolean sendSimpleMessage(String sender, String[] recipients, String message) throws IOException(Code) | | A convenience method for a sending short email without having to
explicitly set the sender and recipient(s). This method
sets the sender and recipients using
SMTPClient.setSender setSender and
SMTPClient.addRecipient addRecipient , and then sends the
message using
SMTPClient.sendShortMessageData sendShortMessageData .
Parameters:
sender - The email address of the sender.
Parameters:
recipients - An array of recipient email addresses.
Parameters:
message - The short email message to send. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| setSender | | public boolean setSender(RelayPath path) throws IOException(Code) | | Set the sender of a message using the SMTP MAIL command, specifying
a reverse relay path. The sender must be set first before any
recipients may be specified, otherwise the mail server will reject
your commands.
Parameters:
path - The reverse relay path pointing back to the sender. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| setSender | | public boolean setSender(String address) throws IOException(Code) | | Set the sender of a message using the SMTP MAIL command, specifying
the sender's email address. The sender must be set first before any
recipients may be specified, otherwise the mail server will reject
your commands.
Parameters:
address - The sender's email address. True if successfully completed, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
| verify | | public boolean verify(String username) throws IOException(Code) | | Verify that a username or email address is valid, i.e., that mail
can be delivered to that mailbox on the server.
Parameters:
username - The username or email address to validate. True if the username is valid, false if not.
exception:
SMTPConnectionClosedException - If the SMTP server prematurely closes the connection as a resultof the client being idle or some other reason causing the serverto send SMTP reply code 421. This exception may be caught eitheras an IOException or independently as itself.
exception:
IOException - If an I/O error occurs while either sending acommand to the server or receiving a reply from the server. |
|
|