The E-mail Adapter

Note: The E-mail Adapter is deprecated as of this release of WebLogic Integration, and will be removed from the product in a future release.

This section contains information on the following subjects:

Introduction to the E-mail Adapter

The e-mail adapter is a J2EE-compliant adapter built with the WebLogic Integration ADK. The purpose of the e-mail adapter is to provide a way for any application to send notice in case of system failure or process completion. This notification is directed using e-mail, which could be configured to target multiple addresses or even a pager. A single templated message could be created for numerous errors allowing the adapter to plug in replaceable parameters and send the notification.

The e-mail adapter provides sample implementations of both a services and events. The event implementation provides sample code for both push and pull event generator paradigms. The service implementation enables the client to send and e-mail message with a minimum of information. Service-specific data is information required to send an e-mail message, such as source address, target addresses, subject, and the body of a message.

How the E-mail Adapter Works

This section provides you with an opportunity to have a look at the e-mail adapter before you start developing an adapter of your own. If you are a business analyst, you may enjoy running through the interface to get a feel for how the adapter works. The example in this section shows how to create an application view for sending or receiving e-mails. This section contains information on the following subjects:

Before You Begin

Make sure the following tasks have been performed before you try to access the e-mail adapter:

Accessing the E-mail Adapter

To access the e-mail adapter:

A Tour of the E-mail Adapter

Figure F-2 Application Integration Console - Login

How the E-mail Adapter was Developed

This section describes each interface used to develop the e-mail adapter. The ADK provides many of the necessary implementations required by a J2EE-compliant adapter; however, since some interfaces cannot be fully implemented until the EIS and its environment are defined, the e-mail adapter was created to illustrate the detail-specific or concrete implementation of the abstract classes provided in the ADK.

The process of creating the e-mail adapter is comprised of the following steps:

Development Reference Documentation

You can review the Javadoc and code for the methods defined in the steps that follow in this section to see how the implementations provided by the ADK were leveraged.

Note: WLI_HOME is the drive or home directory where WebLogic Integration is installed.

Step 1: Development Considerations

Note: Questions preceded by an asterisk (*) are required to use the GenerateAdapterTemplate utility.

Step 2: Implementing the Server Provider Interface Package

To implement the e-mail adapter Server Provider Interface (SPI) and meet the J2EE-compliant SPI requirements, the classes in the ADK were extended to create the following concrete classes:

These classes provide connectivity to an EIS could be used to establish transaction demarcation, and allow management of a selected EIS.

ManagedConnectionFactoryImpl

The first step in implementing an SPI for the e-mail adapter was to implement the ManagedConnectionFactory interface. A ManagedConnectionFactory supports connection pooling by providing methods for matching and creating a ManagedConnection instance.

Basic Implementation

Listing F-1 com.bea.adapter.email.spi.ManagedConnectionFactoryImpl

javax.resource.spi.ManagedConnectionFactory
|
|-->com.bea.adapter.spi.AbstractManagedConnectionFactory
|
|-->email.spi.ManagedConnectionFactoryImpl

Developers' Comments

ManagedConnectionFactory creates physical connections to an underlying EIS for the application server. A physical connection is encapsulated by a ManagedConnection instance.

ManagedConnectionFactoryImpl is a factory for both managed connections and adapter specific connectionFactory instances. The e-mail adapter has a simple implementation for this factory object. Four methods were implemented from the base classes, two of which are abstract. The abstract methods are createConnectionFactory() and createManagedConnection(). Both of these implementations return adapter-specific object instances. The concrete methods overridden by the e-mail adapter include checkState() and hashCode(). The implementation of checkState() validates the connection parameters required for the adapter to acquire a physical connection. The implementation of hashCode() is also based on connection parameters specific to the e-mail adapter.

ManagedConnection

Basic Implementation

Listing F-2 com.bea.adapter.email.spi.ManagedConnectionImpl

javax.resource.spi.ManagedConnection
|
|-->com.bea.adapter.spi.AbstractManagedConnection
|
|-->email.spi.ManagedConnectionImpl

Developers' Comments

The ManagedConnectionImpl represents the physical connection to the EIS. The e-mail adapter overrides what is probably the minimum required functionality of the base classes. There are two abstract methods and two concrete methods that the e-mail adapter implements: getConnection() and createMetaData().

The method getConnection() is used to wrap the current ManagedConnection with a ConnectionImpl and return it to the caller. The value for myCredentials is compared with the connectionRequestInfo passed. If they match, the current ManagedConnection is wrapped with a ConnectionImpl. The createMetaData() method simply instantiates and returns a ConnectionMetaDataImpl.

The other two methods, destroyPhysicalConnection() and compareCredentials(), are overridden because they are either too simple or empty in the base class. These are both concrete methods in the base class. The method destroyPhysicalConnection() is adapter specific; this method is used to free resources associated with acquiring a physical connection.

The compareCredentials() method is used by matchManagedConnections() method in the ManagedConnectionFactory. The matchManagedConnections() method tries to associate a request for connection with an existing connection matching the same criteria. The criteria is defined in the compareCredentials() method. Usernames are used by the e-mail adapter as the criteria.

ConnectionMetaDataImpl

Basic Implementation

Listing F-3 com.bea.adapter.email.spi.ConnectionMetaDataImpl

javax.resource.spi.ManagedConnectionMetaData
|
|-->com.bea.adapter.spi.AbstractConnectionMetaData
|
|-->email.spi.ConnectionMetaDataImpl

Developers' Comments

The ConnectionMetaDataImpl class provides metadata for an EIS. The metadata implementation describes very specific data required by the application server. The e-mail adapter provides an implementation for the abstract methods declared in the base class. These methods provide product name, product version, user name, and max connections allowed.

Step 3: Implementing the Common Client Interface Package

To implement the e-mail adapter Common Client Interface (CCI) and meet the J2EE-compliant CCI requirements, classes in the ADK to create the following concrete classes were extended

These classes provide connectivity to and access back-end systems. The client interface specifies the format of the request and response records for a given interaction with the EIS.

Note: Although implementing the Common Client Interface (CCI) is optional in the Java Connector Architecture 1.0 specification, it is likely to be required in the future. To be prepared, the e-mail adapter provides a complete implementation.

ConnectionImpl

Basic Implementation

Listing F-4 com.bea.adapter.email.cci.ConnectionImpl

javax.resource.cci.Connection
|
|-->com.bea.adapter.cci.AbstractConnection
|
|-->email.cci.ConnectionImpl

Developers' Comments

The ConnectionImpl class is an application-level handle used to access EIS-level resources and functionality. For the e-mail adapter the implementation is simple. Derived-functionality was used for all methods except the createInteraction() method. This method is an abstract method provided in the connection interface, and unless you have specific needs, this is usually the only method that needs to be defined/overridden. For implementation, you need to return an application-level interaction object.

InteractionImpl

Basic Implementation

Listing F-5 com.bea.adapter.email.cci.InteractionImpl

javax.resource.cci.Interaction
|
|-->com.bea.adapter.cci.AbstractInteraction
|
|-->email.cci.InteractionImpl

Developers' Comments

An Interaction enables a component to execute EIS functions. The InteractionImpl class wraps EIS-specific functionality. Using the ConnectionImpl, you can use the physical EIS connection to provide application-level interfaces to the EIS. This is probably where you will spend most of your time.

The two execute() methods process according to the method being called and either return an output document in the parameter list or as a result of the call. The last method is close(). The close() method is used to free resources created in the execution of an EIS call. The execute() method creates an e-mail message based on data from both the InteractionSpecImpl and the input DocumentRecord. The data extracted is used to populate a MimeMessage object and is transported according to the internet address data contained. If an error is encountered it is returned in the output DocumentRecord.

InteractionSpecImpl

An InteractionSpecImpl holds properties for driving an interaction with an EIS instance. An InteractionSpec is used by an interaction to execute the specified function on an underlying EIS.

The CCI specification defines a set of standard properties for an InteractionSpec, but an InteractionSpec implementation is not required to support a standard property if that property does not apply to its underlying EIS.

Basic Implementation

Listing F-6 com.bea.adapter.email.cci.InteractionSpecImpl

javax.resource.cci.InteractionSpec
|
|-->com.bea.adapter.cci.InteractionSpecImpl
|
|-->email.cci.InteractionSpecImpl

Developers' Comments

The InteractionSpecImpl class provides properties used in the request to a service. In the case of the e-mail adapter the properties are specific to an e-mail message; for example: "To"; "From"; "Subject" etc. The InteractionSpecImpl is very much adapter specific. The data required to fulfill a request varies according to the request, and there are no abstract methods that need to be implemented.

Step 4: Implementing the Event Package

Some utility classes were created to help with implementation. These classes were extended from the ADK classes to the create the following concrete classes:

EmailEventMetaData

Listing F-7 EmailEventMetaData

com.bea.adapter.event.EventMetaData
  |
  |-->email.event.EmailEventMetaData

Developers' Comments

The EmailMetaData is used to pass information between the event generator and the handler.

EmailPushEvent

Listing F-8 EmailPushEvent

java.util.EventObject
  |
  |-->com.bea.adapter.event.PushEvent
        |
        |-->email.event.EmailPushEvent

Developers' Comments

The EmailPushEvent is used to send notification from the handler to the event generator.

EmailPushHandler

Listing F-9 EmailPushHander

com.bea.adapter.event.IPushHandler
  |
  |-->email.event.EmailPushHandler

Developers' Comments

The EmailPushHandler implements the ADK interface IPushHandler. The handler interface is provided to abstract EIS event generation from event routing functionality. This is not enforced since the interfaces provided are not required to implement the Push functionality.

The EmailPushHandler implements three interfaces:

The only method implemented outside of the scope of the interface methods is verifyConnection(). The verifyConnection() method validates the connection to the EIS. It does nothing more than check to see if it is connected to the server.

One method of interest is the run() method. A thread was implemented in order to poll the folder for message count. Sun MicroSystems' implementation of the IMAP access protocol does not send notification without this polling, so this it does not provide good example of push generation. However, the idea is to show how to separate the generation functionality from the routing functionality. The rest of the implementation is fairly straightforward and follows the interfaces implemented.

PullEventGenerator

Listing F-10 PullEventGenerator

com.bea.adapter.event.AbstractEventGenerator
  |
  |-->com.bea.adapter.email.event.AbstractPullEventGenerator
    |
    |-->email.event.PullEventGenerator

Developers' Comments

The E-mail Pull event generator is a POP3-only event generator. The reason for this is that POP3 does not allow notifications to be received when a listener is added to the Inbox folder. In order to deploy the PullEventGenerator you need to modify some of the properties contained in the EmailEventRouter web.xml file. Once you have the correct properties, the EmailEventRouter.war file can be created using the ANT build process.

The E-mail PullEventGenerator supports a single event type, which is the notification of an e-mail being received in the Inbox folder using the POP3 access protocol. As such, the e-mail event generator probably doesn't need to implement setupNewTypes() and removeDeadTypes(); however, the event engine will give notification when event types are removed.

Other than the implementation of setupNewTypes() and removeDeadTypes(), the only other abstract method is postEvents(). The postEvents() method is the fulcrum to the event generation process. This is where you would add EIS-specific implementations. The e-mail event generator uses the postEvents() method to read from the Inbox and route new messages to any listeners.

One other method of interest is the doCleanUpOnQuit() method. This method provides a place to free any resources allocated in the event generation process. The e-mail event generator uses doCleanUpOnQuit() to free the mail store and release the mail session.

PushEventGenerator

Listing F-11 PushEventGenerator

com.bea.adapter.event.AbstractEventGenerator
  |
  |-->com.bea.adapter.email.event.AbstractPushEventGenerator
    |
    |-->email.event.PushEventGenerator

Developers' Comments

The E-mail Push event generator is an IMAP only event generator. It is a sample of the push event paradigm. Where the Pull Event Generator uses a thread to continuously poll for an event, the push methodology listens for an event to have been posted. If you look closely at the push event implementation, you will see that it uses a thread to process events in the EmailPushEventHandler. A thread is not necessary to implement the push event. A separate thread was used to implement the push generator.

Additionally, three other classes were used in the push implementation. These are:

The EmailPushHandler serves to abstract the push event generation functionality from the event routing. The EmailPushEvent is used to send notification from the handler to the event generator. The EmailMetaData is used to pass information between the event generator and the handler. If you look closely at the PushEventGenerator code, you will find that it knows almost nothing of the EIS. It uses the setNewTypes() and removeDeadTypes() to create the array it needs to process events, and it uses postEvents() to process notifications.

Step 5: Deploying the Adapter

After implementing the SPI, CCI and event interfaces, the adapter was deployed. To deploy the adapter:

Before You Begin

Before deploying the adapter into WebLogic Integration, do the following:

Step 5a: Update the ra.xml File

The e-mail adapter provides the ra.xml file in the adapter's .rar file (META-INF/ra.xml). Since the e-mail adapter extends the AbstactManagedConnectionFactory class, the following properties were provided in the ra.xml file:

WLI_HOME/adapters/email/src/rar/META-INF/

Step 5b: Create the .rar File

Class files, logging configuration, and message bundle(s) should be bundled into a .jar file, which should then be bundled along with META-INF/ra.xml into the .rar file. The Ant build.xml file demonstrates how to properly construct this .rar file.

Step 5c: Build the .jar and .ear Files

To build the .jar and .ear files, use this procedure:

Step 5d: Create and Deploy the .ear File

To create and deploy the .ear file, thus deploying the e-mail adapter, use this procedure:

Creating the E-mail Adapter Design-Time GUI

The design-time GUI is the user interface that allows the user to create application views, add services and events and deploy the adapter if it is hosted in the WebLogic Integration. This section discusses some specific design-time issues that were considered during the development of the e-mail adapter.

The process of creating the e-mail adapter design-time GUI is comprised of the following steps:

Step 1: Development Considerations

Some of the important development considerations regarding the design-time GUI for the e-mail adapter included:

Step 2: Determine E-mail Adapter Screen Flow

You should consider the order in which the Java server pages will appear when the user displays the application view.

Java Server Pages (JSP)

Step 3: Create the Message Bundle

To support the Internationalization of all text labels, messages, exceptions, and so on, the e-mail adapter uses a message bundle based on a text property file. The property file uses copied name value pairs from the BEA_WLS_SAMPLE_ADK property file, and new entries were added for specific to the e-mail adapter.

The message bundle for the e-mail adapter is contained in WLI_HOME/adapters/email/src directory, which was installed with the ADK. Please refer to BEA_WLS_EMAIL_ADK.properties in the directory above.

For additional instructions on creating a message bundle, please refer to the JavaSoft tutorial on internationalization at:

Step 4: Implementing the Design-time GUI

To implement the design-time GUI, you need to create a DesignTimeRequestHandler class. This class accepts user input from a form and performs a design-time action.

E-mail Implementation

The E-mail DesignTimeRequestHandler class extends AbstractDesignTimeRequestHandler and provides these methods:

Step 5: Writing Java Server Pages

Step 5a: Developers' Comments

1. Your JSPs will be displayed within your display.jsp; thus display.jsp is the first .jsp file that you need to copy. Use the display at the display.jsp in the example adapters (DBMS and e-mail) of the ADK as a starting point.

2. The ADK provides a library of custom .jsp tags, which are used extensively throughout the Java server pages of the ADK and e-mail adapter. They provide the ability to add validation, to save field values when the user clicks away, and a number of other features.

Saving an Object's State When Using the ADK

There are a number of ways to save an object's state when building your adapter using the ADK. The AbstractDesignTimeRequestHandler maintains an ApplicationViewDescriptor of the application view being edited. This is often the best place to save state. Calls to the handler are fast and efficient. You can also ask the AbstractDesignTimeRequestHandler for a manager bean, using its convenience methods: getApplicationViewManager(), getSchemaManager(), and getNamespaceManager(), to retrieve information from the repository about an application view. This is more time-consuming but may be necessary on occasion. Since it is a JSP, you can also use the session object, although everything put in the session must explicitly implement the java.io.serializable interface.

Step 5b: Write the WEB-INF/web.xml Web Application Deployment Descriptor

Write the WEB-INF/web.xml Web application deployment descriptor. In most cases, you should use the adapter's web.xml file as a starting point and modify the necessary components to fit your needs. You can see the code for the web.xml file for the e-mail adapter by going to:

WLI_HOME/adapters/email/src/war/WEB-INF/web.xml