README for POP3 Java class

Copyright Statement


Copyright (c) 1996 John Thomas All Rights Reserved.

Permission to use, copy, modify, and distribute this software and its documentation for commercial or non-commercial purposes is hereby granted provided that this copyright notice appears in all copies. Please notify the author if this code is used in a distributed product.

Note: The apop.java class uses the MD5 and MessageDigest classes from SUN that have more restrictive Copyright statements but these routines are only used for APOP support which may not be required for many uses.


Overview

Interface to a POP3 Mail server

Based on the RFC 1725 definition for the POP 3 Mail client/server protocol: rfc1725.txt

 * Class:	pop3.java
 *
 * Methods:
 *  Constructor:
 *    void      pop3(mailhost,user,password)
 *    void      pop3()
 * * 
 * *    If mailhost,user,password are not supplied on constructor
 * *	then they must be specified on the connect and login calls
 * * 
 *  Public Methods
 * 
 *   popStatus  connect(mailhost)
 *   popStatus  connect()
 *
 *   popStatus  login(user,password)
 *   popStatus  login()
 * *
 * * The following methods try to closely implement the corresponding
 * * POP3 server commands.  See RFC1725
 * *
 *   popStatus     stat()
 *   popStatus     list()    	     *
 *   popStatus     list(msgnum)
 *   popStatus     retr(msgnum)	     *
 *   popStatus     dele(msgnum)
 *   popStatus     noop()
 *   popStatus     quit()
 *   popStatus     top(msgnum,numlines) *
 *   popStatus     uidl(msgnum)
 *   
 *   The APOP command is not supported by the pop3 class.
 *   It is supported by the apop.java class which is a 
 *   subclass of the pop3 class
 *
 *   popStatus is a class that contains the information 
 *   returned by the command.  For example:
 *     popStatus status = list();
 *     status.OK()         true if command suceeded.
 *     status.Response()   Line of text returned by server 
 *     status.Responses()   The * indicated methods have additional
 *			     multiline output that can be retrieved
 *
 *   

Initial release 1.0 - March 21 1996

The apop.java class has not been tested with a POP3 server that supports APOP login. I need someone to volunteer to give me a temporary id on POP3/APOP server so that I can test it.

Release 1.1 - March 26, 1996

- Fixed to use CRLF instead of LF to send commands - Numerous changes to make it Thread-safe (maybe) - Initial APOP test was successful.

Release 1.2 - April 24, 1996

- Improved the demo applet to use a dialog box - Some fixes to handle exceptions during connect.

Release 1.3 - Jan 3, 1997

- Fix to handle servers that return "+OK" instead of "+OK" - Distribute as a Java Package, "jthomas.pop"


Instructions:

download "pop3.tar" to your system.

Untar it into a directory where you will be using the class.
tar -xvf pop3.tar

Either use the Makefile to compile the java classes or issue "javac" against each one.

The pop3.html file contains the documentation on how to use the pop3 class and there are a number of examples included in the tar file.


Contents of pop3.tar:

   
  jthomas/pop/          The directory that contains the Pop package
      pop3.java		The Java POP3 class 
      apop.java             The Java apop class which extends pop3 
			to support the APOP login.

      MD5.java		The MD5 class used by the apop class

      MessageDigest.java    The MessageDigest class extended by the
			MD5 class
  pop3.html		Html documentation for pop3.java
  
  	
	MD5 and MessageDigest are Copyrighted by SUN. 
 	Refer to the java files for restrictions.

  testmain.java		A Java application that does a rather
			complete test of the POP3 protocol.
			It will prompt for the names of the 
			server, userid and password. 

  testapop.java		A Java application that will do a 	
			APOP login if one has a POP3 server that
			supports it.  

  appletpop.java	A Java applet that does a simple login 
			to a POP3 server.  
 
  appletpop.html	A html file to invoke appletpop.java

  getmail.java		An application that will access the POP3 
			server and if it has any waiting mail,
			it will retreive it and save it in a 
			specified mailbox. It is designed to 
			be invoked from a BAT file. 
	Syntax:
		java getmail  host user passwd  mailboxfile			

Use of Pop3 in an applet.

Netscape does not allow an applet to make a network connection to a system other than the system that "served" the applet. This makes it this type of class somewhat useless in an applet unless the Mail Server and the Web Server are the same system. This is usually not the case. One way to circumvent this is to place POP3.class and the code that uses it into your Java CLASSPATH. You could also run the applet under the appletviewer.

In general, until Netscape comes up with a more flexible security policy, the POP3 class is probably more useful in non browser "applications".

In the process of testing this class as an applet, I learned some interesting things about the Netscape class loader and the Applet Connection security limitation.

Netscape enforces the rule that the applet (or any class being invoked by the applet) can only make a network connection to the host system that the applet was downloaded from. However, it can make the connection to any port on that host. The only "exception" to this rule is if the java applet code and all classes used within the applet are found in your Java CLASSPATH. Netscape uses the following search path when searching for the classes to be invoked:

So even if your html applet tag specifies a network address for "code=" and "codebase=", it will still look into CLASSPATH first and if it is found, then it will use that version. So you could use the POP3 class for an applet as long as all the people that want to use the applet have the applet code and the POP3 code in their CLASSPATH.

History:

I worote the pop3.java class because I wanted a way to automatically every hour, connect to my Mail server via a dialup PPP connection and if I had any mail, copy it to my Netscape mailbox and then release the connection. Then at any time, I could take a look at any new mail without having to first make a new connection.

Since I run Win95, I found that Dunce was a good solution for the ability to make the PPP connection every hour and it has the abillity to invoke any command when the connection is ready. Since I didn't immediately find any simple command that would retreive my mail from the POP server and because I needed an excuse to write a Java class, I wrote the pop3 class and the getmail.java application to use it.

I am offering up the pop3 class in case there are others that need to access a POP3 mail server from an application or an applet. Please contact me by E-mail if you find any bugs or have suggestions for improving either the code or the documentation.

01/03/97 - I have rebuilt the package with a fix and also packaged it to be used as a Java Package. I have used this class to implement the JavaFaces application which is being used by numerous users (over 200 at last count) on many different platforms (Windows,OS/2, MacOS and various flavors of Unix). It does seem to work reliably.


Enjoy
John Thomas
jthomas@cruzio.com
http://www.cruzio.com/~jthomas