The KnownSpace Datamanager
"Halfway To Anywhere"


KnownSpace Hydrogen Email Handler Package

Maintenance Developer Guide

Module Author

Manoj Shanbhag, gregory j. e. rawlins
November, 1998; December 7, 1999

Module Flow of Control

A simpleton creates a window for the user to enter email connection information. Once the user clicks "okay", the window generates an event containing the connection information and throws it into the default pool.

The same simpleton listens for such events. When it detects one, it initiates a connection to the specified remote machine, looking for the specified mailbox of the given username and password with the given access protocol. (If the mailbox and access protocol are not specified, JavaMail defaults them to reasonable values---at least for Solaris machines :)

The same simpleton then parses the messages fetched; creates entities for each one---plus their various attributes, which it attaches to each message-bearing entity---and tosses the main entity only into the default pool.

Later, the user may view the stored email message entities with a MailViewer by double-clicking on the entity displayed in the interface.

Module Diagram


---------> EmailHandlerSimpleton -----> uses -----> EmailMessageFlagsEntityValue
|                  |                         -----> UrlParser
|                  |
|                  |
|               creates
|                  |
|                  +
|          EmailParametersInputWindow  ----> uses ----> BasicWindowMonitor
|                  |
|                  |
|               generates
|                  |
|                  +                           MailViewer
|          EmailParametersEnteredEvent
|                  |
|                  |
|               listened to by
|                  |
--------------------

Module Shortcomings

Important External Helper Classes

This module needs, among others, javax.mail.Session, javax.mail.Store, javax.mail.Folder, javax.mail.Message, and javax.mail.Flags. See the JavaMail API for details.

Module Implicit Dependencies

For this module to work properly, the user's CLASSPATH must include a JavaMail jar file; and for JavaMail to work properly it must have a JavaBeans Activation Framework (package javax.activation), whose jar file must also be found through the CLASSPATH. Normally, those jar files should be kept in the /tools directory.

This module also depends on the availabilty of Swing (package javax.swing), and is written for Java 1.2.

Module Classes

This module consists of the following classes:

class org.datamanager.collector.helpers.email.BasicWindowMonitor

This is a simpleminded listener that closes a window receiving a close event; it should be made into an anonymous inner class. It is used by EmailParametersInputWindow.

public class org.datamanager.collector.helpers.email.EmailParametersInputWindow

Objects of this class display a window for the user to enter parameters describing the network connection to fetch an email repository. It is generated by EmailHandlerSimpleton.

On completion, it generates an EmailParametersEnteredEvent holding the connection parameters. It uses BasicWindowMonitor to handle its closing.

The email parameters are: username, password, email host machine, email access protocol (imap, pop3, smtp), and mailbox.

public class org.datamanager.event.EmailParametersEnteredEvent

Objects of this class carry email connection information from the EmailParametersInputWindow to the EmailHandlerSimpleton, via the default pool as its event channel.

Objects of this class encapsulate a collection of parameters determining a network connection to a remote machine holding a mailbox for a particular user.

public class startup.simpletons.EmailHandlerSimpleton

This simpleton creates entities representing email messages, creates and attaches various new entities to store attributes of those messages, and adds all the created entities to the default pool.

It creates an EmailParametersInputWindow for the user to enter email connection parameters, subscribes to EmailParametersEnteredEvents, which the window generates, and uses EmailMessageFlagsEntityValue (to store the message's processing flags) and UrlParser (to parse out any URLs in the message body).

public class org.datamanager.passiveentityvalue.EmailMessageFlagsEntityValue

Objects of this class store various email message flags. They are simple extensions of JavaMail Flags that implement EntityValue so that they can be stored in Entities. Message flags store a message's processing state---whether it's be read or not, deleted or not, answered or not, and so on.

public class org.datamanager.collector.helpers.email.UrlParser

Objects of this class find all isolated URLs within a string. (An isolated URL is one that is preceded by a blank, a newline, a tab, or a double quote.)

public class org.datamanager.userinterface.cerulean.view.viewer.MailViewer

Objects of this class display a stored mail message entity.

NOTE: to find known flaws and possible improvement ideas in the source code, search for "NOTE:".