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

• How the E-mail Adapter Works

• How the E-mail Adapter was Developed

• Creating the E-mail Adapter Design-Time GUI

 

---

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.

The e-mail adapter gives you (developers and business analysts) a concrete example of an adapter, including a JSP-based GUI, to help you understand the possibilities that are at your disposal using the ADK to build adapters. If you are a business analyst, you may enjoy running through the interface to get a better understanding of an "application view", "service", and "event" as shown in How the E-mail Adapter Works.

If you are an adapter developer, you will also want to review How the E-mail Adapter was Developed and Creating the E-mail Adapter Design-Time GUI, the code, and Javadoc to gain insight into how you can extend and use the classes of the ADK to build a JCA-compliant adapter.

 

---

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

• Accessing the E-mail Adapter

• A Tour of the E-mail Adapter

Before You Begin

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

• Install WebLogic Integration. For more information, see Installing BEA WebLogic Integration.

• Set up the ADK Ant-Based Make Process. For more information, see Step 2c: Setting Up the Build Process.

• Ensure that the e-mail adapter has been deployed so that the design-time GUI is accessible. For more information, see the Installing BEA WebLogic Integration.

Accessing the E-mail Adapter

To access the e-mail adapter:

1. Open a new browser window.

2. Open the URL for your system's Application View Management Console.

   http://<HOSTNAME>:7001/wlai

   The Application Integration Console - Login page displays.

   Figure F-1 Application Integration Console - Login

   
    

A Tour of the E-mail Adapter

This section provides you with a short tour through the e-mail adapter. Before you begin, you need to have the e-mail adapter Login page up on your browser. For information about accessing the e-mail adapter, see Accessing the E-mail Adapter.

Figure F-2 Application Integration Console - Login

 

1. To log on to the Application Integration Console - Login screen, enter your WebLogic Username and Password and click Login. The Application View Management Console displays.

   Figure F-3 Application View Management Console

   
    

2. Click Add Application View. The Define New Application View page displays. When you create the application view, you provide a description that associates the application view with the e-mail adapter.

   For detailed information about application views and about defining application views, see Defining an Application View in Using Application Integration.

   Figure F-4 Define New Application View Page

   .
    

3. To define an application view:

   1. In the Application View Name field, enter TestAppView.

      The name should describe the set of functions performed by this application. Each application view name must be unique to its adapter. Valid characters are anything except `.', `#', `\', `+', `&', `,', `'', `"", and a space.

   2. In the Description field, enter a brief description of the application view.

   3. From the Associated Adapters list, choose the e-mail adapter to use to create this application view.

   4. Click OK. The Configure Connection Parameters page displays.

      Figure F-5 Configure Connection Parameters Page

      .
       

4. At the Configure Connection Parameters page, you define the network-related information necessary for the application view to interact with the target EIS. You need to enter this information only once per application view:

   1. Enter your e-mail User Name and e-mail Password.

   2. Enter the e-mail service URL in the Connect String field.

   3. Click Continue. The Application View Administration page displays.

   The Administration page summarizes the connection criteria, and once events and services are defined, you can view the schemas and summaries and also delete an event or service from this page.

   Figure F-6 Application View Administration Page for appViewTest

   
    

5. Now that you have created an application view, you are ready to add a service. To add a service:

   1. In the Administration page, click Add in the Services field. The Add Service page displays.

      Figure F-7 Add Service Page

      
       

   2. In the serviceName field, a meaningful name for the service.

   3. In the serviceDesc field, enter a user description for the service.

   4. In the To field, enter a list of target e-mail addresses.

   5. In the From field, enter the source e-mail address.

   6. In the CC filed, enter a list of e-mail addresses to receive a copy.

   7. In the BCC field, enter a list of e-mail addresses to receive a blind copy, delimited by a semicolon.

   8. In the Subject Field, enter the subject of the e-mail.

   9. Select the Text radio button to send a plain text message. Select Template to define replaceable parameters.

      The body type can be either text or template. A template can contain tags for replaceable parameters.

   10. In the open text field, enter the text of the message.

       The e-mail body can contain replaceable parameters if the type is template, otherwise it will contain a text message.

   11. Click Add Service. The Administration page displayed.

6. Now that you have created an application view, you are ready to add an event to it. To add an event:

   1. In the Administration page, click Add in the Event field. The Add Event page for the event type appears; in this case, that is Configure Mailbox.

      Figure F-8 Add Event Page for Configure Mailbox

      
       

   2. In the eventName field, enter a meaningful name for the event.

   3. In the eventDesc field, enter a description of the event.

   4. Select either the IMAP or POP3 radio button. When configuring an event you can use either the POP3, or IMAP access protocols depending on the type of event generator you wish to deploy. Use IMAP if you are trying to deploy the Push event generator. Use POP3 to deploy the Pull event generator. When IMAP is selected you can select a folder to listen to. POP3/Pull supports the use of a single folder, the INBOX folder.

   5. Scroll to select a folder to query for mail.

   6. Click Add Event. The Application View Administration page displays.

      Figure F-9 Application View Administration Page for appViewTest

      
       

7. Prepare to deploy the application view. The Application View Administration page provides you with a single location for confirming the content of your application view before you save it or deploy it. In this page, you can view the following:

   • Confirm or edit the description of the application view.

   • Confirm or reconfigure Connection Criteria for the application view.

   • Delete services and events.

   • Save the application view so you can return to it later or deploy the application view to the server.

   After verifying the application view parameters, click Continue. The Deploy Application View to Server page displays.

   Figure F-10 Deploy Application View to Servers Page

   
    
    

8. Deploy the Application View. In order to deploy the application view, you must provide several parameters such as enabling asynchronous service invocation, providing the event router URL, and changing the connection pool parameters, among other parameters.
    

   To deploy the application view:

   1. Make sure the Enable Asynchronous Service Invocation check box is unchecked.

   2. In the Event Router URL field, enter http://<HOSTNAME>:<PORT>/EmailEventRouter/EventRouter

   3. For the Connection Pool Parameters, accept the default values:

      Minimum Pool Size - 1

      Maximum Pool Size - 10

      Target Fraction of Maximum Pool Size - 0.1

      Allow Pool to Shrink - checked

   4. In the Log Configuration field, set the log verbosity level to Log warnings, errors, and audit messages.

   5. Make sure the Deploy persistently? box is checked.

   6. Click Deploy.

      Figure F-11 Application View Summary Page

      
       

9. Once the application view is deployed, the summary page displays all relevant information about the deployed application view. Click the appropriate tab on the Summary page to view schemas, event and service summaries, test services and events. You can also undeploy the application view by clicking Undeploy.

 

---

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

• Step 1: Development Considerations

• Step 2: Implementing the Server Provider Interface Package

• Step 3: Implementing the Common Client Interface Package

• Step 4: Implementing the Event Package

• Step 5: Deploying the Adapter

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.

• You can find the Javadoc for this implementation in:

  WLI_HOME/adapters/dbms/docs/api/index.html

• You can find the code listing for this package in:

  WLI_HOME/adapters/email/src/

  in the /cci, /event, and /spi directories

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

Step 1: Development Considerations

The Adapter Setup Worksheet is available to help adapter developers identify and collect critical information about an adapter they are developing before they begin coding. For the e-mail adapter, the worksheet questions are answered as follows:

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

1. *What is the name of the EIS for which you are developing an adapter?

   e-mail API

2. *What is the version of the EIS?

   n/a

3. *What is the type of EIS; for example, DBMS, ERP, etc.?

   e-mail API

4. *Who is the vendor name of this adapter?

   BEA

5. *What is the version number for this adapter?

   None - Sample Only

6. *What is the adapter logical name?

   BEA_WLS_EMAIL

7. Does the adapter need to invoke functionality within the EIS?

   Yes

   If so, then your adapter needs to support services.

   Yes

8. What mechanism/API is provided by the EIS to allow an external program to invoke functionality provided by the EIS?

   It is an API.

9. What information is needed to create a session/connection to the EIS for this mechanism?

   Need to acquire a session, and from the session you can get a transport object. The transport will be used to send mail.

10. What information is needed to determine which function(s) will be invoked in the EIS for a given service?

    Javadoc for e-mail API.

11. Does the EIS allow you to query it for input and output requirements for a given function?

    No

    If so, what information is needed to determine the input requirements for the service?

    n/a

12. For all the input requirements, which ones are static across all requests? Your adapter should encode static information into an InteractionSpec object.

    To, From, CC, BCC, Subject, Body, Type

13. For all the input requirements, which ones are dynamic per request? Your adapter should provide an XML schema that describes the input parameters required by this service per request.

    To, From, CC, BCC, Subject, Body, Type

14. What information is needed to determine the output requirements for the service?

    Success or failure of a send call if in error. Need to extract the error and any e-mail addresses in the error.

15. Does the EIS provide a mechanism to browse a catalog of functions your adapter can invoke? If so, your adapter should support browsing of services.

    No

16. Does the adapter need to receive notifications of changes that occur inside the EIS? If so, then your adapter needs to support events.

    Yes. Need to provide examples of both types of events.

17. What mechanism/API is provided by the EIS to allow an external program to receive notification of events in the EIS? The answer of this question will help determine if a pull or a push mechanism is developed.

    Can either poll a folder for new messages or add a listener (IMAP) to a folder for new messages.

18. Does the EIS provide a way to determine which events your adapter can support?

    No

19. Does the EIS provide a way to query for metadata for a given event?

    Some

20. What locales (language/country) does your adapter need to support?

    English

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:

Table F-1 SPI Class Extensions

 

This concrete class...	Extends this ADK class...
ManagedConnectionFactoryImpl	AbstractManagedConnectionFactory
ManagedConnectionImpl	AbstractManagedConnection
ConnectionMetaDataImpl	AbstractConnectionMetaData

 

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

The ADK provides com.bea.adapter.spi.AbstractManagedConnection Factory, an implementation of the Java Connector Architecture interface javax.resource.spi. ManagedConnectionFactory. The e-mail adapter extends this class in email.spi.ManagedConnectionFactoryImpl. Listing F-1shows the derivation tree for ManagedConnectionFactoryImpl.

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

A ManagedConnection instance represents a physical connection to the underlying EIS in a managed environment. ManagedConnection objects are pooled by the application server. For more information, read about how the ADK implements the AbstractManagedConnection instance in ManagedConnection.

Basic Implementation

The ADK provides com.bea.adapter.spi.AbstractManagedConnection, an implementation of the J2EE interface javax.resource.spi.ManagedConnection. The e-mail adapter extends this class in email.spi.ManagedConnectionImpl. Listing F-2 shows the derivation tree for ManagedConnectionImpl.

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

The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with a ManagedConnection instance. An application server uses this information to get run-time information about a connected EIS instance. For more information, read about how the ADK implements the AbstractConnectionMetaData instance in ConnectionMetaData.

Basic Implementation

The ADK provides com.bea.adapter.spi.AbstractConnectionMetaData, an implementation of the J2EE interface javax.resource.spi.ManagedConnection MetaData. The e-mail adapter extends this class in email.spi.ConnectionMetaDataImpl. Listing F-3 shows the derivation tree for ConnectionMetaDataImpl.

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

Table F-2 CCI Class Extensions

 

This concrete class...	Extends this ADK class...
ConnectionImpl	AbstractConnection
InteractionImpl	AbstractInteraction
InteractionSpecImpl	InteractionSpecImpl

 

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

A Connection represents an application-level handle that is used by a client to access the underlying physical connection. The actual physical connection associated with a Connection instance is associated with a ManagedConnection instance. For more information, read about how the ADK implements the AbstractConnection instance in Connection.

Basic Implementation

The ADK provides com.bea.adapter.cci.AbstractConnection, an implementation of the J2EE interface javax.resource.cci.Connection. The e-mail adapter extends this class in email.cci.ConnectionImpl. Listing F-4 shows the derivation tree for ConnectionImpl.

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

The Interaction enables a component to execute EIS functions. An Interaction instance is created from a connection and is required to maintain its association with the Connection instance. For more information, read about how the ADK implements the AbstractInteraction instance in Interaction.

Basic Implementation

The ADK provides com.bea.adapter.cci.AbstractInteraction, an implementation of the J2EE interface javax.resource.cci.Interaction. The e-mail adapter extends this class in email.cci.InteractionImpl. Listing F-5 shows the derivation tree for InteractionImpl.

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.

The InteractionSpec implementation class must provide getter and setter methods for each of its supported properties. The getter and setter methods convention should be based on the JavaBeans design pattern. For more information, read about how the ADK implements the InteractionSpecImpl instance in InteractionSpec.

Basic Implementation

The ADK provides com.bea.adapter.cci.InteractionSpecImpl, an implementation of the J2EE interface javax.resource.cci.InteractionSpec. The e-mail adapter extends this class in email.cci.InteractionSpecImpl. Listing F-6 shows the derivation tree for InteractionSpecImpl.

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:

Table F-3 Event Class Extensions

 

This concrete class...	Extends the ADK class...
EmailEventMetaData	EventMetaData
EmailPushEvent	PushEvent
EmailPushHandler	java.lang.Object
PullEventGenerator	AbstractPullEventGenerator
PushEventGenerator	AbstractPushEventGenerator

 

EmailEventMetaData

The ADK provides com.bea.adapter.event.EventMetaData, an implementation of the java.lang.Object. The e-mail adapter extends this class by implementing email.event.EmailEventMetaData. Listing F-7 shows the derivation tree for 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

The ADK provides com.bea.adapter.event.PushEvent, an implementation of the java.util.EventObject. The e-mail adapter extends this class by implementing email.event.EmailPushEvent. Listing F-8 shows the derivation tree for 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

The EmailPushHandler extends implements IPushHandler and is the point of contact for the E-mail EIS. Listing F-9 shows the derivation tree for 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:

• MessageCountListener

• Runnable

• IPushHandler

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

The ADK provides com.bea.adapter.event.AbstractPullEventGenerator, an implementation of the java.lang.Object. The e-mail adapter extends this class in email.event.PullEventGenerator. Listing F-10 shows the derivation tree for 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

The ADK provides com.bea.adapter.event.AbstractPullEventGenerator, an implementation of the java.lang.Object. The e-mail adapter extends this class in email.event.PushEventGenerator. Listing F-11 shows the derivation tree for 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:

• EmailPushHandler

• EmailPushEvent

• EmailMetaData

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:

• Update the ra.xml file

• Create the .rar file

• Create and deploy the .ear file

Before You Begin

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

• Determine the location of the adapter on your computer; that is, WLI_HOME/adapters/email where WLI_HOME is the location of your WebLogic Integration installation. This location is referred to as ADAPTER_ROOT hereafter.

• Make sure the e-mail adapter's .jar and .ear files are built, as described in Step 5c: Build the .jar and .ear Files.

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:

• LogLevel

• LanguageCode

• CountryCode

• MessageBundleBase

• LogConfigFile

• RootLogContext

• AdditionalLogContext

The e-mail adapter requires additional declarations, listed in Table F-4:

Table F-4 RA.XML Properties

 

Property	Example
UserName	The username for e-mail adapter login.
Password	The password for username.
ConnectionURL	URL to the e-mail server.

 

See Editing Web Application Deployment Descriptors for instructions on updating these declarations. You can view the complete ra.xml file for the e-mail adapter in:

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:

1. Edit antEnv.cmd (Windows) or antEnv.sh (Unix) in WLI_HOME/adapters/utils. You must set the following variables to valid paths:

   • BEA_HOME - The top-level directory for your BEA products.

   • WLI_HOME - The location of your Application Integration directory.

   • JAVA_HOME - The location of your Java Development Kit.

   • WL_HOME - The location of your WebLogic Server directory.

   • ANT_HOME - The location of your Ant home, typically WLI_HOME/adapters/utils.

2. Execute antEnv from the command-line to set the necessary environment variables for your shell.

3. Change directories to WLI_HOME/adapters/email/project.

4. Execute ant release from the WLI_HOME/adapters/email/project directory to build the adapter.

Step 5d: Create and Deploy the .ear File

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

1. First, declare the adapter's .ear file in your domain's config.xml file, as shown in Listing F-12:

   Listing F-12 Declaring the E-mail Adapter's .ear File

   <!-- This deploys the EAR file -->

   <Application Deployed="true" Name="BEA_WLS_EMAIL_ADK"
      Path="WLI_HOME/adapters/email/lib/BEA_WLS_EMAIL_ADK.ear">

        <ConnectorComponent Name="BEA_WLS_EMAIL_ADK"
           Targets="myserver" URI="BEA_WLS_EMAIL_ADK.rar"/>

        <WebAppComponent Name="EmailEventRouter" Targets="myserver"
           URI="BEA_WLS_EMAIL_ADK_EventRouter.war"/>

        <WebAppComponent Name="BEA_WLS_EMAIL_ADK_Web"
           Targets="myserver" URI="BEA_WLS_EMAIL_ADK_Web.war"/>

   </Application>

   Note: Replace WLI_HOME with the correct path to the WebLogic Integration root directory for your environment.

2. Add the .jar file(s) for the adapter to the WebLogic server classpath. At this time, WebLogic does not support shared .jar files in an .ear file; in other words, the Web applications and the adapters do not share a common classloader parent. Consequently, you need to place the shared .jar files in your adapter on the system classpath.

3. Restart the WebLogic Server.

4. Once the server restarts, add the adapter group to the default WebLogic security realm by using the WebLogic Server Console Web application. To do this, navigate to http://<host>:<port>/console, where <host> is the name of your server and <port> is the listening port; for example:

   http://localhost:7001/console

5. After you have added the adapter group, add a user to the adapter group using the WebLogic console Web application and save your changes.

6. To configure and deploy application views, navigate to http://<host>:<port>/wlai, where <host> is the name of your server and <port> is the listening port; for example:

   http://localhost:7001/wlai

   The Application View Console - Logon is displayed.

   
    

7. Log on to WebLogic Integration by entering your username and password in appropriate fields.

8. Configure and deploy the application views by using the procedures described in Defining Application Views in Using Application Integration.

 

---

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

• Step 2: Determine E-mail Adapter Screen Flow

• Step 3: Create the Message Bundle

• Step 4: Implementing the Design-time GUI

• Step 5: Writing Java Server Pages

Step 1: Development Considerations

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

• Determine the e-mail server that will be supported

• Determine the e-mail schema generation

• Determine if the adapter should support testing of service and events.

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)

The e-mail adapter uses the ADK's Java server pages for a design-time GUI; however, additional JSPs have been added to provide adapter-specific functionality. A description of the additional JSPs is in table Table F-5:

 

Table F-5 Additional ADK JSPs

Filename	Description
addevent.jsp	The Add Event page allows a user to add a new event to the application view.
addservc.jsp	The Add Service page allows the user to add a new service to the application view.
confconn.jsp	The Confirm Connection page provides a form for a user to specify connection parameters for the EIS.
edtevent.jsp	The Edit Event page is an optional page that allows users to edit events.
edtservc.jsp	The Edit Service page is an optional page that allows users to edit services.
event.html	This is a static .html file that contains the forms necessary for editing an event. This file is statically included into edtevent.jsp, which saves duplication of JSP/HTML coding and properties.
service.html	This is a static .html file that contains the forms necessary for editing a service. This file is statically included into edtservc.jsp, which saves duplication of JSP/HTML coding and properties.

 

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:

http://java.sun.com/docs/books/tutorial/i18n/index.html

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.

For more information, see Step 4: Implementing the Design-Time GUI.

E-mail Implementation

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

Method	Description
addevent(javax.servlet.http.HttpServlet Request request)	Adds an event to the application view.
addservc(javax.servlet.http.HttpServlet Request request)	Adds a service to the application view.
getAdapterLogicalName()	Returns my adapter's logical name and helps parent when deploying application views, etc.
getManagedConnectionFactoryClass()	Returns my adapter's SPI ManagedConnectionFactory implementation class, used by parent to get a CCI connection to my EIS.

 

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