pgoldstein 2002/08/15 14:37:35 Modified: src/java/org/apache/james/smtpserver MessageSizeException.java SMTPHandler.java SMTPInputStream.java SMTPServer.java SizeLimitedInputStream.java Added: src/java/org/apache/james/smtpserver package.html Log: Added extensive commenting. Revision Changes Path 1.3 +6 -4 jakarta-james/src/java/org/apache/james/smtpserver/MessageSizeException.java Index: MessageSizeException.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/smtpserver/MessageSizeException.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- MessageSizeException.java 18 Jan 2002 02:48:37 -0000 1.2 +++ MessageSizeException.java 15 Aug 2002 21:37:34 -0000 1.3 @@ -10,16 +10,18 @@ import java.io.IOException; /** - * This exceptions is used to indicate when a new MimeMessage has exceeded + * This exception is used to indicate when a new MimeMessage has exceeded * the maximum message size for the server, as configured in the conf file. + * * @author Matthew Pangaro <[EMAIL PROTECTED]> * @version 0.5.1 */ public class MessageSizeException extends IOException { - /** Default constructor that sets the message indicating message - size error. - */ + /** + * Sole contructor for this class. This constructor sets + * the exception message to a fixed error message. + */ public MessageSizeException() { super("Message size exceeds fixed maximum message size."); } 1.22 +11 -12 jakarta-james/src/java/org/apache/james/smtpserver/SMTPHandler.java Index: SMTPHandler.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/smtpserver/SMTPHandler.java,v retrieving revision 1.21 retrieving revision 1.22 diff -u -r1.21 -r1.22 --- SMTPHandler.java 12 Aug 2002 06:19:01 -0000 1.21 +++ SMTPHandler.java 15 Aug 2002 21:37:34 -0000 1.22 @@ -31,8 +31,9 @@ import java.net.SocketException; import java.util.*; /** - * This handles an individual incoming message. It handles regular SMTP - * commands, and when it receives a message, adds it to the spool. + * Provides SMTP functionality by carrying out the server side of the SMTP + * interaction. + * * @author Serge Knystautas <[EMAIL PROTECTED]> * @author Federico Barbieri <[EMAIL PROTECTED]> * @author Jason Borden <[EMAIL PROTECTED]> @@ -113,9 +114,7 @@ // session in progress. /** - * This method is called by the ConnectionHandlerFactory with the - * handler <code>Configuration</code>. This provides the SMTPHandler - * with required configuration data. + * Pass the <code>Configuration</code> to the instance. * * @param configuration the class configurations. * @throws ConfigurationException if an error occurs @@ -135,9 +134,9 @@ } /** - * This method is called by the ConnectionHandlerFactory with the - * appropriate <code>ComponentManager</code>. This allows the SMTPHandler - * to access other system components. + * Pass the <code>ComponentManager</code> to the <code>composer</code>. + * The instance uses the specified <code>ComponentManager</code> to + * acquire the components it needs for execution. * * @param componentManager The <code>ComponentManager</code> which this * <code>Composable</code> uses. @@ -158,8 +157,8 @@ * This handler is responsible for processing connections as they occur. * * @param connection the connection - * @exception IOException if an error reading from socket occurs - * @exception ProtocolException if an error handling connection occurs + * @throws IOException if an error reading from socket occurs + * @throws ProtocolException if an error handling connection occurs */ public void handleConnection(Socket connection) throws IOException { try { 1.3 +13 -1 jakarta-james/src/java/org/apache/james/smtpserver/SMTPInputStream.java Index: SMTPInputStream.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/smtpserver/SMTPInputStream.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- SMTPInputStream.java 18 Jan 2002 02:48:37 -0000 1.2 +++ SMTPInputStream.java 15 Aug 2002 21:37:34 -0000 1.3 @@ -12,11 +12,16 @@ import java.io.InputStream; /** - * Removes the dot-stuffing happing during the SMTP DATA transport + * Removes the dot-stuffing happening during the SMTP DATA transport * * @author Serge Knystautas <[EMAIL PROTECTED]> */ public class SMTPInputStream extends FilterInputStream { + /** + * An array to hold the last two bytes read off the stream. + * This allows the stream to detect '\r\n' sequences even + * when they occur across read boundaries. + */ protected int last[] = new int[2]; public SMTPInputStream(InputStream in) { @@ -27,6 +32,8 @@ /** * Read through the stream, checking for '\r\n.' + * + * @return the byte read from the stream */ public int read() throws IOException { int b = in.read(); @@ -41,6 +48,11 @@ /** * Read through the stream, checking for '\r\n.' + * + * @param b the byte array into which the bytes will be read + * @param off the offset into the byte array where the bytes will be inserted + * @param len the maximum number of bytes to be read off the stream + * @return the number of bytes read */ public int read(byte[] b, int off, int len) throws IOException { if (b == null) { 1.9 +23 -0 jakarta-james/src/java/org/apache/james/smtpserver/SMTPServer.java Index: SMTPServer.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/smtpserver/SMTPServer.java,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- SMTPServer.java 12 Aug 2002 22:28:14 -0000 1.8 +++ SMTPServer.java 15 Aug 2002 21:37:34 -0000 1.9 @@ -18,6 +18,9 @@ import java.net.UnknownHostException; /** + * <p>Accepts SMTP connections on a server socket and dispatches them to SMTPHandlers.</p> + * + * <p>Also responsible for loading and parsing SMTP specific configuration.</p> * * @version 1.1.0, 06/02/2001 * @author Federico Barbieri <[EMAIL PROTECTED]> @@ -32,6 +35,12 @@ return new DefaultHandlerFactory( SMTPHandler.class ); } + /** + * Pass the <code>Configuration</code> to the instance. + * + * @param configuration the class configurations. + * @throws ConfigurationException if an error occurs + */ public void configure( final Configuration configuration ) throws ConfigurationException { @@ -58,6 +67,13 @@ super.configure( configuration.getChild( "handler" ) ); } + /** + * Initialize the component. Initialization includes + * allocating any resources required throughout the + * components lifecycle. + * + * @throws Exception if an error occurs + */ public void initialize() throws Exception { getLogger().info("SMTPServer init..."); super.initialize(); @@ -74,6 +90,13 @@ System.out.println("Started SMTP Server "+m_connectionName); } + /** + * The dispose operation is called at the end of a components lifecycle. + * Instances of this class use this method to release and destroy any + * resources that they own. + * + * @throws Exception if an error is encountered during shutdown + */ public void dispose() { getLogger().info( "SMTPServer dispose..." ); 1.4 +5 -3 jakarta-james/src/java/org/apache/james/smtpserver/SizeLimitedInputStream.java Index: SizeLimitedInputStream.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/smtpserver/SizeLimitedInputStream.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- SizeLimitedInputStream.java 18 Jan 2002 02:48:37 -0000 1.3 +++ SizeLimitedInputStream.java 15 Aug 2002 21:37:34 -0000 1.4 @@ -10,8 +10,9 @@ import java.io.IOException; import java.io.InputStream; -/** This class wraps an underlying input stream, limiting the allowable size - * of an incoming MimeMessage. The size limit is configured in the conf file, +/** + * Wraps an underlying input stream, limiting the allowable size + * of incoming data. The size limit is configured in the conf file, * and when the limit is reached, a MessageSizeException is thrown. * @author Matthew Pangaro <[EMAIL PROTECTED]> */ @@ -25,7 +26,8 @@ */ private long bytesread = 0; - /** InputStream that will be wrapped. + /** + * InputStream that will be wrapped. */ private InputStream in = null; 1.1 jakarta-james/src/java/org/apache/james/smtpserver/package.html Index: package.html =================================================================== <body> <p>Provides classes implementing SMTP functionality.</p> </body>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>