Subversion Repositories javautils

                             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.