KnownSpace Hydrogen Email Handler Package
Application Developer Guide
Email Attributes
After fetching and parsing the email messages, the module creates entites for each email message named "email message " + messageNumber (which will convert to a String of course), then it attaches the following attributes to each message:
-
"email senders", StringEntityValue
(composed of strings separated by commas, with a comma after the last string [laziness, which i will fix if email fetch actually works]) - "email recipients", StringEntityValue (same format as senders)
- "email subject", StringEntityValue
- "email date", DateEntityValue
- "email size", IntegerEntityValue
-
"email message flags", MessageFlags
(a bunch of booleans in an object; i suggest you ignore this for now since to make sense of it and access it properly you'd have to read the javamail api looking for Flags.Flag. i can do that later, if this all works) - "email content type", StringEntityValue
- "email message body", ObjectEntityValue
- "email message urls", VectorEntityValue
-
"mime-type", StringEntityValue
gives the mime type of the base entity -
"content-source", StringEntityValue
the value stored is "mail" to indicate to other modules that the base entity is an email message.
Module Shortcomings
- This module does not remember past email connection information. The user must enter it over and over again.
- This module does not continually check for new email in the remote mailbox. The user must initiate a new session to check mail.
- This module names the fetched email by email message number, starting over from 1 every time a connection initiates, rather than keeping a cumulative total. If the user does not delete read messages on the remote mailbox this results in multiple copies of the same email, paerhaps with different numbers (depending on whether any have since been deleted).
- This module does not delete any messages from the remote mailbox after reading them, even if they are marked as deleted. More generally, this module does no email handling at all beyond simply fetching, parsing, storing, and displaying email messages.
- This module does no verification or authentication. The code is currently trivial to crack. It should create a proper Authenticator object to guard against hacking. (And to be really paranoid, it also should not pass around unencrypted password information in the event.)
- The input window uses a primitive listener to close itself, when it should actually use an anonymous inner class for the same job.
- The email handler simpleton is far too large. It should be broken up into at least three simpletons: one to display the initial input window and then die, one to listen for the event and fetch the messages and then die, and one to parse the messages and create entities for them and then die.
- The email handler simpleton creates separate entities for simple attributes like "date" and so on. While this is consistent with the rest of KnownSpace, these might be compressed into values of one new EntityValue object if space becomes an issue. However, note that it only adds the central email entity to the default pool; all the other entities it creates are simply attached to that one email entity.
- The URL parser should be in the org.datamanager.tools package, since it is of more general use than simply parsing mail messages, and it should have a separate JUnit tester class rather than include testing code in its main() method. More generally, more of the module's components should be fully unit tested.
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:".