Sun GlassFish Enterprise Server |
The MailConnector sample application demonstrates:
This document uses the following variables:
install_dir
or GF_HOME is the directory where the
application server is installed. app_dir
is the application base directory: samples_install_dir/javaee6/connectors/apps/mailconnector
.
ear_dir
is the ear
base
directory: samples_install_dir/javaee6/connectors/apps/mailconnector
.
mailconnector-ear.ear
mailconnector.rar
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 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
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:
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. 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 |
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 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:
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. 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:
ear_dir/mailconnector-ejb/src/conf/ejb-jar.xml
file will have the following properties for the MDB:
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.
Perform the following steps to build, deploy, and run the
application:
ear_dir
is the sample application base
directory
Change directory to ear_dir.
all
target.ear_dir> ant
all
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
ear_dir> ant
undeploy
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,
(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)
ear_dir
and ant setup
will create necessary connector resource, pool and javamail resource. Use ant unsetup
to delete these resources later.
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.
<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.
[PT]
[EC]
[RA]
[SC]
[MDB]
[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@mailserverBy 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
This sample application is not supported on Netbeans.
If you have problems when running the application, refer to troubleshooting document.
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.