FileDocCategorySizeDatePackage
SMTP.javaAPI DocApache Commons NET 1.4.1 API30347Sat Dec 03 10:05:50 GMT 2005org.apache.commons.net.smtp

SMTP

public class SMTP extends org.apache.commons.net.SocketClient
SMTP provides the basic the functionality necessary to implement your own SMTP client. To derive the full benefits of the SMTP class requires some knowledge of the FTP protocol defined in RFC 821. However, there is no reason why you should have to use the SMTP class. The {@link org.apache.commons.net.smtp.SMTPClient} class, derived from SMTP, implements all the functionality required of an SMTP client. The SMTP class is made public to provide access to various SMTP constants and to make it easier for adventurous programmers (or those with special needs) to interact with the SMTP protocol and implement their own clients. A set of methods with names corresponding to the SMTP command names are provided to facilitate this interaction.

You should keep in mind that the SMTP server may choose to prematurely close a connection for various reasons. The SMTP class will detect a premature SMTP server connection closing when it receives a {@link org.apache.commons.net.smtp.SMTPReply#SERVICE_NOT_AVAILABLE SMTPReply.SERVICE_NOT_AVAILABLE } response to a command. When that occurs, the SMTP class method encountering that reply will throw an {@link 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 {@link org.apache.commons.net.smtp.SMTPConnectionClosedException} , you must disconnect the connection with {@link org.apache.commons.net.SocketClient#disconnect disconnect() } to properly clean up the system resources used by SMTP. Before disconnecting, you may check the last reply code and text with {@link #getReplyCode getReplyCode }, {@link #getReplyString getReplyString }, and {@link #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 {@link 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
SMTPClient
see
SMTPConnectionClosedException
see
org.apache.commons.net.MalformedServerReplyException

Fields Summary
public static final int
DEFAULT_PORT
The default SMTP port (25).
private static final String
__DEFAULT_ENCODING
private StringBuffer
__commandBuffer
BufferedReader
_reader
BufferedWriter
_writer
int
_replyCode
Vector
_replyLines
boolean
_newReplyString
String
_replyString
protected org.apache.commons.net.ProtocolCommandSupport
_commandSupport_
A ProtocolCommandSupport object used to manage the registering of ProtocolCommandListeners and te firing of ProtocolCommandEvents.
Constructors Summary
public SMTP()
The default SMTP constructor. Sets the default port to DEFAULT_PORT and initializes internal data structures for saving SMTP reply information.


                              
     
    
        setDefaultPort(DEFAULT_PORT);
        __commandBuffer = new StringBuffer();
        _replyLines = new Vector();
        _newReplyString = false;
        _replyString = null;
        _commandSupport_ = new ProtocolCommandSupport(this);
    
Methods Summary
private void__getReply()

        int length;

        _newReplyString = true;
        _replyLines.setSize(0);

        String line = _reader.readLine();

        if (line == null)
            throw new SMTPConnectionClosedException(
                "Connection closed without indication.");

        // In case we run into an anomaly we don't want fatal index exceptions
        // to be thrown.
        length = line.length();
        if (length < 3)
            throw new MalformedServerReplyException(
                "Truncated server reply: " + line);

        try
        {
            String code = line.substring(0, 3);
            _replyCode = Integer.parseInt(code);
        }
        catch (NumberFormatException e)
        {
            throw new MalformedServerReplyException(
                "Could not parse response code.\nServer Reply: " + line);
        }

        _replyLines.addElement(line);

        // Get extra lines if message continues.
        if (length > 3 && line.charAt(3) == '-")
        {
            do
            {
                line = _reader.readLine();

                if (line == null)
                    throw new SMTPConnectionClosedException(
                        "Connection closed without indication.");

                _replyLines.addElement(line);

                // The length() check handles problems that could arise from readLine()
                // returning too soon after encountering a naked CR or some other
                // anomaly.
            }
            while (!(line.length() >= 4 && line.charAt(3) != '-" &&
                     Character.isDigit(line.charAt(0))));
            // This is too strong a condition because a non-conforming server
            // could screw things up like ftp.funet.fi does for FTP
            // line.startsWith(code)));
        }

        if (_commandSupport_.getListenerCount() > 0)
            _commandSupport_.fireReplyReceived(_replyCode, getReplyString());

        if (_replyCode == SMTPReply.SERVICE_NOT_AVAILABLE)
            throw new SMTPConnectionClosedException(
                "SMTP response 421 received.  Server closed connection.");
    
private int__sendCommand(java.lang.String command, java.lang.String args, boolean includeSpace)

        String message;

        __commandBuffer.setLength(0);
        __commandBuffer.append(command);

        if (args != null)
        {
            if (includeSpace)
                __commandBuffer.append(' ");
            __commandBuffer.append(args);
        }

        __commandBuffer.append(SocketClient.NETASCII_EOL);

        _writer.write(message = __commandBuffer.toString());
        _writer.flush();

        if (_commandSupport_.getListenerCount() > 0)
            _commandSupport_.fireCommandSent(command, message);

        __getReply();
        return _replyCode;
    
private int__sendCommand(int command, java.lang.String args, boolean includeSpace)

        return __sendCommand(SMTPCommand._commands[command], args, includeSpace);
    
protected void_connectAction_()
Initiates control connections and gets initial reply.

        super._connectAction_();
        _reader =
            new BufferedReader(new InputStreamReader(_input_,
                                                     __DEFAULT_ENCODING));
        _writer =
            new BufferedWriter(new OutputStreamWriter(_output_,
                                                      __DEFAULT_ENCODING));
        __getReply();
    
public voidaddProtocolCommandListener(org.apache.commons.net.ProtocolCommandListener listener)
Adds a ProtocolCommandListener. Delegates this task to {@link #_commandSupport_ _commandSupport_ }.

param
listener The ProtocolCommandListener to add.

        _commandSupport_.addProtocolCommandListener(listener);
    
public intdata()
A convenience method to send the SMTP DATA command to the server, receive the reply, and return the reply code.

return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.DATA);
    
public voiddisconnect()
Closes the connection to the SMTP server and sets to null some internal data so that the memory may be reclaimed by the garbage collector. The reply text and code information from the last command is voided so that the memory it used may be reclaimed.

exception
IOException If an error occurs while disconnecting.

        super.disconnect();
        _reader = null;
        _writer = null;
        _replyString = null;
        _replyLines.setSize(0);
        _newReplyString = false;
    
public intexpn(java.lang.String name)
A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.

param
name The name to expand.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.EXPN, name);
    
public intgetReply()
Fetches a reply from the SMTP server and returns the integer reply code. After calling this method, the actual reply text can be accessed from either calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }. Only use this method if you are implementing your own SMTP client or if you need to fetch a secondary response from the SMTP server.

return
The integer value of the reply code of the fetched SMTP reply.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while receiving the server reply.

        __getReply();
        return _replyCode;
    
public intgetReplyCode()
Returns the integer value of the reply code of the last SMTP reply. You will usually only use this method after you connect to the SMTP server to check that the connection was successful since connect is of type void.

return
The integer value of the reply code of the last SMTP reply.

        return _replyCode;
    
public java.lang.StringgetReplyString()
Returns the entire text of the last SMTP server response exactly as it was received, including all end of line markers in NETASCII format.

return
The entire text from the last SMTP response as a String.

        Enumeration en;
        StringBuffer buffer;

        if (!_newReplyString)
            return _replyString;

        buffer = new StringBuffer(256);
        en = _replyLines.elements();
        while (en.hasMoreElements())
        {
            buffer.append((String)en.nextElement());
            buffer.append(SocketClient.NETASCII_EOL);
        }

        _newReplyString = false;

        return (_replyString = buffer.toString());
    
public java.lang.String[]getReplyStrings()
Returns the lines of text from the last SMTP server response as an array of strings, one entry per line. The end of line markers of each are stripped from each line.

return
The lines of text from the last SMTP response as an array.

        String[] lines;
        lines = new String[_replyLines.size()];
        _replyLines.copyInto(lines);
        return lines;
    
public inthelo(java.lang.String hostname)
A convenience method to send the SMTP HELO command to the server, receive the reply, and return the reply code.

param
hostname The hostname of the sender.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.HELO, hostname);
    
public inthelp()
A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.

return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.HELP);
    
public inthelp(java.lang.String command)
A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.

param
command The command name on which to request help.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.HELP, command);
    
public intmail(java.lang.String reversePath)
A convenience method to send the SMTP MAIL command to the server, receive the reply, and return the reply code.

param
reversePath The reverese path.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return __sendCommand(SMTPCommand.MAIL, reversePath, false);
    
public intnoop()
A convenience method to send the SMTP NOOP command to the server, receive the reply, and return the reply code.

return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.NOOP);
    
public intquit()
A convenience method to send the SMTP QUIT command to the server, receive the reply, and return the reply code.

return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.QUIT);
    
public intrcpt(java.lang.String forwardPath)
A convenience method to send the SMTP RCPT command to the server, receive the reply, and return the reply code.

param
forwardPath The forward path.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return __sendCommand(SMTPCommand.RCPT, forwardPath, false);
    
public voidremoveProtocolCommandistener(org.apache.commons.net.ProtocolCommandListener listener)
Removes a ProtocolCommandListener. Delegates this task to {@link #_commandSupport_ _commandSupport_ }.

param
listener The ProtocolCommandListener to remove.

        _commandSupport_.removeProtocolCommandListener(listener);
    
public intrset()
A convenience method to send the SMTP RSET command to the server, receive the reply, and return the reply code.

return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.RSET);
    
public intsaml(java.lang.String reversePath)
A convenience method to send the SMTP SAML command to the server, receive the reply, and return the reply code.

param
reversePath The reverese path.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.SAML, reversePath);
    
public intsend(java.lang.String reversePath)
A convenience method to send the SMTP SEND command to the server, receive the reply, and return the reply code.

param
reversePath The reverese path.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.SEND, reversePath);
    
public intsendCommand(int command, java.lang.String args)
Sends an SMTP command to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.

param
command The SMTPCommand constant corresponding to the SMTP command to send.
param
args The arguments to the SMTP command. If this parameter is set to null, then the command is sent with no argument.
return
The integer value of the SMTP reply code returned by the server in response to the command.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand._commands[command], args);
    
public intsendCommand(java.lang.String command)
Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.

param
command The text representation of the SMTP command to send.
return
The integer value of the SMTP reply code returned by the server in response to the command.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(command, null);
    
public intsendCommand(int command)
Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.

param
command The SMTPCommand constant corresponding to the SMTP command to send.
return
The integer value of the SMTP reply code returned by the server in response to the command.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(command, null);
    
public intsendCommand(java.lang.String command, java.lang.String args)
Sends an SMTP command to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling {@link #getReplyString getReplyString } or {@link #getReplyStrings getReplyStrings }.

param
command The text representation of the SMTP command to send.
param
args The arguments to the SMTP command. If this parameter is set to null, then the command is sent with no argument.
return
The integer value of the SMTP reply code returned by the server in response to the command.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return __sendCommand(command, args, true);
    
public intsoml(java.lang.String reversePath)
A convenience method to send the SMTP SOML command to the server, receive the reply, and return the reply code.

param
reversePath The reverese path.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.SOML, reversePath);
    
public intturn()
A convenience method to send the SMTP TURN command to the server, receive the reply, and return the reply code.

return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.TURN);
    
public intvrfy(java.lang.String user)
A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.

param
user The user address to verify.
return
The reply code received from the server.
exception
SMTPConnectionClosedException If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
exception
IOException If an I/O error occurs while either sending the command or receiving the server reply.

        return sendCommand(SMTPCommand.VRFY, user);