Sun Java System Application Server

MailConnector Sample Application

The MailConnector Sample Application demonstrates:

How to create a resource adapter (RA) according to the J2EE Connector Architecture (CA) 1.5 specification.
How to deploy such RAs to the Application Server.
How RAs interact with other J2EE application components.

This document uses the following variables:

install_dir is the directory where Application Server is installed.
app_dir is the application base directory: install_dir/samples/connectors/apps/mailconnector.
appname is the application name: mailconnector. The resource adapter connector module is mailconnectorRA.
The prebuilt EAR file is mailconnector.ear.

Overview

This sample application conists of:

MailConnector Resource Adapter
MailConnector application that contains a message-driven bean (MDB) and a Web application.

The MailConnector Resource Adapter enables the MDB to receive email messages that are delivered to a specific mailbox folder on a given mail server. It also provides connection factory objects that clients can use to obtain connection objects that allow them to synchronously query email servers for new messages on a given mailbox folder.

The onMessage() method of the MDB uses the JavaMail API to send a reply acknowledging the receipt of the message, which verifies that the process is working. This code has been commented out to avoid sending undesired replies when you are testing with a busy mailbox. Instead, relevant information about the received message is dumped to the standard output and you can see it in the server logs.

The MailConnector Resource Adapter

The components of the resource adapter are archived into a file named mailconnector.rar that contains the following files:

MailConnector JAR File, mailconnector.jar, a JAR file containing Java classes and error message files.
MailConnector deployment descriptor file, META-INF/ra.xml.

MailConnector JAR File

The mailconnector.jar file contains the Java interfaces, classes, error message and resource files that make up the resource adapter . You can modify the resource file, LocalStrings.properties, for localization.

The source code for these components is in app_dir/mailconnector-ra/src/java/samples/connectors/mailconnector, in the following sub-directories:

ra: the base class of the MailConnector RA.
ra/inbound: classes that implement the inbound part of the MailConnector.
ra/outbound: classes implement the outbound part of the MailConnector.
api: interfaces that MDBs associated with this RA are required to implement and the Connection and ConnectionFactory interfaces provided by the outbound resource adapter.

Deployment Descriptor File

The Mailconnector RA's deployment descriptor file is app_dir/mailconnector-ra/src/conf/ra.xml,

It specifies the classes of the RA that implement the required APIs as established by the J2EE Connector Architecture specification, version 1.5. It also defines the activation configuration spec properties that must be provided by any message-driven bean that will consume email messages from this resource adapter. It also specifies the listener interface that those MDBs must implement: samples.connectors.inbound.api.JavaMailMessageListener. This interface defines a single method, void onMessage(javax.mail.Message).

The Polling Thread of the Inbound Connector

When the MailConnector resource adapter is deployed, it uses the Work Management facilities available to resource adapters to start a thread that monitors mailbox folders for new messages. When a new message arrives to a folder, the PollingThread instantiates a DeliveryThread that forwards the message to the appropriate message-driven bean.

The information needed by the PollingThread to monitor a specific folder (username, password, server name, and folder name) is specified by the MDB assembler via the the activation config properties of the MDB deployment descriptor. When an MDB is deployed, the Application Server passes the MDB's activation config spec information to the MailConnector resource adapter, which in turn forwards it to the PollingThread. When the MDB is undeployed, the Application Server notifies the RA, and then the MailConnector RA notifies the PollingThread, so that it stops monitoring the the mail folder associated with the MDB being undeployed. When the RA is undeployed, the PollingThread is terminated.

The PollingThread source code is located at app_dir/mailconnector-ra/src/java/samples/connectors/mailconnector/ra/inbound

The MailConnector Application

The MailConnector application contains a message-driven bean that exercises the Inbound connector. The sample application also contains a Web application that enables the user to send email messages (any mail client can be used for this purpose), and it also allows the user to query for new messages on a given mailbox folder by means of a JSP/Servlet pair that uses the synchronous features of the MailConnector to perform this task.

The source code for these components is in app_dir in the following sub-directories:

mailconnector-ejb/src/conf application deployment descriptor files.
mailconnector-ejb/src/java/samples/connectors/mailconnector/ejb/mdb: contains source code for the MDB. The onMessage method of this MDB consumes email messages sent to the mailbox folder described in the activation config spec properties of the MDB deployment descriptor ejb-jar.xml.
mailconnector-war/src/java: contains the SendMailServlet and the MailBrowserServlet servlets.
mailconnector-war/web: contains the main HTML page of the Web application and two JSP pages. The JSP pages enable users to send email messages to a given mailbox folder and query for new messages in a mail folder using the connection interfaces provided through the MailConnector resource adapter.
mailconnector-share/src/samples/connectors/mailconnector/api: contains source code for the interface that MDBs need to implement to be able to accept messages from the inbound RA (samples.connectors.inbound.api.JavaMailMessageListener) as well as for the ConnectionFactory and Connection interfaces available through the outbound resource adapter of the MailConnector-RA.



Configuration

Note:The pre-built EAR file provided with this sample contains
    an MDB with generic property values that do not correspond to a
    real email folder. Before deploying this application, specify properties for your environment,
    then rebuild the EAR file.

Follow these steps:


Edit the app_dir/mailconnector-ejb/src/conf/ejb-jar.xml file and
set the following properties of the MDB:

serverName: name of the machine where the mail server is running
userName: name of the account that owns the mail  folder
password: password of the account that owns the mail folder
folderName: name of the mail folder associated   with the MDB (Inbox by default)
protocol: must be "imap"


If you wish, edit the file mail.properties, specifying
the same property values as you did in the ejb-jar.xml
file. These properties enable the MDB to send email
messages. Otherwise the MDB will log the receipt of the
message, but will not be able to acknowledge the receipt
of the message via email. The code of the MDB that acknowledges messages has been
commented out, so you should set these properties only
if you uncomment that part of the MDB source code.


Building, Deploying, and Running the Application


The general instructions for building, deploying, and running sample applications are provided in
Building, Deploying, and Running Sample Applications.


Follow this general procedure:

    Build the Application.
      The build file, build.xml, is in the app_dir directory.

    
Deploy the Application
      The EAR file is mailconnector.ear.
NOTE: If you use Admin Console to deploy, you must deploy the Resource Adapter before you
deploy the MailConnector application.  If  you use asant, it will deploy them in the
proper order.

    
Run the Application
      The application name is mailconnector.  See further instructions below.




Running the Sample Application

You can test the outbound resource adapter by running the MailConnector application.
Use the menu to access the JSP pages that allow you to send
    email messages to a given email mailbox and also to query the same
    mailbox for new messages arrived. These JSPs use servlets to
    accomplish these tasks.
    
Testing the Inbound Resource Adapter

Once the RA and the MDB have been deployed, you can start sending
    email messages to the address of the folder associated with the MDB.
    When messages arrive at the MDB, it acknowledges the receipt by
    replying to the sender of the email, however, to avoid unnecessary
    replies while testing the application, the send statement has been
    commented out. Please uncomment that statement and rebuild the
    application if you wish to activate the reply feature. In addition,
    the MDB logs the receipt of the message in the Application Server
    log file with entries similar to these:

<MDB> In JavaMailMessageBean.JavaMailMessageBean()
<MDB> In JavaMailMessageBean.setMessageDrivenContext()
<MDB> In JavaMailMessageBean.ejbCreate()
<MDB> ---- Got a message
<MDB> SUBJECT: What's up
<MDB> SENDER : joe@localhost


You can also check the server log file and verify that the RA has
    started PollingThread and that it has received the information
    corresponding to the deployed MDB. The PollingThread logs are
    preceded by [PT]. The PollingThread helper class EndpointConsumer
    logs are preceded by [EC]. Resource adapter logs are preceded by
    [RA], and the MDB logs are preceded by [MDB]. After deploying the
    RA, you should see the following lines (along with other log lines
    from the Application Server):

[PT] WorkManager started polling thread

After deploying the EAR file containing the MDB, if there are no
    problems opening the mail folder associated with the MDB, you should
    see log lines similar to the following (with the appropriate values):

[EC] Created EndpointConsumer for: username::foldername@mailserver







 Copyright © 2006 Sun Microsystems, Inc.
All rights reserved.