Samples Main Page

The MailConnector Resource Adapter Sample Application

This sample application demonstrates how to develop a resource adapter (RA) and deploy connector resources with annotations defined in the Java EE Connector Architecture 1.7 specification. The application uses the mail connector resource adapter to retrieve e-mails. The mail connector resource adapter is completely built by specifying annotations; no deployment descriptor is used.

Description

This Mail Connector sample application consists of 4 maven projects:

• mailconnector-ear is the Java EE enterprise application which contains the following 3 JavaEE modules.
• mailconnector-ra is an embedded resource adapter module that facilitates communication between the JavaEE application and the mail server.
• mailconnector-mdb is an EJB module that contains a message-driven bean (MDB). This MDB exercises the Inbound connector.
• mailconnector-web is a web module that enables the user to send email messages and query for new messages on a given mailbox folder.

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 : mailconnector-ra

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 a connector descriptor file (ra.xml). It is also possible to have the ra.xml file along with the annotated .rar file.

MailConnector RAR File

The mailconnector.rar file contains the Java interfaces, classes, error messages 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 mailconnector/mailconnector-ra/src/main/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.

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 the 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 the 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 configuration properties of the MDB deployment descriptor. When an MDB is deployed, the Application Server passes the MDB's activation configuration 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 mailconnector/mailconnector-ra/src/main/java/samples/connectors/mailconnector/ra/inbound

The Message-Driven Bean(MDB): mailconnector-mdb

The MailConnector application contains a message-driven bean(MDB) that consumes new mails through the MailConnector Resource Adapter.

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

• mailconnector/mailconnector-mdb/src/main/resources/META-INF: contains application deployment descriptor files.
• mailconnector/mailconnector-mdb/src/main/java/samples/connectors/mailconnector/ejb/mdb: contains source code for the MDB. The onMessage method of this MDB consumes email messages sent to a mailbox folder. The mailbox folder is described through the annotation @ActivationConfigProperty defined in @MessageDriven.

The Web Application: mailconnector-web

The MailConnector application 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 the following sub-directories:

• mailconnector/mailconnector-web/src/main/java: contains the SendMailServlet and the MailBrowserServlet servlets.
• mailconnector/mailconnector-web/src/main/webapp/: 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.

Annotated Artifacts

The following servlets are annotated to define resources:

Servlet	Annotation used
samples.connectors.mailconnector.servlet.SendMailServlet	@MailSessionDefinition annotation to define a maill session resource which is used to build and send a mail message.
samples.connectors.mailconnector.servlet.MailBrowserServlet	@ConnectionFactoryDefinition annotation to define a connector resource which is used to create a connection.

Mail Server

The sample application uses a mock JavaMail implementation. The mock JavaMail implementation does not communicate with an mail server. Instead, it simulates a mail server using an in-memory mailbox. For the sake of convenience, this sample project contains its jar library which is located at mailconnector/lib/mock-javamail-1.12.jar. User can directly copy this jar file to the glassfish/lib directory of your Glassfish installation, and do not have to download and build the mock JavaMail project from source files.

1. Download the sources for mock JavaMail using the following command::
   svn checkout https://svn.java.net/svn/mock-javamail~svn/trunk/mock-javamail
2. Compile the sources using the following command:
   mvn clean install
   This command generates the JAR file in target/mock-javamail-<version>.jar

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 to configure the application:

1. The MDB class samples.connectors.mailconnector.ejb.mdb.JavaMailMessageBean defines the following properties using the @ActivationConfigProperty annotation:
   
   
   • serverName: localhost
   • userName: joe
   • password: joe
   • folderName: name of the mail folder associated with the MDB (Inbox by default)
   • protocol: must be "imap"
2. If you wish, edit these properties. These properties enable the MDB to send email messages. 

Key Features

The MailConnector sample application demonstrates the following key features:

• How to create a resource adapter (RA) according to the Java EE Connector Architecture 1.6 Specification by annotating the resource adapter artifacts.
• How to deploy such RAs to the Application Server.
• How resource adapters interact with other Java EE application components.
• How to use resouce adapter's (RA) outbound artifacts.
• How to use resource adapter's (RA) inbound artifacts.
• How to use the WorkContext (eg: SecurityContext) features introduced in Java EE Connector Architecture 1.6 Specification to flow in contextual information from external systems (EIS) to the application server (applications).
• How to define a connector resource in a Web module according to the Java EE Connector Architecture 1.7 Specification through the @ConnectionFactoryDefinition annotation.
• How to define a mail session resource in a Web module according to the Java EE 7 specification with the @MailSessionDefinition annotation.

Building, Deploying, and Running the Application

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

1. app_dir is the sample application base directory: samples_install_dir/connectors.
2. Change directory to app_dir.
3. Build the sample application using
   mvn clean install
4. Change directory to app_dir/mailconnector/mailconnector-ear
5. Download the latest GlassFish
   mvn cargo:install
6. In order to install mock JavaMail library, copy the jar file of mock JavaMail to the lib/ directory of GlassFish installation by executing the command:
   cp ../lib/mock-javamail-1.12.jar target/cargo/installs/latest-glassfish/glassfish4/glassfish/lib
7. Use this command to start GlassFish and deploy the sample application :
   mvn cargo:start antrun:run
8. Use the following command to undeploy the sample application and stop GlassFish:
   mvn cargo:deployer-undeploy cargo:stop clean

Testing the Outbound Resource Adapter

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

Go to the following URL: http://localhost:8080/mailconnector-web

Use the menu to access the JSP pages that allow you to send email messages to an email mailbox and to check the same mailbox for new messages. The JSP pages use servlets to accomplish these tasks.

Querying the mailbox is accomplished using the outbound resource adapter.

Testing the Inbound Resource Adapter (SecurityContext)

• Access the following URL: http://localhost:8080/mailconnector-web
• Click on Send an email message
• Set the From field to tom@localhost
• Set the To field to joe@localhost
• Edit the subject and message
• Press send
• The message is sent to joe's mail box. 
• The deployed resource-adapter has a polling thread that polls the user's (joe's) mailbox periodically (every 30 seconds).
• The thread checks for any new messages. If there are new messages, they will be scheduled for delivery.
• Delivery is scheduled in the SecurityContext ie., in the context of the sender's identity.
• The Resource Adapter will create and submit a SecurityContext representing the sender's identity. For simplicity, we have created the users and credentials in the GlassFish domain; the password is the same as the user name. The list of users is the following: tom, mike, leo, george.
• For every received message, the resource adapter schedules a delivery of the message to the MDB by submitting a work instance.
• The SecurityContext is set with sender's id. The SecurityContext in this sample creates a PasswordValidationCallback with the sender's id and password.
• If the sender's id is a configured user in GlassFish, the context setup in GlassFish succeeds ie., PasswordValidationCallback succeeds and the message is delivered to the MDB.
• If the sender's id is not configured, the context setup in GlassFish fails, and the message is not delivered to the MDB.
• When the message is delivered to the MDB, the MDB prints the caller-principal  of the delivered message using MDBContext.getCallerPrincipal().

• The MDB logs the reception of messages in the application server log file with entries similar to these:

<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 the PollingThread and that it has received the information corresponding to the deployed MDB.

• The PollingThread log entries are preceded by [PT]
• The PollingThread helper class EndpointConsumer log entries are preceded by [EC]
• Resource adapter log entries are preceded by [RA]
• The log entries related to the SecurityContext created per message delivery are preceded by [SC]
• The MDB log entries are preceded by [MDB]

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 entries similar to the following (with the appropriate values):

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

After deploying the embedded RA, you should see log entries similar to the following (along with other log entries from the application server):

[PT] WorkManager started polling thread

By default, the INFO log level messages are printed. You can set the FINEST level of logging for the sample by executing the following command:

GF_HOME/bin/asadmin set-log-levels set-log-levels samples.connectors.mailconnector.ra=FINEST

Troubleshooting

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

Copyright © 1997-2013 Oracle and/or its affiliates. All rights reserved.