Appendix E - External EMail Program #

Sending bulk e-mails to the holders of selected accounts and individual statements to those account holders is done by a separate program, outside the main Max2 Visual Basic & C++ program. It is written in Java and uses Java libraries designed to manipulate e-mail messages and their component parts and send them using the SMTP protocol.

The Java program is normally invoked using the external account processing functions of Max2 though, in theory, it could be run for other purposes. Its installation steps are somewhat separate from those of the rest of Max2 and it need not be installed on a system which is not used for sending e-mail.

At the time of writing, at Booker the e-mail sender program is only installed on a separate machine from that with the main Max2 database. It is used with a mirror database rather than on the main database.

The main input to the e-mail sender program is one or more export account files in one of the e-mail sub-formats: that is, with the file header record containing Max2 Statement EMail or Max2 Bulk EMail.

Rather than have a separate configuration file, the e-mail sender program takes all of the information it needs to run from the export account file written by Max2 - which sets the data via the external account processing advanced options dialog box and its subsidiary dialog boxes. This way, all of the configuration information can be kept together.

A consequence of the e-mail sender being a separate Java program is that it runs, of course, in a Java Virtual Machine process in the 32-bit Windows environment rather than the 16-bit backwards compatibility box supported by Windows 95, 98, XP or Vista. This has no major significance but might be relevant to keep in mind when looking into any problems.


Class Names #

The name of the main class of the e-mail sender program is EMailMsgSender. This is not in a package (i.e., it is in the default package) mainly to keep the command line short - there's a limit of 128 characters for commands invoked by 16-bit Windows applications.

Subsidiary classes are in the packages uk.co.bookergliding.max2.emailer and uk.co.bookergliding.max2.emailer.xhtml.


Command Line #

The parameters passed to the e-mail sender are in the typical form of a mixture of switches and file names.

The file names are the names of the control files to be processed. These are in one of the e-mail formats specified in Introduction. At least one control file must be specified. If more than one is specified (Max2 only specifies one) then they are processed in turn, in the order in which they are specified. Errors which are specific to one particular control file do not prevent the following ones from being processed.

Command line options are indicated by starting the parameter with a "-" character. The Windows convention of using a "/" for options is not supported. The options are:

Only one of -k and -d can be specified. If neither is specified or if there is an error with the processing of a control file then the program asks, using a dialog box, what is to be done with the control file.

The normal way to set up Max2 is with the -d switch specified in the Processor Parameters field of the External Account Processing Advanced Options dialog box.

Including the invokation of the Java Virtual Machine and specification of the EMailMsgSender class to run a typical command line used by Max2 to start the e-mail message sender could be:

C:\Windows\Java.exe -classpath C:\Max2\Bin\Max2Java.jar EMailMsgSender -d C:\WINDOWS\TEMP\~MSX011C.TMP

This should be read as a single command line, even if it wraps in the representation above. The .TMP file is the control file written by the Max2 VB code.


Attachment Processing #

For the e-mail message variants of the export account information file format it is possible to list the names of files to be included in the message(s) to be sent sent by using I: Attachment records. Within the Max2 user interface the file names are specified in the Attachments list of the External Account Processing Options dialog box.

The basic handling of these files is described in the Message Text and Attachments paragraphs of the External Account Processing Options Dialog description.

Most of the handling of file type information is delegated to the Java library in activation.jar (see Support Library Installation for how that comes into play and below for development implications). This library contains a mapping from file name extensions to media types ("MIME types") which are used in the e-mail messages sent. The sources searched for these mappings are described in the Javadoc for the class MimetypesFileTypeMap in the jaf-1_0_2.zip file.

The e-mail sender program adds one item to the default list: a mapping from the pdf extension to the media type application/pdf. Combining this with the mappings provided in the version of application.jar from jaf-1_0_2.zip gives the following rather idiosyncratic list:

Media Type Extensions
text/html html htm HTML HTM
text/plain txt text TXT TEXT
image/gif gif GIF
image/ief ief
image/jpeg jpeg jpg jpe JPG
image/tiff tiff tif
image/x-xwindowdump xwd
application/postscript ai eps ps
application/pdf pdf
application/rtf rtf
application/x-tex tex
application/x-texinfo texinfo texi
application/x-troff t tr roff
audio/basic au
audio/midi midi mid
audio/x-aifc aifc
audio/x-aiff aif aiff
audio/x-mpeg mpeg mpg
audio/x-wav wav
video/mpeg mpeg mpg mpe
video/quicktime qt mov
video/x-msvideo avi

Later versions of the Activation Framework add the png extension to the list which could be handy. Further extensions, if necessary, could be added to the e-mail sender program without too much difficulty.

However, for most purposes it is best to stick to very basic formats. Usually PDF is best.


Development Environment #

The Java code has been developed and tested using a Java 1.4 compiler and runtime environment. It does not use or need generics or other Java 1.5 features.

No particular IDE is used. Originally, the code was created using the freebie version of the JCreator IDE but now it is simply edited with a text editor and compiled under the control of an Ant script.

The distribution contains the Java Runtime Environment (JRE) (see Java Runtime Installation). However, for compilation a Java Development Kit (JDK) is required. This can be downloaded for free from the Sun website. Though the program is designed for Java 1.4 it is should be fine to compile with later versions, at least until Sun do something silly (which is unlikely to be a long-term problem as they're usually pretty good about backward compatibility).

As discussed in the System Administration chapter (Support Library Installation) two Java libraries which are free downloads from Sun but not part of the standard Java Runtime Environment are used. Their installation for program execution is discussed in the referenced system administration section but they are also needed at compile time. The Ant script gets them from the sibling java directory where they are stored for distribution. Therefore, this directory is required for compilation.

Deployment is discussed in EMail Software Installation.