Java TM Connector Architecture Inbound Resource Adapter Sample Application

  Samples Index



Inbound Connector Sample Application

This document describes how to build an Inbound Resource Adapter, following the JavaTM Connector Architecture (CA) 1.5 specifications, that can be used in conjunction with the Sun Java System Application Server 8.

This document contains the following sections:



Overview

The Inbound Sample Connector shows how to create an Inbound J2EE CA 1.5 compliant inbound resource adapter (RA), how to deploy such components in the Sun Java System Application Server 8, and also to show how these RAs interact with other J2EE 1.4 compliant application components. The RA described here allows Message-driven Beans (MDBs) to receive email messages that are delivered to a specific mailbox folder on a given mail server. Along with the resource adapter, the sample application provides a simple RMI backend service that allows you to monitor the mailbox folders specified by the MDBs. The sample application also contains a sample MDB that illustrates how the activation configuration spec properties of the MDB provide the configuration parameters that the backend and the RA require in order for you to be able to monitor a mailbox folder.

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.

The main components of this sample are the following:


The Inbound Resource Adapter

The components of the resource adapter are archived, according to the connector architecture specification, into a file named inbound.rar. A pre-built version of this file is located in <install_dir>/samples/connectors/inbound/inbound.rar.

The files in the Inbound Connector Sample are as follows:

inbound.jar

The inbound.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:

META-INF/ra.xml

The Inbound RA's ra.xml file specifies the classes of this RA that implement the required APIs as established by the J2EE Connector Architecture version 1.5. It also defines the activation config 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/inbound/src/META-INF/ra.xml.


The Sample Application

The Inbound 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 an application client and a Web application that allow the user to send emails (any mail client can be used for this purpose, so this document does not explain these components in detail).

The directory structure of the Sample Application is as follows (all paths are relative to <install_dir>/samples/connectors/inbound/):

src - contains the deployment descriptors required to deploy the application to the Sun Java System Application Server 8
src/samples/connectors/inbound/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).
src/samples/connectors/inbound/client/appclient - source code for the application client
src/samples/connectors/inbound/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


The Backend Service

When the inbound resource adapter is deployed, it starts the execution of a backend RMI service that can start a thread that will monitor a specific mailbox folder for new messages. When a new message arrives in that folder, the service thread forwards it to the the inbound resource adapter, which in turn delivers the message to the appropriate message-driven bean. The information needed by the backend service to monitor a specific folder (username, password, server name, and so on) is specified by the messaging provider via the the activation config spec properties of the MDB. When an MDB is deployed, the J2EE SDK passes the MDB's activation config spec information to the inbound resource adapter, which in turn forwards it to the backend RMI service. The RMI service then starts a new thread to monitor the given mailbox folder. When the MDB is undeployed, the J2EE SDK notifies the RA of that action, then the RA notifies the backend service, so that the specific thread monitoring the mail folder associated with the MDB being undeployed is terminated. When the RA is undeployed, the backend service is stopped, and all its threads are terminated. The backend components are located in <install_dir>/samples/connectors/inbound/src/samples/connectors/inbound/backend. There are two main components:


Compiling and Assembling the Application


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

Note Like any other sample provided with the J2EE 1.4 SDK, this sample provides pre-built EAR and RAR files that could be used without rebuilding the application. However, since the activation config spec properties of the MDB bundled in the pre-built EAR file do not describe a real mail folder, you must rebuild the EAR file before deploying this app. Once you have rebuilt the EAR file, refer to Deploying the Sample Application to learn how to deploy it.

Also, once the MDB receives an email message, it will email back a notification to the sender, so make sure to set appropriate values for the properties defined in src/mail.properties, because these enable the MDB to send emails. Otherwise the MDB will log the receipt of the message, but will not be able to acknowledge the receipt of the message via email.
  1. Compile and assemble the application.
    2.
    1. Change directory to: <install_dir>/samples/connectors/inbound/src.
    2. Edit the ejb-jar.xml file and set the activation config spec properties of the MDB so that they specify a real mailbox folder. When deployed, the MDB will receive new messages that were 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)
      • interval: time, in quarters of a minute, that should elapse between checks for new messages in the folder (this is used by the backend service to determine how frequently it should check for new messages arriving to the folder)
      • protocol: at this point this must be set to IMAP. Other options (such as any flavor of POP) have not been tested, but should probably work with little effort as well.
    3. Execute the command asant core. This command compiles all sources and assembles the following modules:
      • inbound.ear
        • Main application, containing a message-driven bean and simple Web and application client applications that allow you to send email messages
      • inbound.rar
        • Inbound 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 4 and 5 are optional.
  3. Clean the application project area (optional).
    4.
    Execute the command asant clean to remove all the files generated in Step 3.
  4. Generate API documentation (optional).
    5.
    Execute the command asant javadocs under <install_dir>/samples/connectors/inbound/src. The API documentation will be located under <install_dir>/samples/connectors/inbound/javadocs.


Deploying the Sample Application

This section contains instructions on how to deploy the application to the Sun Java System Application Server 8.

Note

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

Also, once the MDB receives an email message, it will email back a notification to the sender, so make sure to set appropriate values for the properties defined in src/mail.properties, because these enable the MDB to send emails. Otherwise the MDB will log the receipt of the message, but will not be able to acknowledge the receipt of the message via email.

Please read the note above and rebuild the application if necessary. Then execute the commands asant deploy-rar and asant deploy under <install_dir>/samples/connectors/inbound/src.

These commands deploy the two modules of the Inbound Connector sample application: inbound.rar and inbound.ear. Pre-built versions of these files are located under <install_dir>/samples/connectors/inbound/.


Verifying Deployment

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

To verify the registration of the application, do the following:

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:

inbound <j2ee-application>
inboundRA <connector-module>

You can also check the server log file and verify that the RA has started the backend service and that a service thread has been started for the deployed MDB. The RMI service logs are preceded by [S], 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 J2EE 1.4 SDK):

[RA-start()] starting the service [S]JavaMailService bound [RA-start()] Service started

After deploying the EAR file containing the MDB, you should see log lines similar to the following (with the appropriate values):

[S]Registering EndpointConsumer: username::Inbox@servername0
[S]Starting mail server thread: username::Inbox@servername0

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

<MDB> In SimpleMessageBean.SimpleMessageBean()
<MDB> In SimpleMessageBean.setMessageDrivenContext()
<MDB> In SimpleMessageBean.ejbCreate()
<MDB> Got message: Test 2
<MDB> Found mail session javax.mail.Session@1663698
<MDB> Mail sent


Running the Sample Application

Once the RA and the MDB have been deployed, you can start sending emails 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. In addition. the MDB logs the receipt of the message in the Sun Java System Application Server 8 log file with entries similar to these:

<MDB> In SimpleMessageBean.SimpleMessageBean()
<MDB> In SimpleMessageBean.setMessageDrivenContext()
<MDB> In SimpleMessageBean.ejbCreate()
<MDB> Got message: Test 2
<MDB> Found mail session javax.mail.Session@1663698
<MDB> Mail sent

We recommend that you send emails to the folder associated with the MDB from an email address other than the one that is associated with the MDB. Otherwise, the MDB will receive its own replies.



Troubleshooting

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

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

to learn what exactly went wrong.

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

Last Updated Oct 3, 2003