Non-Dairy Creamer Release 0.8

What Is Non-Dairy Creamer?

Non-Dairy Creamer (hereafter, NDC) is a software system for utilizing the Interactive Mail Access Protocol version 4 (hereafter IMAP) from within a Java application or Applet. NDC provides a layer of abstraction on top of the network protocol so application writers wishing to build mail reading capabilities into their Java programs (or Applets) may do so with a minimum of hassle.

NDC provides the application program with a set of Java objects which can be used without a detailed understanding of the IMAP protocol to access/manipulate mail messages and related entities such as mailboxes (folders). The NDC API provides objects such as Mailboxes, Messages, Mail Addresses, Body Parts (for multipart mail)etc. It is hoped that in a future version the NDC toolkit will be sufficiently abstracted from IMAP that it will not be necessary for application programmers to know anything about IMAP to use NDC.

Caveat Emptor

For those of you not familar with the IMAP protocol, it does not provide the capability of sending electronic mail. That is the domain of RFC 822 and (in short) not my problem.

Summary Of Documentation

• Downloading
  • Running The Test Mailer
• API Documentation
• IMAPD
• Known Problems And Bugs
• Programming With NDC (separate document)
  • High Level Structure
    • Protocol State Objects
    • Mail Message Data Objects
      • BodyPart Objects And MIME
    • Utility Objects
  • Coding Standards
• Plans For The Next Release
• Reporting Bugs

Downloading

• Release 0.8.

Running The Test Mailer

To run the mailer you first need to have an imapd running on a system in your network. If you don't have an imapd see below. Now that you are running the imapd, you'll need to tell java where to look for its classes and the NDC classes. You set the environment variable CLASSPATH to a set of directories and/or zip files with the classes in them. (I haven't had much luck with getting things to work out of zip files in the CLASSPATH variable; if you get it work with NDC please send me mail.) As an example, I have the java system loaded into my ~/java director and I have the unpacked NDC distribution there as well. So, I set my CLASSPATH variable to be ~/java/lib:~/java. The first one is for the system defined classes which I have in a zip file (classes.zip) in the lib subdirectory. The second one is the path to the top of my heirarchy of class names, so there is a directory in ~/java called GIT which has a sudirectory called GVU, and so on.

Once you have this much set up, verify that you have java in your path and that it is the one associated with the classes in your CLASSPATH. Now try this command: java GIT.GVU.IMAP.Tests.Driver. If you get a prompt which asks you IMAP Server : you are in business.

IMAPD

To use NDC you'll have to be running a copy of imapd on your system. I have already compiled imapd for some popular operating systems around this building. If you would like to have one of my pre-compiled binaries, please just click on the operating system you are interested in.

• Solaris 2 (compiled on 2.5)
• IRIX 5 (compiled on 5.2)
• SunOS 4 (compiled on 4.1.3)

Here are Mark Crispin's (author of the IMAP standard and the U. Washington server) instructions for installing imapd on your system.

UNIX INSTALLATION NOTES

The imapd daemon should be installed in a system daemon directory,
and invoked by your /etc/inetd.conf file with a line like:

imap	stream	tcp	nowait	root	/usr/local/etc/imapd	imapd

     Note that different variants of UNIX have different versions of inetd,
so you should verify the precise form of these commands (for example, some
versions of inetd do not require the "nowait").

     You may also have to edit your /etc/services (or Yellow Pages,
NetInfo, etc. equivalent) to register this service, such as:

imap		143/tcp

Known Problems And Bugs

• Some mail messages that MH tolerates (such as those with empty header fields) are not handled correctly and cause an null pointer exception. This is only a problem for those using MH mailboxes.
• NDC assumes a UNIX server. This is only relevant with respect to the difference in file heirarchy separator ('/' vs '\').
• If the connection times out and NDC then tries to issue a command, it ends up trying to write on a closed socket and throws an IOException. If this happens is should be trapping the exception and trying to read the remaining messgaes from the server. Hopefully, this would have a BYE message in it, so the client of the API could gracefully shut thigns down.
• I can't figure out how to get java to read a line from the terminal and not echo the characters. Thus your password is printed on the screen as you log in to the sample mailer.
• I probably need to make a pass over all the functions in the API and be sure that everything that needs to be public is declared that way and everything else isn't. This may cause some applications which are using what are now public functions to break, but hey, its release 0.8!

Plans For The Next Release (0.9)

• Obviously, fix the known problems and bugs. Especially the dependency on a UNIX server.
• Add support for all protocol requests and responses.
• Add support for quoted-printable encoding in MIME messages.
• Add some kind of very simple Applet example. This will probably just type out your inbox and put it into a web page (no user interaction other than just scrolling).

Reporting Bugs

Click here for a mail buffer in your browser.