commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bre...@apache.org
Subject cvs commit: jakarta-commons-sandbox/net/src/java/org/apache/commons/net/pop3 POP3.java POP3Client.java POP3Command.java POP3MessageInfo.java POP3Reply.java
Date Wed, 03 Apr 2002 04:39:48 GMT
brekke      02/04/02 20:39:48

  Added:       net/src/java/org/apache/commons/net/pop3 POP3.java
                        POP3Client.java POP3Command.java
                        POP3MessageInfo.java POP3Reply.java
  Log:
  Moving com.oroinc.net.pop3 to org.apache.commons.net.pop3
  
  Revision  Changes    Path
  1.1                  jakarta-commons-sandbox/net/src/java/org/apache/commons/net/pop3/POP3.java
  
  Index: POP3.java
  ===================================================================
  package org.apache.commons.net.pop3;
  
  /* ====================================================================
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 2001 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   *
   * 4. The names "Apache" and "Apache Software Foundation" and
   *    "Apache Commons" must not be used to endorse or promote products
   *    derived from this software without prior written permission. For
   *    written permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache",
   *    "Apache Turbine", nor may "Apache" appear in their name, without
   *    prior written permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   */
  
  import java.io.*;
  import java.net.*;
  import java.util.*;
  
  import org.apache.commons.net.*;
  
  /***
   * The POP3 class is not meant to be used by itself and is provided
   * only so that you may easily implement your own POP3 client if 
   * you so desire.  If you have no need to perform your own implementation,
   * you should use <a href="org.apache.commons.net.pop3.POP3Client.html">POP3Client</a>.
   * <p>
   * 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 
   * <a href="org.apache.commons.net.MalformedServerReplyException.html">
   * MalformedServerReplyException </a>, 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.
   * <p>
   * <p>
   * @author Daniel F. Savarese
   * @see POP3Client
   * @see org.apache.commons.net.MalformedServerReplyException
   ***/
  
  public class POP3 extends SocketClient {
    /*** The default POP3 port.  Set to 110 according to RFC 1288. ***/
    public  static final int DEFAULT_PORT    = 110;
    /*** 
     * A constant representing the state where the client is not yet connected
     * to a POP3 server.
     ***/
    public static final int DISCONNECTED_STATE  = -1;
    /***  A constant representing the POP3 authorization state. ***/
    public static final int AUTHORIZATION_STATE = 0;
    /***  A constant representing the POP3 transaction state. ***/
    public static final int TRANSACTION_STATE   = 1;
    /***  A constant representing the POP3 update state. ***/
    public static final int UPDATE_STATE        = 2;
  
    static final String _OK    = "+OK";
    static final String _ERROR = "-ERR";
  
    private int __popState;
    private BufferedWriter __writer;
    private StringBuffer __commandBuffer;
  
    BufferedReader _reader;
    int _replyCode;
    String _lastReplyLine;
    Vector _replyLines;
  
    /***
     * A ProtocolCommandSupport object used to manage the registering of
     * ProtocolCommandListeners and te firing of ProtocolCommandEvents.
     ***/
    protected ProtocolCommandSupport _commandSupport_;
  
    /***
     * The default POP3Client constructor.  Initializes the state
     * to <code>DISCONNECTED_STATE</code>.
     ***/
    public POP3() {
      setDefaultPort(DEFAULT_PORT);
      __commandBuffer = new StringBuffer();
      __popState   = DISCONNECTED_STATE;
      _reader    = null;
      __writer    = null;
      _replyLines = new Vector();
      _commandSupport_ = new ProtocolCommandSupport(this);
    }
  
    private void __getReply() throws IOException {
      String line;
  
      _replyLines.setSize(0);
      line = _reader.readLine();
  
      if(line == null)
        throw new EOFException("Connection closed without indication.");
  
      if(line.startsWith(_OK))
        _replyCode = POP3Reply.OK;
      else if(line.startsWith(_ERROR))
        _replyCode = POP3Reply.ERROR;
      else
        throw new
  	MalformedServerReplyException(
  	      "Received invalid POP3 protocol response from server.");
  
      if(_commandSupport_.getListenerCount() > 0)
        _commandSupport_.fireReplyReceived(_replyCode, getReplyString());
  
      _replyLines.addElement(line);
      _lastReplyLine = line;
    }
  
  
    /***
     * Performs connection initialization and sets state to 
     * <code> AUTHORIZATION_STATE </code>.
     ***/
    protected void _connectAction_() throws IOException {
      super._connectAction_();
      _reader = new BufferedReader(new InputStreamReader(_input_));
      __writer = new BufferedWriter(new OutputStreamWriter(_output_));
      __getReply();
      setState(AUTHORIZATION_STATE);
    }
  
  
    /***
     * Adds a ProtocolCommandListener.  Delegates this task to
     * <a href="#_commandSupport_"> _commandSupport_ </a>.
     * <p>
     * @param listener  The ProtocolCommandListener to add.
     ***/
    public void addProtocolCommandListener(ProtocolCommandListener listener){
      _commandSupport_.addProtocolCommandListener(listener);
    }
  
    /***
     * Removes a ProtocolCommandListener.  Delegates this task to
     * <a href="#_commandSupport_"> _commandSupport_ </a>.
     * <p>
     * @param listener  The ProtocolCommandListener to remove.
     ***/
    public void removeProtocolCommandistener(ProtocolCommandListener listener){
      _commandSupport_.removeProtocolCommandListener(listener);
    }
  
  
    /***
     * Sets POP3 client state.  This must be one of the
     * <code>_STATE</code> constants.
     * <p>
     * @param state  The new state.
     ***/
    public void setState(int state) { __popState = state; }
  
  
    /***
     * Returns the current POP3 client state.
     * <p>
     * @return The current POP3 client state.
     ***/
    public int getState() { return __popState;  }
  
  
    /***
     * Retrieves the additional lines of a multi-line server reply.
     ***/
    public void getAdditionalReply() throws IOException {
      String line;
  
      line = _reader.readLine();
      while(line != null) {
        _replyLines.addElement(line);
        if(line.equals("."))
  	break;
        line = _reader.readLine();
      }
    }
  
  
    /***
     * Disconnects the client from the server, and sets the state to
     * <code> DISCONNECTED_STATE </code>.  The reply text information
     * from the last issued command is voided to allow garbage collection
     * of the memory used to store that information.
     * <p>
     * @exception IOException  If there is an error in disconnecting.
     ***/
    public void disconnect() throws IOException {
      super.disconnect();
      _reader = null;
      __writer = null;
      _lastReplyLine = null;
      _replyLines.setSize(0);
      setState(DISCONNECTED_STATE);
    }
  
  
    /***
     * Sends a command an arguments to the server and returns the reply code.
     * <p>
     * @param command  The POP3 command to send.
     * @param args     The command arguments.
     * @return  The server reply code (either POP3Reply.OK or POP3Reply.ERROR).
     ***/
    public int sendCommand(String command, String args) throws IOException {
      String message;
  
      __commandBuffer.setLength(0);
      __commandBuffer.append(command);
  
      if(args != null) {
        __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;
    }
  
    /***
     * Sends a command with no arguments to the server and returns the
     * reply code.
     * <p>
     * @param command  The POP3 command to send.
     * @return  The server reply code (either POP3Reply.OK or POP3Reply.ERROR).
     ***/
    public int sendCommand(String command) throws IOException {
      return sendCommand(command, null);
    }
  
    /***
     * Sends a command an arguments to the server and returns the reply code.
     * <p>
     * @param command  The POP3 command to send
     *                  (one of the POP3Command constants).
     * @param args     The command arguments.
     * @return  The server reply code (either POP3Reply.OK or POP3Reply.ERROR).
     ***/
    public int sendCommand(int command, String args) throws IOException {
      return sendCommand(POP3Command._commands[command], args);
    }
  
    /***
     * Sends a command with no arguments to the server and returns the
     * reply code.
     * <p>
     * @param command  The POP3 command to send
     *                  (one of the POP3Command constants).
     * @return  The server reply code (either POP3Reply.OK or POP3Reply.ERROR).
     ***/
    public int sendCommand(int command) throws IOException {
      return sendCommand(POP3Command._commands[command], null);
    }
  
  
    /***
     * Returns an array of lines received as a reply to the last command
     * sent to the server.  The lines have end of lines truncated.  If
     * the reply is a single line, but its format ndicates it should be
     * a multiline reply, then you must call
     * <a href="#getAdditionalReply"> getAdditionalReply() </a> to
     * fetch the rest of the reply, and then call <code>getReplyStrings</code>
     * again.  You only have to worry about this if you are implementing
     * your own client using the <a href="#sendComand"> sendCommand </a> methods.
     * <p>
     * @return The last server response.
     ***/
    public String[] getReplyStrings() {
      String[] lines;
      lines = new String[_replyLines.size()];
      _replyLines.copyInto(lines);
      return lines;
    }
  
    /***
     * Returns the reply to the last command sent to the server.
     * The value is a single string containing all the reply lines including
     * newlines.  If the reply is a single line, but its format ndicates it
     * should be a multiline reply, then you must call
     * <a href="#getAdditionalReply"> getAdditionalReply() </a> to
     * fetch the rest of the reply, and then call <code>getReplyString</code>
     * again.  You only have to worry about this if you are implementing
     * your own client using the <a href="#sendComand"> sendCommand </a> methods.
     * <p>
     * @return The last server response.
     ***/
    public String getReplyString() {
      Enumeration enum;
      StringBuffer buffer = new StringBuffer(256);
  
      enum = _replyLines.elements();
      while(enum.hasMoreElements()) {
        buffer.append((String)enum.nextElement());
        buffer.append(SocketClient.NETASCII_EOL);
      }
  
      return buffer.toString();
    }
  
  }
  
  
  
  
  1.1                  jakarta-commons-sandbox/net/src/java/org/apache/commons/net/pop3/POP3Client.java
  
  Index: POP3Client.java
  ===================================================================
  package org.apache.commons.net.pop3;
  
  /* ====================================================================
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 2001 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   *
   * 4. The names "Apache" and "Apache Software Foundation" and
   *    "Apache Commons" must not be used to endorse or promote products
   *    derived from this software without prior written permission. For
   *    written permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache",
   *    "Apache Turbine", nor may "Apache" appear in their name, without
   *    prior written permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   */
  
  import java.io.*;
  import java.net.*;
  import java.util.*;
  import java.security.*;
  
  import org.apache.commons.io.*;
  
  /***
   * The POP3Client class implements the client side of the Internet POP3
   * Protocol defined in RFC 1939.  All commands are supported, including
   * the APOP command which requires MD5 encryption.  See RFC 1939 for
   * more details on the POP3 protocol.
   * <p>
   * 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 
   * <a href="org.apache.commons.net.MalformedServerReplyException.html">
   * MalformedServerReplyException </a>, 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.
   * <p>
   * <p>
   * @author Daniel F. Savarese
   * @see POP3MessageInfo
   * @see org.apache.commons.io.DotTerminatedMessageReader
   * @see org.apache.commons.net.MalformedServerReplyException
   ***/
  
  public class POP3Client extends POP3 {
  
    private static POP3MessageInfo __parseStatus(String line) {
      int num, size;
      StringTokenizer tokenizer;
  
      tokenizer = new StringTokenizer(line);
  
      if(!tokenizer.hasMoreElements())
        return null;
  
      num = size = 0;
  
      try {
        num = Integer.parseInt(tokenizer.nextToken());
  
        if(!tokenizer.hasMoreElements())
  	return null;
  
        size = Integer.parseInt(tokenizer.nextToken());
      } catch(NumberFormatException e) {
        return null;
      }
  
      return new POP3MessageInfo(num, size);
    }
  
    private static POP3MessageInfo __parseUID(String line) {
      int num;
      StringTokenizer tokenizer;
  
      tokenizer = new StringTokenizer(line);
  
      if(!tokenizer.hasMoreElements())
        return null;
  
      num = 0;
  
      try {
        num = Integer.parseInt(tokenizer.nextToken());
  
        if(!tokenizer.hasMoreElements())
  	return null;
  
        line = tokenizer.nextToken();
      } catch(NumberFormatException e) {
        return null;
      }
  
      return new POP3MessageInfo(num, line);
    }
  
    /***
     * Login to the POP3 server with the given username and password.  You
     * must first connect to the server with
     * <a href="org.apache.commons.net.SocketClient.html#connect"> connect </a>
     * before attempting to login.  A login attempt is only valid if
     * the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#AUTHORIZATION_STATE">
     * AUTHORIZATION_STATE </a>.  After logging in, the client enters the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.
     * <p>
     * @param username  The account name being logged in to.
     * @param password  The plain text password of the account.
     * @return True if the login attempt was successful, false if not.
     * @exception IOException If a network I/O error occurs in the process of
     *            logging in.
     ***/
    public boolean login(String username, String password) throws IOException {
      if(getState() != AUTHORIZATION_STATE)
        return false;
  
      if(sendCommand(POP3Command.USER, username) != POP3Reply.OK)
        return false;
  
      if(sendCommand(POP3Command.PASS, password) != POP3Reply.OK)
        return false;
  
      setState(TRANSACTION_STATE);
  
      return true;
    }
  
  
    /***
     * Login to the POP3 server with the given username and authentication
     * information.  Use this method when connecting to a server requiring
     * authentication using the APOP command.  Because the timestamp
     * produced in the greeting banner varies from server to server, it is
     * not possible to consistently extract the information.  Therefore,
     * after connecting to the server, you must call
     * <a href="org.apache.commons.net.pop3.POP3.html#getReplyString">
     * getReplyString </a> and parse out the timestamp information yourself.
     * <p>
     * You must first connect to the server with
     * <a href="org.apache.commons.net.SocketClient.html#connect"> connect </a>
     * before attempting to login.  A login attempt is only valid if
     * the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#AUTHORIZATION_STATE">
     * AUTHORIZATION_STATE </a>.  After logging in, the client enters the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  After connecting, you must parse out the
     * server specific information to use as a timestamp, and pass that
     * information to this method.  The secret is a shared secret known
     * to you and the server.  See RFC 1939 for more details regarding
     * the APOP command.
     * <p>
     * @param username  The account name being logged in to.
     * @param timestamp  The timestamp string to combine with the secret.
     * @param secret  The shared secret which produces the MD5 digest when
     *        combined with the timestamp.
     * @return True if the login attempt was successful, false if not.
     * @exception IOException If a network I/O error occurs in the process of
     *            logging in.
     * @exception NoSuchAlgorithmException If the MD5 encryption algorithm 
     *      cannot be instantiated by the Java runtime system.
     ***/
    public boolean login(String username, String timestamp, String secret)
         throws IOException, NoSuchAlgorithmException
    {
      int i;
      byte[] digest;
      StringBuffer buffer, digestBuffer;
      MessageDigest md5;
  
      if(getState() != AUTHORIZATION_STATE)
        return false;
  
      md5 = MessageDigest.getInstance("MD5");
      timestamp+=secret;
      digest = md5.digest(timestamp.getBytes());
      digestBuffer = new StringBuffer(128);
  
      for(i = 0; i < digest.length; i++)
        digestBuffer.append(Integer.toHexString(digest[i] & 0xff));
  
      buffer = new StringBuffer(256);
      buffer.append(username);
      buffer.append(' ');
      buffer.append(digestBuffer.toString());
  
      if(sendCommand(POP3Command.APOP, buffer.toString()) != POP3Reply.OK)
        return false;
  
      setState(TRANSACTION_STATE);
  
      return true;
    }
   
  
    /***
     * Logout of the POP3 server.  To fully disconnect from the server
     * you must call
     * <a href="org.apache.commons.net.pop3.POP3.html#disconnect"> disconnect </a>.
     * A logout attempt is valid in any state.  If
     * the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>, it enters the
     * <a href="org.apache.commons.net.pop3.POP3.html#UPDATE_STATE">
     * UPDATE_STATE </a> on a successful logout.
     * <p>
     * @return True if the logout attempt was successful, false if not.
     * @exception IOException If a network I/O error occurs in the process
     *           of logging out.
     ***/
    public boolean logout() throws IOException {
      if(getState() == TRANSACTION_STATE)
        setState(UPDATE_STATE);
      sendCommand(POP3Command.QUIT);
      return (_replyCode == POP3Reply.OK);
    }
  
  
    /***
     * Send a NOOP command to the POP3 server.  This is useful for keeping
     * a connection alive since most POP3 servers will timeout after 10
     * minutes of inactivity.  A noop attempt will only succeed if
     * the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.
     * <p>
     * @return True if the noop attempt was successful, false if not.
     * @exception IOException If a network I/O error occurs in the process of
     *        sending the NOOP command.
     ***/
    public boolean noop() throws IOException {
      if(getState() == TRANSACTION_STATE)
        return (sendCommand(POP3Command.NOOP) == POP3Reply.OK);
      return false;
    }
  
  
    /***
     * Delete a message from the POP3 server.  The message is only marked
     * for deletion by the server.  If you decide to unmark the message, you
     * must issuse a <a href="#reset"> reset </a> command.  Messages marked
     * for deletion are only deleted by the server on
     * <a href="#logout"> logout </a>.
     * A delete attempt can only succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.
     * <p>
     * @param messageId  The message number to delete.
     * @return True if the deletion attempt was successful, false if not.
     * @exception IOException If a network I/O error occurs in the process of
     *           sending the delete command.
     ***/
    public boolean deleteMessage(int messageId) throws IOException {
      if(getState() == TRANSACTION_STATE)
        return (sendCommand(POP3Command.DELE, Integer.toString(messageId))
  	      == POP3Reply.OK);
      return false;
    }
  
  
    /***
     * Reset the POP3 session.  This is useful for undoing any message
     * deletions that may have been performed.  A reset attempt can only
     * succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.
     * <p>
     * @return True if the reset attempt was successful, false if not.
     * @exception IOException If a network I/O error occurs in the process of
     *      sending the reset command.
     ***/
    public boolean reset() throws IOException {
      if(getState() == TRANSACTION_STATE)
        return (sendCommand(POP3Command.RSET) == POP3Reply.OK);
      return false;
    }
  
    /***
     * Get the mailbox status.  A status attempt can only
     * succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns a POP3MessageInfo instance
     * containing the number of messages in the mailbox and the total
     * size of the messages in bytes.  Returns null if the status the 
     * attempt fails.
     * <p>
     * @return A POP3MessageInfo instance containing the number of
     *         messages in the mailbox and the total size of the messages
     *         in bytes.  Returns null if the status the attempt fails.
     * @exception IOException If a network I/O error occurs in the process of
     *       sending the status command.
     ***/
    public POP3MessageInfo status() throws IOException {
      if(getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.STAT) != POP3Reply.OK)
        return null;
      return __parseStatus(_lastReplyLine.substring(3));
    }
  
  
    /***
     * List an individual message.  A list attempt can only
     * succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns a POP3MessageInfo instance
     * containing the number of the listed message and the
     * size of the message in bytes.  Returns null if the list
     * attempt fails (e.g., if the specified message number does
     * not exist).
     * <p>
     * @param messageId  The number of the message list.
     * @return A POP3MessageInfo instance containing the number of the
     *         listed message and the size of the message in bytes.  Returns
     *         null if the list attempt fails.
     * @exception IOException If a network I/O error occurs in the process of
     *         sending the list command.
     ***/
    public POP3MessageInfo listMessage(int messageId) throws IOException {
      if(getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.LIST, Integer.toString(messageId))
         != POP3Reply.OK)
        return null;
      return __parseStatus(_lastReplyLine.substring(3));
    }
  
  
    /***
     * List all messages.  A list attempt can only
     * succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns an array of POP3MessageInfo instances,
     * each containing the number of a message and its size in bytes.
     * If there are no messages, this method returns a zero length array.
     * If the list attempt fails, it returns null.
     * <p>
     * @return An array of POP3MessageInfo instances representing all messages
     * in the order they appear in the mailbox,
     * each containing the number of a message and its size in bytes.
     * If there are no messages, this method returns a zero length array.
     * If the list attempt fails, it returns null.
     * @exception IOException If a network I/O error occurs in the process of
     *     sending the list command.
     ***/
    public POP3MessageInfo[] listMessages() throws IOException {
      POP3MessageInfo[] messages;
      Enumeration enum;
      int line;
  
      if(getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.LIST) != POP3Reply.OK)
        return null;
      getAdditionalReply();
  
      // This could be a zero length array if no messages present
      messages = new POP3MessageInfo[_replyLines.size() - 2];
      enum = _replyLines.elements();
  
      // Skip first line
      enum.nextElement();
  
      // Fetch lines.
      for(line = 0; line < messages.length; line++)
        messages[line] = __parseStatus((String)enum.nextElement());
  
      return messages;
    }
  
    /***
     * List the unique identifier for a message.  A list attempt can only
     * succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns a POP3MessageInfo instance
     * containing the number of the listed message and the
     * unique identifier for that message.  Returns null if the list
     * attempt fails  (e.g., if the specified message number does
     * not exist).
     * <p>
     * @param messageId  The number of the message list.
     * @return A POP3MessageInfo instance containing the number of the
     *         listed message and the unique identifier for that message.
     *         Returns null if the list attempt fails.
     * @exception IOException If a network I/O error occurs in the process of
     *        sending the list unique identifier command.
     ***/
    public POP3MessageInfo listUniqueIdentifier(int messageId)
         throws IOException
    {
      if(getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.UIDL, Integer.toString(messageId))
         != POP3Reply.OK)
        return null;
      return __parseUID(_lastReplyLine.substring(3));
    }
  
  
    /***
     * List the unique identifiers for all messages.  A list attempt can only
     * succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns an array of POP3MessageInfo instances,
     * each containing the number of a message and its unique identifier.
     * If there are no messages, this method returns a zero length array.
     * If the list attempt fails, it returns null.
     * <p>
     * @return An array of POP3MessageInfo instances representing all messages
     * in the order they appear in the mailbox,
     * each containing the number of a message and its unique identifier
     * If there are no messages, this method returns a zero length array.
     * If the list attempt fails, it returns null.
     * @exception IOException If a network I/O error occurs in the process of
     *     sending the list unique identifier command.
     ***/
    public POP3MessageInfo[] listUniqueIdentifiers() throws IOException {
      POP3MessageInfo[] messages;
      Enumeration enum;
      int line;
  
      if(getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.UIDL) != POP3Reply.OK)
        return null;
      getAdditionalReply();
  
      // This could be a zero length array if no messages present
      messages = new POP3MessageInfo[_replyLines.size() - 2];
      enum = _replyLines.elements();
  
      // Skip first line
      enum.nextElement();
  
      // Fetch lines.
      for(line = 0; line < messages.length; line++)
        messages[line] = __parseUID((String)enum.nextElement());
  
      return messages;
    }
  
  
    /***
     * Retrieve a message from the POP3 server.  A retrieve message attempt
     * can only succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns a DotTerminatedMessageReader instance
     * from which the entire message can be read.
     * Returns null if the retrieval attempt fails  (e.g., if the specified
     * message number does not exist).
     * <p>
     * You must not issue any commands to the POP3 server (i.e., call any
     * other methods) until you finish reading the message from the
     * returned Reader instance.
     * The POP3 protocol uses the same stream for issuing commands as it does
     * for returning results.  Therefore the returned Reader actually reads
     * directly from the POP3 connection.  After the end of message has been
     * reached, new commands can be executed and their replies read.  If
     * you do not follow these requirements, your program will not work
     * properly.
     * <p>
     * @param messageId  The number of the message to fetch.
     * @return A DotTerminatedMessageReader instance
     * from which the entire message can be read.
     * Returns null if the retrieval attempt fails  (e.g., if the specified
     * message number does not exist).
     * @exception IOException If a network I/O error occurs in the process of
     *        sending the retrieve message command.
     ***/
    public Reader retrieveMessage(int messageId) throws IOException {
      if(getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.RETR, Integer.toString(messageId))
         != POP3Reply.OK)
        return null;
  
      return new DotTerminatedMessageReader(_reader);
    }
  
  
    /***
     * Retrieve only the specified top number of lines of a message from the 
     * POP3 server.  A retrieve top lines attempt
     * can only succeed if the client is in the
     * <a href="org.apache.commons.net.pop3.POP3.html#TRANSACTION_STATE">
     * TRANSACTION_STATE </a>.  Returns a DotTerminatedMessageReader instance
     * from which the specified top number of lines of the message can be
     * read.
     * Returns null if the retrieval attempt fails  (e.g., if the specified
     * message number does not exist).
     * <p>
     * You must not issue any commands to the POP3 server (i.e., call any
     * other methods) until you finish reading the message from the returned
     * Reader instance.
     * The POP3 protocol uses the same stream for issuing commands as it does
     * for returning results.  Therefore the returned Reader actually reads
     * directly from the POP3 connection.  After the end of message has been
     * reached, new commands can be executed and their replies read.  If
     * you do not follow these requirements, your program will not work
     * properly.
     * <p>
     * @param messageId  The number of the message to fetch.
     * @param numLines  The top number of lines to fetch. This must be >= 0.
     * @return  A DotTerminatedMessageReader instance
     * from which the specified top number of lines of the message can be
     * read.
     * Returns null if the retrieval attempt fails  (e.g., if the specified
     * message number does not exist).
     * @exception IOException If a network I/O error occurs in the process of
     *       sending the top command.
     ***/
    public Reader retrieveMessageTop(int messageId, int numLines)
         throws IOException
    {
      if(numLines < 0 || getState() != TRANSACTION_STATE)
        return null;
      if(sendCommand(POP3Command.TOP, Integer.toString(messageId) + " " + 
  		   Integer.toString(numLines)) != POP3Reply.OK)
        return null;
  
      return new DotTerminatedMessageReader(_reader);
    }
  
  
  }
  
  
  
  
  1.1                  jakarta-commons-sandbox/net/src/java/org/apache/commons/net/pop3/POP3Command.java
  
  Index: POP3Command.java
  ===================================================================
  package org.apache.commons.net.pop3;
  
  /* ====================================================================
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 2001 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   *
   * 4. The names "Apache" and "Apache Software Foundation" and
   *    "Apache Commons" must not be used to endorse or promote products
   *    derived from this software without prior written permission. For
   *    written permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache",
   *    "Apache Turbine", nor may "Apache" appear in their name, without
   *    prior written permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   */
  
  import java.io.*;
  import java.net.*;
  import java.util.*;
  
  /***
   * POP3Command stores POP3 command code constants.
   * <p>
   * <p>
   * @author Daniel F. Savarese
   ***/
  
  public final class POP3Command {
    /*** Send user name. ***/
    public static final int USER = 0;
    /*** Send password. ***/
    public static final int PASS = 1;
    /*** Quit session. ***/
    public static final int QUIT = 2;
    /*** Get status. ***/
    public static final int STAT = 3;
    /*** List message(s). ***/
    public static final int LIST = 4;
    /*** Retrieve message(s). ***/
    public static final int RETR = 5;
    /*** Delete message(s). ***/
    public static final int DELE = 6;
    /*** No operation.  Used as a session keepalive. ***/
    public static final int NOOP = 7;
    /*** Reset session. ***/
    public static final int RSET = 8;
    /*** Authorization. ***/
    public static final int APOP = 9;
    /*** Retrieve top number lines from message. ***/
    public static final int TOP  = 10;
    /*** List unique message identifier(s). ***/
    public static final int UIDL = 11;
  
    static final String[] _commands = {
      "USER", "PASS", "QUIT", "STAT", "LIST", "RETR", "DELE", "NOOP", "RSET",
      "APOP", "TOP", "UIDL"
    };
  
    // Cannot be instantiated.
    private POP3Command() {}
  
    /***
     * Get the POP3 protocol string command corresponding to a command code.
     * <p>
     * @return The POP3 protocol string command corresponding to a command code.
     ***/
    public static final String getCommand(int command) {
      return _commands[command];
    }
  }
  
  
  
  1.1                  jakarta-commons-sandbox/net/src/java/org/apache/commons/net/pop3/POP3MessageInfo.java
  
  Index: POP3MessageInfo.java
  ===================================================================
  package org.apache.commons.net.pop3;
  
  /* ====================================================================
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 2001 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   *
   * 4. The names "Apache" and "Apache Software Foundation" and
   *    "Apache Commons" must not be used to endorse or promote products
   *    derived from this software without prior written permission. For
   *    written permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache",
   *    "Apache Turbine", nor may "Apache" appear in their name, without
   *    prior written permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   */
  
  import java.io.*;
  import java.net.*;
  import java.util.*;
  
  /***
   * POP3MessageInfo is used to return information about messages stored on
   * a POP3 server.  Its fields are used to mean slightly different things
   * depending on the information being returned.
   * <p>
   * In response to a status command, <code> number </code>
   * contains the number of messages in the mailbox, <code> size </code> 
   * contains the size of the mailbox in bytes, and <code> identifier </code>
   * is null.
   * <p>
   * In response to a message listings, <code> number </code>
   * contains the message number, <code> size </code> contains the
   * size of the message in bytes, and <code> identifier </code> is null.
   * <p>
   * In response to unique identifier listings, <code> number </code> contains
   * the message number, <code> size </code> is undefined, and
   * <code> identifier </code> contains the message's unique identifier.
   * <p>
   * <p>
   * @author Daniel F. Savarese
   ***/
  
  public final class POP3MessageInfo {
    public int number;
    public int size;
    public String identifier;
  
    /***
     * Creates a POP3MessageInfo instance with <code>number</code> and
     * <code> size </code> set to 0, and <code>identifier</code> set to
     * null.
     ***/
    public POP3MessageInfo() {
      number = size = 0;
      identifier = null;
    }
  
    /***
     * Creates a POP3MessageInfo instance with <code>number</code> set
     * to <code> num </code>, <code> size </code> set to <code> octets </code>,
     * and <code>identifier</code> set to null.
     ***/
    public POP3MessageInfo(int num, int octets) {
      number     = num;
      size       = octets;
      identifier = null;
    }
  
    /***
     * Creates a POP3MessageInfo instance with <code>number</code> set
     * to <code> num </code>, <code> size </code> undefined,
     * and <code>identifier</code> set to <code>uid</code>.
     ***/
    public POP3MessageInfo(int num, String uid) {
      number     = num;
      size       = -1;
      identifier = uid;
    }
  }
  
  
  
  1.1                  jakarta-commons-sandbox/net/src/java/org/apache/commons/net/pop3/POP3Reply.java
  
  Index: POP3Reply.java
  ===================================================================
  package org.apache.commons.net.pop3;
  
  /* ====================================================================
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 2001 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   *
   * 4. The names "Apache" and "Apache Software Foundation" and
   *    "Apache Commons" must not be used to endorse or promote products
   *    derived from this software without prior written permission. For
   *    written permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache",
   *    "Apache Turbine", nor may "Apache" appear in their name, without
   *    prior written permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   */
  
  import java.io.*;
  import java.net.*;
  import java.util.*;
  
  /***
   * POP3Reply stores POP3 reply code constants.
   * <p>
   * <p>
   * @author Daniel F. Savarese
   ***/
  
  public final class POP3Reply {
    /*** The reply code indicating success of an operation. ***/
    public static int OK    = 0;
  
    /*** The reply code indicating failure of an operation. ***/
    public static int ERROR = 1;
  
    // Cannot be instantiated.
    private POP3Reply() {}
  }
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message