JavaMail Servlet

~~~~~~~~~~~~~~~~

Overview:

=========

JavaMailServlet should not be taken as a demo of how to use the Java

Servlet API. It is rather an example of how the JavaMail APIs could

be used in a server in a three-tier environment described by the

following diagram:

+-----------+ +-----------+ +-----------+

| IMAP | | | | |

| Server |<-IMAP->| JavaMail |<-HTTP->| WWW |

+-----------+ | Servlet |--HTML->| Browser |

| SMTP |<-SMTP->| | | |

| Server | | | | |

+-----------+ +-----------+ +-----------+

The JavaMailServlet supports the following functionality:

* login to an IMAP server

* list all the messages in the INBOX folder

* view the selected message

* compose and send a message

Setting up and running the demo:

================================

Note: These instructions explain how to compile and run the servlet

demo with Java Web Server (JWS). The procedure should be similar with

other web servers that support the Java Servlet API.

1. Download the latest version of the Java Web Server from

http://www.sun.com/software/jwebserver/index.html and

install according to the included documentation. Make

sure JWS is listening to requests on port 80 (you may

need to modify it from default port 8080; use the JWS

Admin Applet). Make sure you can load the Java Web

Server welcome page when you connect with your browser

to the machine that the server is installed on. Also,

make sure your web browser has cookie support turned on.

2. Set your classpath to include the following:

* mail.jar: in the JavaMail API distribution

* activation.jar: in the JAF distribution

* jws.jar: in the /lib/ directory in JWS installation

3. In javamail-1.1/demo/servlet directory, compile the

JavaMailServlet.java file. That produces two class files,

JavaMailServlet.class and MailUserData.class. Copy these

class files to the /servlets/ directory in the JWS

installation.

4. Copy the mail.jar and activation.jar to the /lib/

directory in the JWS installation.

5. Copy the JavaMail.html file to the /public_html/

directory in the JWS installation.

6. Restart Java Web Server to pick up the new jar files

added to its lib directory. Check again that you can

load the default JWS page to verify that the server

is working fine.

7. Using a web browser, go to

http://<hostname>/JavaMail.html and login to a

valid IMAP account. From here on, you can view

messages in your INBOX and create and send new

messages.

JavaMailServlet Design:

=======================

The following is a brief description of JavaMailServlet class. It

is not intended to serve as an example of how to develop servlets;

see http://java.sun.com/products/servlet for information on the Java

Servlet API. You may find it useful to refer to JavaMailServlet.java

source while reading this.

The JavaMailServlet uses two primary methods to process all

requests: doPost() and doGet(). doPost() processes submissions

from the login and compose forms. When the user logs in, the

doPost() method gets a JavaMail Session and uses the values

of the "hostname", "username" and "password" parameters to login

to the IMAP Store and get the INBOX Folder. To preserve state

between multiple HTTP requests, the necessary information

(Session, Store, Folder, URLName) are collected in the

MailUserData object which is stored using JWS's Session

technology (don't confuse HttpSession and JavaMail's Session--

they are different). Finally, the doPost() method outputs

a table listing the INBOX and the number of messages in it.

Clicking on the "INBOX" link calls the doGet() method

which displays a table of message headers. (See the doGet()

and displayHeaders() methods.)

Clicking on a message generates a request to the servlet with

the message sequence number as a parameter. The doGet() method

receives the request and calls the displayMessage() method

passing it the message sequence number to display. The

displayMessage() method first lists the message headers

by calling the displayMessageHeaders() utility method.

For text/plain messages, the message content is then displayed

as a string wrapped in HTML <pre>...</pre> tags. For multipart

messages, each part is passed to the displayPart() method.

There are two displayPart() methods. The one with signature

displayPart(MailUserData mud, int msgNum, Part part,

int partNum, HttpServletRequest req,

ServletOutputStream out)

is called from the displayMessage() method for each part. For

any part with text/plain content type, the content is output

as a string wrapped in HTML <pre>...</pre> tags. For other

content types, a link representing the part is displayed,

along with the part filename and description, if available.

Clicking in the part link generates a request to the servlet

with two parameters: the message sequence number and the

part number. The doGet() method interprets the parameters and

invokes the second displayPart() method with the signature

displayPart(MailUserData mud, int msgNum,

int partNum, ServletOutputStream out,

HttpServletResponse res)

This method retrieves the specified part from the message and

streams it to the web browser, preceded by the MIME content type

of this part. For example, if the part has a MIME type image/gif,

the method will set the servlet response MIME content type to

"image/gif" and then follow it with the bytes of the actual

image. This leverages the web browser's content handling

ability to display different media types.

Message composition and sending is very similar to message

viewing. When the "Compose" link is clicked in the headerlist

page, the servlet outputs the HTML source for the compose

form stored in the composeForm variable. The user then fills

in the destination address, subject, text, and presses

send. This sends a POST request to the servlet, which

invokes the doPost() method. doPost() calls the servlet's

send() method, which creates a new MimeMessage and fills

it with data retrieved from the POST request. The message

is then sent to its destination using the Transport.send()

static method.