JavaTM Connector Architecture MailConnector Resource Adapter Sample Application

  Samples Index



MailConnector Sample Application

This document describes how to build a MailConnector Resource Adapter, following the JavaTM 2 Platform, Enterprise Edition (J2EETM) Connector Architecture 1.5 specification, that can be used in conjunction with the Sun Java System Application Server 8.1 2005Q1.

This document contains the following sections:



Overview

The MailConnector Sample Application shows the following:

The RA described here allows message-driven beans (MDBs) to receive email (javax.mail.Message) 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.

To assist in the implementation of asynchronous messaging (delivering messages to MDBs), the capabilities for scheduling worker threads from a resource adapter (Work Management APIs) were used to obtain a thread (called PollingThread) which works as a bridge between the MailConnector-RA and the email servers. The sample application also includes a sample MDB that illustrates how the activation spec properties of the MDB provide the configuration parameters that the PollingThread of the RA requires to be able to monitor a given mailbox folder. It also contains two servlets and two JavaServerTM Pages (JSPTM) pages that you can use to test the synchronous facilities provided by the MailConnector resource adapter.

The onMessage method of the MDB uses the JavaMail API to send a reply acknowledging the receipt of the message, which is enough to verify that the full 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 can be seen in the server logs.

The main components of this sample are the following:


The MailConnector Resource Adapter

The components of the resource adapter are archived, according to the connector architecture specification, into a file named mailconnector.rar.

The mailconnector.rar. contains the following files:


mailconnector.jar

The mailconnector.jar file contains the Java interfaces, implementation classes, and utility classes required by the resource adapter, and the error message or resource files. The resource files, named LocalStrings.properties, may be modified to comply with internationalization (I18N) standards. The source code for these components can be found here (all paths are relative to <install_dir>/samples/connectors/apps/mailconnector):

META-INF/ra.xml

The Mailconnector RA's deployment descriptor ra.xml file specifies the classes of this 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)

This file is located at <install_dir>/samples/connectors/apps/mailconnector/mailconnector-ra/src/conf/ra.xml.


The Sample Application

The MailConnector sample application contains a message-driven bean that exercises the Inbound connector. You should deploy the Resource Adapter before you deploy the sample application. The sample application also contains a Web application that allows the user to send email messages (any mail client can be used for this purpose, so this document does not explain this component in detail), 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 directory structure of the Sample Application is as follows (all paths are relative to <install_dir>/samples/connectors/apps/mailconnector/):

mailconnector-ejb/src/conf - contains the deployment descriptors required to deploy the application on the Application Server
mailconnector-ejb/src/java/samples/connectors/mailconnector/client/mdb - 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/samples/connectors/mailconnector/servlet - source code for the SendMailServlet and the MailBrowserServlet servlets.
  • SendMailServlet.java: sends email messages using the information provided through the sendmail.jsp JSP page
  • MailBrowserServlet.java: uses the outbound connector facilities to check for new email messages in a given mail folder whose location has been provided through the browsemail.jsp JSP page
mailconnector-war/web - contains the main menu of the Web component application included with this sample (index.html) as well as the two JSP pages that allow users to send email messages to a given mailbox folder as well and to query for new messages on a given mail folder using the connection interfaces provided through the MailConnector resource adapter.

src/samples/connectors/mailconnector/api
- source code for the interface that MDBs need to implement to be able to accept messages from this 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.


The Polling Thread of the inbound connector

When the MailConnector resource adapter is deployed, it makes use of the Work Management facilities available to resource adapters to start the execution of a thread that will monitor mailbox folders for new messages. When a new message arrives to a folder, the PollingThread instantiates a DeliveryThread that will forward 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 of that action, 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 is located at <install_dir>/samples/connectors/apps/mailconnector/mailconnector-ra/src/java/samples/connectors/mailconnector/ra/inbound.


Compiling and Assembling the Application



This section contains instructions on how to build and assemble the application.


Note The pre-built EAR file provided with this sample contains an MDB whose activation config spec properties, defined in the ejb-jar.xml file, are generic values that do not correspond to a real email folder. Before deploying this application, you need to specify properties specific to your environment, and then rebuild the EAR file.

  1. Compile and assemble the application.
    1. Change directory to: <install_dir>/samples/connectors/apps/mailconnector/src/conf.
    2. Edit the mailconnector-ejb/src/conf/ejb-jar.xml file and set the activation config spec properties of the MDB so that they specify a real mailbox folder in your computing environment. When deployed, the MDB will receive new messages that are sent to that folder. These are the properties that need to be set:
      • 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: at this point this must be set to imap. Other options (such as POP) have not been tested.
    3. 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. As explained above, currently 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.
    4. Execute the command asant core. This command compiles all sources and assembles the following modules:
      • mailconnector.ear
      • Main application, containing a message-driven bean and simple Web application that allow you to send email messages to a folder and/or query for new messages on a given folder
      • mailconnector.rar
      • MailConnector resource adapter

  2. Deploy the application.
  3. After compiling the sources and assembling the EAR and RAR files, you may proceed to Deploying the Sample Application. Steps 3 and 4 are optional.
  4. Clean the application project area (optional).
  5. Execute the command asant clean to remove all the files generated in Step 1.
  6. Generate API documentation (optional).
  7. Execute the command asant javadocs under <install_dir>/samples/connectors/apps/mailconnector. The API documentation will be located under <install_dir>/samples/connectors/apps/mailconnector/javadocs.


Deploying the Sample Application

This section contains instructions on how to deploy the application on the Application Server.


Note

Before deploying, you must have edited the activation config spec properties of the MDB defined in the mailconnector-ejb/src/conf/ejb-jar.xml file (servername, username, password, foldername), so that they correspond to a mail folder, on a real mail server, from which the MDB will consume messages.


Execute the command asant deploy under <install_dir>/samples/connectors/apps/mailconnector.

This command deploys the two modules of the MailConnector sample application: mailconnector.rar and mailconnector.ear.


Verifying Deployment

As an optional step, you can use the asadmin command to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.

To verify the registration of the application, execute the command asadmin list-components to look at applications deployed with a server instance. For example:

<install_dir>/bin/asadmin list-components --user <username> --password <password>

You will see the sample inbound connector listed as well as the J2EE application containing the MDB:

mailconnector <j2ee-application>
mailconnectorRA <connector-module>

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

Once an email message is delivered to the mailbox folder associated with the MDB, log lines similar to the following should appear:

<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


Running the Sample Application

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

Testing the outbound resource adapter:

You can test the outbound resource adapter by pointing your browser to the following URL:

http://hostname:port/mailconnector

Then 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.


Troubleshooting

If you encounter problems when running the application, review the Application Server log file located at

<install_dir>/domains/<domain-name>/logs/server.log

to learn what exactly went wrong.


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

Last Updated August 3, 2004