The eMail Sample Adapter

 

This section contains information on the following subjects:

• Introduction to the eMail Sample Adapter

• How the eMail Sample Adapter Works

• How the eMail Event Adapter was Developed

• Creating the eMail Adapter Design-Time GUI

 

---

Introduction to the eMail Sample Adapter

The eMail adapter is a J2EE-compliant adapter built with BEA WebLogic Application Integration Adapter Development Kit. The purpose of the eMail 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 email, 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 eMail 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 eMail message with a minimum of information. Service-specific data is information required to send an email message, such as source address, target addresses, subject, and the body of a message.

The eMail sample 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 eMail Sample Adapter Works.

If you are an adapter developer, you will also want to review How the eMail Event Adapter was Developed and Creating the eMail 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 eMail Sample Adapter Works

This section provides you with an opportunity to have a look at the eMail 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 emails. This section contains information on the following subjects:

• Before You Begin

• Accessing the eMail Sample Adapter

• A Tour of the eMail Sample Adapter

Before You Begin

Make sure the following tasks have been performed before you try to access the eMail sample adapter:

• Install the BEA WebLogic Application Integration. For more information, see the BEA WebLogic Application Integration Installation and Setup Guide.

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

• Ensure that the eMail sample adapter has been deployed so that the design-time GUI is accessible. For more information, see the BEA WebLogic Application Integration Installation and Setup Guide.

Accessing the eMail Sample Adapter

To access the eMail Adapter:

1. Open a new browser window.

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

   http://<HOSTNAME>:7601/wlai

   The Application Integration Console - Login page displays.
   
   

   
    

A Tour of the eMail Sample Adapter

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

 

1. To log on to the Application View Management Console, enter your WebLogic username and password, then click Login. The Application View Management Console displays.
   
   
    
    

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 eMail adapter.

   Note: For detailed information about application views, see Introduction to Using Application Integration. For detailed information about defining application views, see Defining Application Views in the BEA WebLogic Application Integration User Guide
   
   .

   .
    

3. To define an application view:

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

      Note: 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 eMail adapter to use to create this application view.

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

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 eMail User Name and eMail Password.

   2. Enter the eMail service URL in the Connect String field.

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

      Note: 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.
      
      

      
       

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.
      
      
       

   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 email addresses.

   5. In the From field, enter the source email address.

   6. In the CC filed, enter a list of email addresses to receive a copy.

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

   8. In the Subject Field, enter the subject of the email.

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

      Note: 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.

       Note: The email 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 displays.
      
      
       

   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 Save AppView. The Appliation View Administration page displays.
      
      
       

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.
     
     

     
      
      

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 checked.

   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.7

      Allow Pool to Shrink - checked

   4. In the Log Configuration field, enter Log warnings, errors, and audit messages.

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

   6. Click Deploy.
      
      
       

9. Once the application view is deployed, the summary page displays all relevant information about the deployed application view. Use the Summary page to view schemas, event and service summaries, test services and events and undeploy the application view.

 

---

How the eMail Event Adapter was Developed

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

The process of creating the eMail 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:

<WLAI_HOME>\dev\email\docs\api\index.html

You can find the code listing for this package in:

<WLAI_HOME>\dev\email\src\email\spi

Note: <WLAI_HOME> is the drive or home directory where BEA WebLogic Application 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 email sample 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?

   email API

2. *What is the version of the EIS?

   n/a

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

   email 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 eMail 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 email 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 eMail 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 B-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 email 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 eMail adapter extends this class in email.spi.ManagedConnectionFactoryImpl. Listing B-1shows the derivation tree for ManagedConnectionFactoryImpl.

Listing B-1 com.bea.adapter.email.spi.ManagedConnectionFactory Impl

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 ManagedConnections and adapter specific connectionFactory instances. The eMail 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 eMail 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 eMail 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 eMail adapter extends this class in email.spi.ManagedConnectionImpl. Listing B-2 shows the derivation tree for ManagedConnectionImpl.

Listing B-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 eMail adapter overrides what is probably the minimum required functionality of the base classes. There are two abstract methods and two concrete methods that the eMail 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 eMail 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 runtime 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 eMail adapter extends this class in email.spi.ConnectionMetaDataImpl. Listing B-3 shows the derivation tree for ConnectionMetaDataImpl.

Listing B-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 eMail 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 eMail 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 B-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 eMail 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 eMail adapter extends this class in email.cci.ConnectionImpl. Listing B-4 shows the derivation tree for ConnectionImpl.

Listing B-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 eMail 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 eMail adapter extends this class in email.cci.InteractionImpl. Listing B-5 shows the derivation tree for InteractionImpl.

Listing B-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 email 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 Java Beans 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 eMail adapter extends this class in email.cci.InteractionSpecImpl. Listing B-6 shows the derivation tree for InteractionSpecImpl.

Listing B-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 eMail adapter the properties are specific to an email 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 B-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 eMail adapter extends this class by implementing email.event.EmailEventMetaData. Listing B-7 shows the derivation tree for EmailEventMetaData.

Listing B-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 eMail adapter extends this class by implementing email.event.EmailPushEvent. Listing B-8 shows the derivation tree for EmailPushEvent.

Listing B-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 Email EIS. Listing B-9 shows the derivation tree for EmailPushHandler.

Listing B-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's 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 eMail adapter extends this class in email.event.PullEventGenerator. Listing B-10 shows the derivation tree for PullEventGenerator.

Listing B-10 PullEventGenerator

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

Developers' Comments

The Email 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 Email PullEventGenerator supports a single event type, which is the notification of an email being received in the Inbox folder using the POP3 access protocol. As such, the email 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 email 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 email 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 eMail adapter extends this class in email.event.PushEventGenerator. Listing B-11 shows the derivation tree for PushEventGenerator.

Listing B-11 PushEventGenerator

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

Developers' Comments

The Email 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

• Deploy the .rar File

Step 5a: Update the RA.XML File

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

• LogLevel

• LanguageCode

• CountryCode

• MessageBundleBase

• LogConfigFile

• RootLogContext

• AdditionalLogContext

The eMail sample adapter requires these additional delcarations:

Table B-4 RA.XML Properties

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

You can view the complete ra.xml file for the eMail adapter in:

• *WLAI_HOME\dev\email\src\rar\meta-inf\

*WLAI_HOME is the drive or home directory where BEA WebLogic Application Integration is installed.

Step 5b: Create the .rar File

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

Step 5c: Deploy the .rar File

The .rar file should be deployed into the container in the J2EE-compliant application server. The deployment procedure is different on every J2EE-compliant server.

 

---

Creating the eMail 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 BEA WebLogic Application Integration. This section discusses some specific design time issues that were considered during the development of the eMail adapter.

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

• Step 1: Development Considerations

• Step 2: Determine eMail 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 eMail adapter included:

• Determine the email server that will be supported

• Determine the eMail schema generation

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

Step 2: Determine eMail 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 eMail 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 follows:

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.
display.jsp	The Display page is the main "displayer" for other java server pages in the adapter. It authenticates the request and sets the basic look of each screen with a title and description. It includes each JSP that is requested and displays it inline.

Step 3: Create the Message Bundle

To support the Internationalization of all text labels, messages, exceptions, etc., the eMail 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 eMail adapter.

The message bundle for the eMail adapter is contained in WLAI_HOME\dev\doc\email\src directory, which was installed with the ADK. The "HOME" indicates the drive used during installation. 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: 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 in Developing a Design-Time GUI.

eMail Implementation

The Email 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 Java Server Pages will be displayed within your control.jsp; thus control.jsp is the first .jsp that you need to copy. Use the display at the control.jsp in the example adapters (DBMS and eMail) 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 eMail adapter. They provide the ability to add validation, to save field values when the user clicks away, and a number of other features.

Note: 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 Java Server Page, 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 sample adapter's web.xml file as a starting point and modify the necessary components to fit your needs. The code for the web.xml file for the eMail adapter is shown below: