| Java EE 7 SDK | 
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.
This Mail Connector sample application consists of 4 maven projects:
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 a connector
        descriptor file (ra.xml). It is also possible to have the ra.xml file along
        with the annotated .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.
        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 | @Connectorannotation to represent the
                    resource-adapter.@AuthenticationMechanismannotation to provide the authentication mechanism requirement.@SecurityPermissionannotation to provide the security
                    permission requirement. | 
| samples.connectors.mailconnector.ra.outbound.ManagedConnectionFactoryImpl | @ConnectionDefinitionannotation to represent
                    a connection definition with managed-connection-factory,
                    connection-factory artifact details. | 
| samples.connectors.mailconnector.ra.inbound.ActivationSpecImpl | @Activationannotation to represent the
                    activation-spec and the message-listener artifact details. | 
| All the annotated classes | @ConfigPropertyannotation 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 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 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 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.
        The following servlets are annotated to define resources:
    
    
| Servlet | Annotation used | 
|---|---|
| samples.connectors.mailconnector.servlet.SendMailServlet | @MailSessionDefinitionannotation to define a maill session resource which is used to build and send a mail message. | 
| samples.connectors.mailconnector.servlet.MailBrowserServlet | @ConnectionFactoryDefinitionannotation to define a connector resource which is used to create a connection. | 
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. Follow these steps to install mock JavaMail with the Glassfish server:
svn checkout https://svn.java.net/svn/mock-javamail~svn/trunk/mock-javamail
	mvn clean installtarget/mock-javamail-<SNAPSHOT>.jar
	<glassfish-install-dir>/lib directory of your
	Glassfish installation.
	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:
samples.connectors.mailconnector.ejb.mdb.JavaMailMessageBean 
        defines the following properties using the @ActivationConfigProperty annotation:The MailConnector sample application demonstrates the following key features:
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).@ConnectionFactoryDefinition annotation. @MailSessionDefinition annotation. Perform the following steps to build, deploy, and run the application:
 app_dir is the sample application base directory: 
             samples_install_dir/javaee7/connectors.app_dir. 
                mvn clean install
            
app_dir/mailconnector/mailconnector-ear
                mvn cargo:install
            
lib/ directory
		    in your Glassfish installation.
                mvn cargo:start antrun:run
            
build and dist.
            
                mvn cargo:deployer-undeploy cargo:stop clean
            
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.
http://localhost:8080/mailconnector-webMDBContext.getCallerPrincipal().
            <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.
PollingThread log entries are preceded by [PT]
        PollingThread helper class EndpointConsumer log
            entries are preceded by [EC]
        [RA][SC]
        [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 and above are printed.
    You can set the FINEST level of logging for the sample by executing the following command:
GF_HOME/bin/asadmin set-log-level --log-level FINEST samples.connectors.mailconnector.ra
    
    If you have problems when running the application, refer to the troubleshooting document.
Copyright © 1997-2013 Oracle and/or its affiliates. All rights reserved.