Sun GlassFish Enterprise Server 

Samples Main Page

MailConnector Resource Adapter and Sample Application

The MailConnector sample application demonstrates:

This document uses the following variables:

Overview

This sample application consists of:

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 Java classes and error message files

Because this is a annotated .rar, it does not have connector descriptor file (ra.xml). It is also possible to have ra.xml along with annotated .rar

MailConnector RAR File

The mailconnector.rar 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:

Annotated Resource-Adapter Artifacts

The following resource-adapter classes are annotated to represent various artifacts of the resource-adapter:

Resource Adapter Class Annotation used
samples.connectors.mailconnector.ra.ResourceAdapterImpl @Connector annotation to represent the resource-adapter.
@AuthenticationMechanism annotation to provide the authentication mechanism requirement.
@SecurityPermission annotation to provide security permission requirement.
samples.connectors.mailconnector.ra.outbound.ManagedConnectionFactoryImpl @ConnectionDefinition annotation to represent a connection definition with managed-connection-factory, connection-factory artifact details.
samples.connectors.mailconnector.ra.inbound.ActivationSpecImpl @Activation annotation to represent the activation-spec and the message-listener artifact details.
All of annotated classes @ConfigProperty annotation to represent config properties of the Java Bean

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 ear_dir in the following sub-directories:

Mail Server

Configuration

Note:The pre-built EAR file provided with this sample contains an MDB with generic property values that corresponds to the email folder of user joe. If you intend to change the user, rebuild the EAR file before deploying this application. 

Follow these steps:

  1. The ear_dir/mailconnector-ejb/src/conf/ejb-jar.xml file will have the following properties for the MDB:
  2. 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. 

Building, Deploying, and Running the Application

Perform the following steps to build, deploy, and run the application:

  1. Setup your build environment and configure the application server with which the build system has to work by following the common build instructions.
  2. ear_dir is the sample application base directory
  3. Change directory to ear_dir.
  4. Build, deploy, and run the sample application using the all target.
  5. ear_dir> ant all

  6. It is possible to do the above separately by issuing separate commands as given below.
  7. ear_dir> ant rar compiles and packages the resource-adapter

    ear_dir> ant ear compiles and packages the ear

    ear_dir> ant deploy deploys the resource-adapter, creates necessary resources (javamail, connector), necessary users and credentials in GlassFish and deploys the .ear to application server

    ear_dir> ant run will launch the web application in the default browser

  8. Use the target undeploy to undeploy the application, delete the resources (javamail, connector), deletes users and undeploy the resource-adapter

    ear_dir> ant undeploy

  9. Use the target clean to remove the temporary directories, such as build and dist.

    ear_dir> ant clean

Note : Alternately, you can use Netbeans IDE to open the pre configured projects for mailconnector-ear and mailconnector-ra. Once they are opened,

  1. configure the mailconnector-ra's dependencies to use javax.mail.jar, javax.resource.jar, javax.security.auth.message.jar and common-util.jar from GlassFish installation.

    (Right click the mailconnector-ra project, select Properties > Java Sources Classpath and resolve the dependencies to use the javax.mail.jar, javax.resource.jar, javax.security.auth.message.jar and common-util.jar  in GlassFish Installation's modules directory)

  2. build and deploy mailconnector-ra
  3. [In the command prompt] Change directory to ear_dir and ant setup will create necessary connector resource, pool and javamail resource. Use ant unsetup to delete these resources later.
  4. build, deploy, run mailconnector-ear

Exercising the Outbound Resource Adapter

You can test the outbound resource adapter by running the MailConnector application. 

eg: http://localhost:8080/mailconnector-war

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.

Querying the mailbox is accomplished using the outbound resource adapter features.

Exercising the Inbound Resource Adapter (SecurityContext)

<MDB> In JavaMailMessageBean.JavaMailMessageBean()
<MDB> In JavaMailMessageBean.setMessageDrivenContext()
<MDB> In JavaMailMessageBean.ejbCreate()
[PT] scheduling a delivery FROM: joe::INBOX@localhost
[SC] Password validation callback succeded for user : tom
<MDB> ---- Got a message 
<MDB> SUBJECT: What's up
<MDB> SENDER : tom@localhost
<MDB> getCallerPrincipal() : tom

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.


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

By default, INFO and above log level related messages are printed. You can set FINEST logging for the sample by executing the following command.
GF_HOME/bin/asadmin set-log-level --log-level FINEST samples.connectors.mailconnector.ra

Building, Deploying, and Running the Application in NetBeans IDE

This sample application is not supported on Netbeans.

Troubleshooting

If you have problems when running the application, refer to troubleshooting document.



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