webapp/webapp.README.txt

This demo illustrates the use of JavaMail APIs in a 3-tiered web 
application. It must be deployed on a web server that supports
servlet and JSP-based web applications (e.g. Tomcat) using at least
J2SE 1.3 and Servlet 2.2.

	+-----------+        +-----------+        +-----------+
	|   IMAP    |        |           |        |           |
	|  Server   |<-IMAP->| JavaMail  |<-HTTP->|    WWW    |
	+-----------+        | Web app   |--HTML->|  Browser  |
	|   SMTP    |<-SMTP->|           |        |           |
	|  Server   |        |           |        |           |
	+-----------+        +-----------+        +-----------+


The JavaMail Web application 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

It is comprised of an HTML document and several Web components 
(servlets, JSP pages and custom tags) and is packaged in a Web 
archive with the following contents:

	index.html
	login.jsp
	folders.jsp
	messageheaders.jsp
	messagecontent.jsp
	compose.jsp
	send.jsp
	errorpage.jsp
	errordetails.jsp
	logout.jsp
	WEB-INF/
	WEB-INF/classes/
	WEB-INF/classes/demo/AttachmentServlet.class
	WEB-INF/classes/demo/FilterServlet.class
	WEB-INF/classes/demo/MailUserBean.class
	WEB-INF/lib/
	WEB-INF/lib/jtl.jar
	WEB-INF/web.xml
	










The collection of .html and .jsp files provide the client-side view 
of the JavaMail Web application. 

	  index.html
	      |
	  login.jsp
	      |
         folders.jsp
	      |
      messageheaders.jsp
	      |
             / \
            /   \
    compose.jsp  messagecontent.jsp
         |
     send.jsp


The WEB-INF/web.xml file contains the web applications deployment
descriptor. It is an XML document that contains configuration and
deployment information for the application.

As per the Servlet specification, the WEB-INF/classes directory
contains servlet and utility classes used by the web application.
The FilterServlet acts as the Controller of the JavaMail Web 
application. All requests are mapped to this servlet. It checks
to see that the user is logged in to the server before forwarding the
request to the appropriate JSP page. The AttachmentServlet is used
to render non-text attachments and the MailUserBean is a utility class
used to maintain information about the mail user.

The WEB-INF/lib directory (also defined in the Servlet specification)
contains the Java archive file for the javamail custom tag library.

The follow tags are furnished in the javamail tag library:

<javamail:sendmail 
 mailuser="mailuserbean"
 [host="hostname"] [port="port"]
 sender="email address" recipient="email address" 
 [cc="email address"] [bcc="email address"] [subject="subject"]>
body of the message
</javamail:sendmail>

Description: Used to send messages.


<javamail:message id="messageinfo"
 folder="folder"
 num="message number"/>

Description: Used to read a single message.


<javamail:listmessages id="mailinfobean"
 folder="folder"
</javamail:listmessages>

Description: Used to iterate through list of messages. The body of the 
tag is repeated for each message in the list.











Building and Packaging the JavaMail Web application

All source for this demo can be found in the following directories:
	src/classes
	src/docroot
	src/taglib

Build scripts (build.sh and build.bat) are provided for building and
packaging the demo. Before executing the build scripts, be sure that 
the following are in your CLASSPATH:
	mail.jar		the JavaMail jar file
	activation.jar		the JAF jar file
	servlet.jar		the servlet/JSP jar file

The following steps are performed when building and packaging the demo.

1. Create a directory named "src/docroot/WEB-INF/classes/demo".

2. Create a directory named "src/docroot/WEB-INF/lib".

3. Compile the files from the "src/classes/demo" directory and add them
   to "src/docroot/WEB-INF/classes/demo".

4. Compile the files from the "src/tablib" directory.

5. Create an archive (jtl.jar) of the taglib classes and add it
   to "src/docroot/WEB-INF/lib".

6. Create a web archive file of the contents of "src/docroot" (and all
   of its sub-directories).

(For a list of the contents of the resulting web archive,
 see the beginning of this document.)











A note on sending mail

In order to send mail using the JavaMail Web App, it is necessary to identify
an SMTP host. This can be accomplished in a couple of ways.

1. Use the TOMCAT_OPTS environment variable.

   Add the following to the TOMCAT_OPTS environment variable:

	-Dmail.smtp.host=yourSMTPmailservername

   Restart your web server.


2. Modify the send.jsp file and update the javamail.war file:

   Add the following parameter to the <javamail:sendmail> tag:

	host="yourSMTPmailservername"

   Repackage the javamail.war file to include the modified send.jsp file.