Learning to Develop Adapters Using the DBMS Sample Adapter

This section contains information about the following subjects:

• Introduction to the DBMS Sample Adapter

• How the DBMS Sample Adapter Works

• How the DBMS Sample Adapter Was Developed

• How the DBMS Sample Adapter Design-Time GUI Was Developed

 

---

Introduction to the DBMS Sample Adapter

The DBMS sample adapter is a J2EE-compliant adapter that includes a JSP-based GUI. It provides a concrete example of how an adapter can be constructed by using the WebLogic Integration ADK. A relational database is used as the adapter's EIS to allow adapter providers to focus on details of the adapter and the ADK, instead of investing time to learn about a particular proprietary EIS.

The DBMS Sample Adapter is intended to help you understand the tasks required to design and develop your own adapter. It is not intended for use in a production environment, nor is it supported in such an environment. Because the adapter is intended as an example, rather than a production-ready adapter, it does not include a full set of features and has the following limitations: the adapter is unable to execute complex queries or stored procedures.

Whether you are a developer or a business analyst, the DBMS sample adapter can help you understand the possibilities at your disposal when you use the ADK to build adapters. If you are a business analyst, you might find it useful to run through the interface to get a better understanding of an application view, service, and event, as described in How the DBMS Sample Adapter Works.

If you are an adapter developer, we suggest you start by learning how you can extend and use the ADK classes to build a J2EE-compliant adapter. To do so, review the following:

• How the DBMS Sample Adapter Was Developed

• How the DBMS Sample Adapter Design-Time GUI Was Developed

• DBMS sample adapter code

• DBMS sample adapter Javadoc

The DBMS sample adapter satisfies the following requirements:

• Provides a GUI that allows end-users to connect to a Pointbase, Oracle, SQLServer, or Sybase database.

• Uses the classes and tools of the ADK.

• Allows users to create application views with events and services.

• Allows users to test events and services.

• Provides a GUI that enables users to browse, from the GUI, the catalogs, schemas, tables, and columns of the underlying database.

• Supports the creation of services that select, insert, delete, and update data in the database (EIS).

 

---

How the DBMS Sample Adapter Works

This section shows how the DBMS sample adapter works. If you are a business analyst, you might enjoy running through the interface to get a feel for how the adapter works. The example in this section shows how to create a service that inserts a customer in the underlying database, and how an event is generated to notify others that this action has taken place.

This section contains information about the following subjects:

• Before You Begin

• Accessing the DBMS Sample Adapter

• Tour of the DBMS Sample Adapter

Before You Begin

Before you try to access the DBMS sample adapter, make sure you complete the following tasks:

• Install WebLogic Integration. For instructions, see Installing WebLogic Platform.

• Set up the ADK Ant-based make process. For instructions, see Step 2c: Set Up the Build Process.

• Deploy the DBMS sample adapter in such a way that the design-time GUI is accessible. For more information, see Installing WebLogic Platform.

Accessing the DBMS Sample Adapter

To access the DBMS sample adapter:

1. Open a new browser window.

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

   http://HOSTNAME:7001/wlai

   The Application View Console Logon page is displayed as shown in Figure  E-1.

Tour of the DBMS Sample Adapter

This section provides a short tour through the DBMS sample adapter. To begin, open the Application View Console Logon page for the DBMS sample adapter in your browser. For instructions, see Accessing the DBMS Sample Adapter.

Figure E-1 Application View Console - Logon

 

 

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

   Figure E-2 Application View Management Console

   
    

2. Click Add Application View. The Define New Application View page is displayed. When you create an application view, you should provide a description that associates that application view with the DBMS sample adapter.

   For detailed information about application views and how to define them, see Defining an Application View in Using Application Integration.

   Figure E-3 Define New Application View Page

   
    

3. To define an application view:

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

      The name should describe the set of functions performed by this application. The name of each application view must be unique to its adapter. All characters are valid except the following: period (.), hash mark (#), backslash (\), plus sign (+), ampersand (&), comma (,), apostrophe (`), double quotes ("), and a space.

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

   3. From the Associated Adapters list, select a DBMS sample adapter to use to create your application view.

   4. Click OK. The Select Existing Connection page is displayed.

      Figure E-4 Select Existing Connection Page

      
       

   The Select Existing Connection page allows you to choose the type of connection factory to associate with the application view.

   • Select the New Connection radio button to create a new connection factory.

   • Select the radio button for an existing connection factory to share a connection factory with other application views. Click the Reference link next to an existing connection factory to display the names of application views that are deployed using the existing connection factory.

     Figure E-5 Connection Factory Reference Page

     
      

   From the Connection Factory Selection page, you can display the Select Connection or Connection Configuration pages at any time. You can switch between a new and an existing connection factory at any time before the application view is deployed.

4. Click Continue. If you choose to create a new connection factory, the Configure Connection Parameters page is displayed. If you choose to use an existing connection factory, the Application View Administration page is displayed. (See step 5. for information on the Application View Administration page.)

   Figure E-6 Configure Connection Parameters Page

   
    

5. On the Configure Connection Parameters page, enter the network-related information that enables the application view to interact with the target EIS. It is not necessary for you to enter this information more than once per application view:

   1. Enter your WebLogic Server username and password.

   2. In the Data Source Name (JNDI) field, enter WLAI_DataSource.

   3. Click Continue. The Application View Administration page is displayed.

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

   You have finished creating an application view; you can now add a service to it.

   Figure E-7 Application View Administration Page for AppViewTest

   
    

6. To add a service to your new application view, you must supply a name for the service, a description of it, and an SQL statement.

   Use the browse link to browse the DBMS sample adapter database schemas and tables and to specify the database table CUSTOMER_TABLE.

   To add a service:

   1. On the Application View Administration page, click Add in the Services group. The Add Service page is displayed.

      Figure E-8 Add Service Page

      
       

   2. In the Unique Service Name field, enter InsertCustomer.

   3. In the Description field, enter a description of the service.

   4. Click Browse DBMS to view the table and column structure of the database. If you are writing a complex query, you may want to leave the Browse window open so you can later cut and paste table or column names into your query.

      Figure E-9 Browse DBMS Page

      
       

   5. On the DBMS Schemas for Catalog page, click APP.

      Figure E-10 Browse DBMS Table Types Page

      
       

   6. On the DBMS Table Types page, click TABLE.

      Figure E-11 DBMS Browse Tables Page

      
       

   7. On the Tables list for APP page, click CUSTOMER_TABLE. The Browse window now displays the names and types of the columns.

      Figure E-12 Browse DBMS for Table Page

      
       

   8. Click Close Window to close the window and return to the Add Service Page.

      This window is included in the tour to introduce you to available functionality; you are not required to select any text for this exercise.

   9. On the Service Page, add the following information to the SQL Statement field:

      Insert into APP.CUSTOMER_TABLE (FIRSTNAME, LASTNAME, DOB) VALUES ([FIRSTNAME VARCHAR], [LASTNAME VARCHAR], [DOB DATE])

   10. Click Add. The Application View Administration page is displayed.

       For additional information about adding services, see Defining an Application View in Using Application Integration.

7. Add an event to your application view. To do so, you must provide a unique name and a description of the event. Then you must specify the database table to which a trigger should be added for the event. You must also specify whether the event is an insert, update, or delete event.

   You can use the Browse DBMS link to browse the DBMS database schemas and tables and to specify the database table. Then you can have the field populated automatically with the specified table name.

   To add an event:

   1. On the Application View Administration page, click Add in the Events field. The Add Event page is displayed.

      Figure E-13 Add Event Page

      
       

   2. In the Unique Event Name field, enter CustomerInserted.

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

   4. Click the Browse DBMS link to view the table and column structure of the database.

      Figure E-14 Browse DBMS Tables Page

      
       

   5. Select the CUSTOMER TABLE option. Then click Fill table name with selected table.

      Figure E-15 Add Event Page

      
       

   6. Select the Insert Event option.

   7. Click Add. The Application View Administration page is displayed.

      Figure E-16 Application View Administration Page for AppViewTest

      
       

8. Prepare to deploy the application view. The Application View Administration page provides a single location at which you can confirm the content of your application view before saving or deploying it. On this page, you can:

   • Confirm or edit the description of the application view.

   • Confirm or reconfigure the connection criteria for the application view.

   • Delete services and events.

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

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

9. Deploy the Application View. To do so, you must define several parameters, including the following: enable asynchronous service invocation, the event router URL, and the connection pool parameters.

   Figure E-17 Display Application View to Server Page

   
    

   To deploy the application view:

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

   2. In the Event Router URL field, enter:

      http://localhost:7001/DbmsEventRouter/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 (selected)

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

   5. Make sure the Deploy persistently? option is selected.

   6. Click the Restrict Access link. The Application View Security page is displayed.

10. Set permissions for the application view. You can grant or revoke read and write access for a user or a group.

    Figure E-18 Application View Security Page

    
     

    To set permissions for the application view:

    1. For Choose an Action, select the Revoke option.

    2. In the Specify a User or Group, enter Jdoe.

    3. For Permission: select the Write (Deploy/Undeploy/Edit App View) option.

    4. Click Done. The Deploy Application View Page is displayed.

    5. Click Deploy.

11. Once the application view is deployed, all relevant information about it is displayed on the Summary for Application View page. Use this page to view schemas, event summaries, and service summaries, to test services and events, and to undeploy the application view.

    Figure E-19 Summary for Application View Page

    
     

12. Test an event. To ensure that the application view is working correctly, you can test the events and services shown in it. You can test an event by invoking a service or by manually creating the event. The user can also specify how long the application should wait to receive the event.

    1. In the Events group, on the CustomerInserted line, click Test. The Test Event page is displayed.

       Figure E-20 Test Event Page

       
        

    2. On the Test Event page select the Service option and, from the Service menu, InsertCustomer.

    3. In the How long should we wait to receive the event? field, enter 6000.

    4. Click Test. The Test Service page is displayed.

       Figure E-21 Test Service Page

       
        

    5. In the FIRSTNAME field, enter a first name.

    6. In the LASTNAME field, enter a last name.

    7. In the DOB field, enter a date of birth. The correct format is specified to the right of the DOB field.

    8. Click Test. The Test Result page is displayed. It shows the contents of the XML documents representing the event you generated and the response generated by the application view.

       Figure E-22 Test Result Page

       
        

 

---

How the DBMS Sample Adapter Was Developed

This section describes each interface used to develop the DBMS sample adapter. The ADK provides many of the necessary implementations required by a Java Connector Architecture-compliant adapter, but some interfaces cannot be implemented fully until the EIS and its environment are defined. For this reason the DBMS sample adapter was created as a concrete implementation of the abstract classes provided by the ADK.

The procedure for creating the DBMS sample adapter includes the following steps:

• Step 1: Learn About the DBMS Sample Adapter

• Step 2: Define Your Environment

• Step 3: Implement the Server Provider Interface Package

• Step 4: Implement the Common Client Interface Package

• Step 5: Implement the Event Package

• Step 6: Deploy the DBMS Sample Adapter

Step 1: Learn About the DBMS Sample Adapter

To learn how the implementations provided by the ADK are leveraged in the DBMS sample adapter, we recommend that you review the Javadoc and code for the methods defined in this section.

• For the Javadoc, see:

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

• For the code listing for this package, see:

  WLI_HOME/adapters/dbms/src/com/bea/adapter/dbms/spi

Note: WLI_HOME is the drive or directory in which WebLogic Integration is installed.

Step 2: Define Your Environment

The Adapter Setup Worksheet (see 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 DBMS 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?

   PointBase, SQLServer, Oracle, or Sybase databases.

2. *What version of the EIS are you using?

   PointBase 4.0, MSSQLServer 7.0, Oracle 8.1.6, or Sybase 11.9.2.

3. *Which type of EIS (such as DBMS or ERP) are you using?

   DBMS

4. *What is the name of the vendor for this adapter?

   BEA

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

   None - Sample Only

6. *What is the logical name of the adapter?

   BEA_WLS_DBMS_ADK

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

   Yes

   If so, then your adapter must support services.

   Yes

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

   JDBC

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

   Database URL, driver class, user name, password

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

    Function name, executeUpdate, executeQuery

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

    Yes, you can browse data structures.

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

    SQL

12. Which of the input requirements are static across all requests? Your adapter should encode static information in an InteractionSpec object.

    SQL

13. Which of the input requirements are dynamic per request? Your adapter should provide an XML schema that describes the input parameters required by this service per request.

    The input requirements would change depending on the SQL expression for the service.

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

    N/A

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

    Yes

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

    Yes

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

    None. The DBMS sample adapter was built on the WebLogic Integration event generator using a pull mechanism.

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

    Yes

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

    Yes

20. What locales (defined by language and country) does your adapter need to support?

    Multiple

Step 3: Implement the Server Provider Interface Package

To implement the DBMS sample 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 E-1 SPI Class Extensions

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

 

These classes provide connectivity to an EIS and establish a framework for event listening and request transmission, establish transaction demarcation, and allow management of a selected EIS.

ManagedConnectionFactoryImpl

The first step in implementing an SPI for the DBMS sample 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 DBMS sample adapter extends this class in com.bea.adapter.dbms.spi.ManagedConnectionFactoryImpl. Listing  E-1 shows the derivation tree for ManagedConnectionFactoryImpl.

Listing E-1 com.bea.adapter.dbms.spi.ManagedConnectionFactoryImpl

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

Developers' Comments

The ManagedConnectionFactory is the central class of the Java Connector Architecture SPI package. The ADK's AbstractManagedConnectionFactory provides much of the required implementation for the methods declared in Sun MicroSystems' interface. To extend the ADK's AbstractManagedConnectionFactory for the DBMS sample adapter, the key createConnectionFactory() and createManagedConnection() methods were implemented. Overrides for equals(), hashcode(), checkState() were also written to provide specific behaviors for the databases supported by the DBMS sample adapter.

There are private attributes about which the superclass has no knowledge. When creating your adapters, you must provide setter/getter methods for these attributes. The abstract createConnectionFactory() method is implemented to provide an EIS-specific ConnectionFactory using the input parameters.

Additionally, createManagedConnection() is the main factory method of the class. It checks to see if the adapter is configured properly before doing anything else. It then implements methods of the superclass to get a connection and a password credential object. It then attempts to open a physical database connection; if this succeeds, it instantiates and returns a ManagedConnectionImpl (the DBMS sample adapter implementation of ManagedConnection), which is given the physical connection.

Other methods are getter/setter methods for member attributes.

ManagedConnectionImpl

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 DBMS sample adapter extends this class in com.bea.adapter.dbms. spi.ManagedConnectionImpl. Listing  E-2 shows the derivation tree for ManagedConnectionImpl.

Listing E-2 com.bea.adapter.dbms.spi.ManagedConnectionImpl

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

Developers' Comments

This class is thoroughly documented in the Javadoc comments because the ManagedConnection is a crucial part of the Java Connector Architecture SPI specification. You should focus on our implementation of the following methods:

• java.lang.object.getConnection(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo connectionRequestInfo)

• protected void destroyPhysicalConnection(java.lang.Object objPhysicalConnection)

• protected void destroyConnectionHandle(java.lang.Object objHandle)

• boolean compareCredentials(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo info)

The ping() method is used to check whether a physical database connection (not our cci.Connection) is still valid. If an exception occurs, ping() is specific about checking the type so that a connection is not needlessly destroyed.

Other methods are EIS-specific or are simply required setters or getters.

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

Basic Implementation

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

Listing E-3 com.bea.adapter.dbms.spi.ConnectionMetaDataImpl

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

Developers' Comments

The ADK's AbstractConnectionMetaData class implements the following:

• javax.resource.cci.ConnectionMetaData

• javax.resource.spi.ManagedConnectionMetaData

This implementation of the ConnectionMetaData class uses a DatabaseMetaData object. Because the ADK's abstract implementation was used, you must provide EIS-specific knowledge when implementing the abstract methods in this class.

LocalTransactionImpl

The LocalTransaction interface provides support for transactions that are managed within an EIS resource manager (that is, transactions that do not require an external transaction manager). For more information, read about how the ADK implements the AbstractLocalTransaction instance in LocalTransaction.

Basic Implementation

The ADK provides com.bea.adapter.spi.AbstractLocalTransaction, an implementation of the J2EE interface javax.resource.spi.LocalTransaction. The DBMS sample adapter extends this class in com.bea.adapter.dbms. spi.LocalTransactionImpl. Listing  E-4 shows the derivation tree for LocalTransactionImpl.

Listing E-4 com.bea.adapter.dbms.spi.LocalTransactionImpl

javax.resource.spi.LocalTransaction
|
|-->com.bea.adapter.spi.AbstractLocalTransaction
|
|-->com.bea.adapter.dbms.spi.LocalTransactionImpl

Developers' Comments

This class utilizes the ADK's abstract superclass which provides logging and event notification. The superclass implements both the CCI and SPI LocalTransaction interfaces provided by Sun. The DBMS sample adapter's concrete class implements the three abstract methods of the superclass:

• doBeginTx()

• doCommitTx()

• doRollbackTx()

Step 4: Implement the Common Client Interface Package

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

Table E-2 CCI Class Extensions

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

 

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

Note: Although implementation of the CCI is optional in the Java Connector Architecture 1.0 specification, it is likely to be required in the future. For your reference, the DBMS sample adapter provides a complete implementation.

ConnectionImpl

A Connection represents an application-level handle that is used by a client to access an underlying physical connection. The actual physical connection associated with a Connection instance is represented by 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 DBMS sample adapter extends this class in com.bea.adapter.dbms.cci.ConnectionImpl. Listing  E-5 shows the derivation tree for ConnectionImpl.

Listing E-5 com.bea.adapter.dbms.cci.ConnectionImpl

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

Developers' Comments

The ConnectionImpl class is the DBMS sample adapter's concrete implementation of the javax.resource.cci.Connection interface. It extends the ADK's AbstractConnection class. The actual physical connection associated with a connection instance is represented by a ManagedConnection instance.

A client gets a connection instance by using the getConnection() method on a ConnectionFactory instance. A connection can be associated with zero or more interaction instances. The simplicity of this concrete class is a testament to the power of extending the ADK's base classes.

InteractionImpl

The Interaction instance 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 DBMS sample adapter extends this class in com.bea.adapter.dbms.cci. InteractionImpl. Listing  E-6 shows the derivation tree for InteractionImpl.

Listing E-6 com.bea.adapter.dbms.cci.InteractionImpl

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

Developers' Comments

The InteractionImpl class is the concrete implementation of the ADK's Interaction object. The methods are EIS-specific implementations of methods required by the Java Connector Architecture and the ADK.

Both versions of the Java Connector Architecture's javax.resource.cci.InteractionExecute()method (the central method of this class) were implemented for the DBMS sample adapter. The main logic for the execute() method includes the following signature:

public Record execute(InteractionSpec ispec, Record input)

Because this method returns the actual output record from the interaction, it is called more often than other methods.

The second implementation is provided as a convenience method. This form of execute() includes the following signature: public boolean execute(InteractionSpec ispec, Record input, Record output). The second implementation's logic returns a boolean, which indicates only the success or failure of the interaction.

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 convention followed in the getter and setter methods 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 DBMS sample adapter extends this class in com.bea.adapter.dbms. cci.InteractionSpecImpl. Listing  E-7 shows the derivation tree for InteractionSpecImpl.

Listing E-7 com.bea.adapter.dbms.cci.InteractionSpecImpl

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

Developers' Comments

An implementation class for the InteractionSpec interface is required to implement the java.io.Serializable interface. InteractionSpec extends the ADK InteractionSpec in order to add setter and getter methods for the String attribute m_sql. The getter and setter methods should be based on the Java Beans design pattern, as specified in the Java Connector Architecture 1.0 specification.

Step 5: Implement the Event Package

This package contains only one class: the DBMS sample adapter EventGeneratorWorker. It does the work for the event generator for the DBMS sample adapter.

EventGenerator

The EventGenerator class implements the following interfaces:

• com.bea.wlai.event.IEventGenerator

• java.lang.Runnable

Basic Implementation

The DBMS sample adapter event generator extends the ADK's AbstractPullEventGenerator because a database cannot push information to the event generator; you therefore need to pull or poll the database for changes about which you want to be notified. Listing  E-8 shows the derivation tree for EventGenerator.

Listing E-8 EventGenerator

com.bea.adapter.event.AbstractEventGenerator
|
|-->com.bea.adapter.event.AbstractPullEventGenerator
|
|-->com.bea.adapter.dbms.event.DbmsEventGeneratorWorker

Developers' Comments

This concrete implementation of the ADK's AbstractPullEventGenerator implements the following abstract methods:

• protected abstract void postEvents(IEventRouter router) throws Exception

• protected abstract void setupNewTypes(List listOfNewTypes)

• protected abstract void removeDeadTypes(List listOfDeadTypes).

It also overrides the following methods:

• void doInit(Map map)

• void doCleanUpOnQuit().

These methods are EIS-specific: they are used to identify an event within the context of the EIS while interacting with the database to create and remove event definitions and events. Additionally, these methods can be used to create and remove triggers on the database that are activated when an event occurs.

The key method of the class is postEvents(). It creates the IEvent objects of the data taken from rows in the EVENT table of the database. This method takes an IEventRouter as an argument. After creating an IEvent using the IEventDefinition object's createDefaultEvent() method, the postEvents() method populates the event data propagates the event to the router by calling router.postEvent(event). Once the event is sent to the router, the method deletes the relevant rows of event data from the database.

The method setupNewTypes()creates new event definitions, making sure that the appropriate triggers are created for the database. For each event definition, the method creates a trigger information object that describes the catalog, schema, table, triggerType, and trigger key represented by the event definition. A map of trigger keys is maintained so that triggers are not redundantly added to the database. If the map does not contain the new key, trigger text for the database is generated.

The method removeDeadTypes() also creates a trigger information object, but this object also searches for one or more matching event types. All event definitions that match this trigger are removed from the map, and then the trigger itself is removed from the database.

Step 6: Deploy the DBMS Sample Adapter

After implementing the SPI, CCI, and event interfaces, deploy the adapter by completing the following steps:

• Step 6a: Set Up Your Environment

• Step 6b: Update the ra.xml File

• Step 6c: Create the RAR File

• Step 6d: Build the JAR and EAR Files

• Step 6e: Create and Deploy the EAR File

Step 6a: Set Up Your Environment

Before deploying the adapter in a WebLogic Integration environment, determine the location of the adapter on your computer. The adapter resides in WLI_HOME/adapters/dbms. You must replace WLI_HOME with the pathname for the directory in which WebLogic Integration is installed. We refer to this location as ADAPTER_ROOT.

Step 6b: Update the ra.xml File

The DBMS sample adapter provides the ra.xml file in the adapter's RAR file (META-INF/ra.xml). Because the DBMS sample adapter extends the AbstactManagedConnectionFactory class, the following properties are provided in the ra.xml file:

• LogLevel

• LanguageCode

• CountryCode

• MessageBundleBase

• LogConfigFile

• RootLogContext

• AdditionalLogContext

The DBMS sample adapter also requires the declarations listed in the following table.

Table E-3 ra.xml Properties

Property	Example
UserName	Username for DBMS sample adapter login
Password	Password for username
DataSourceName	Name of the JDBC connection pool

 

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

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

Step 6c: Create the RAR File

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

Step 6d: Build the JAR and EAR Files

To build the JAR and EAR files, complete the following procedure:

1. In a text editor, open either antEnv.cmd (Windows) or antEnv.sh (UNIX) in WLI_HOME/adapters/utils. Assign valid pathnames to the following variables:

   • 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 installation, such as WLI_HOME/adapters/utils.

2. Execute antEnv from the command line so the new values of the required environment variables take effect.

3. Go to WLI_HOME/adapters/dbms/project.

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

Step 6e: Create and Deploy the EAR File

The DBMS sample adapter is displayed by creating and deploying an EAR file. To do so, complete the following procedure:

1. Declare the adapter's EAR file in your domain's config.xml file, as shown in the following listing.

Listing E-9 Declaring the DBMS Sample Adapter's EAR File

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

<Application Deployed="true" Name="BEA_WLS_DBMS_ADK" Path="WLI_HOME/adapters/dbms/lib/BEA_WLS_DBMS_ADK.ear">

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

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

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

</Application>

Note: Replace WLI_HOME with the pathname of the WebLogic Integration installation directory for your environment.

2. Open the WebLogic Server Administration Console by entering:

   http://host:port/console

   In this URL host is the name of your server and port is the port at which your server listens. For example:

   http://localhost:7001/console

3. In the WebLogic Server Administration Console:

   1. Add the adapter group to the default WebLogic Server security realm.

   2. Add a user to the adapter group.

   3. Save your changes.

4. To configure and deploy application views, go to:

   http://host:port/wlai

   In this URL host is the name of your server and port is the port at which your server listens. For example:

   http://localhost:7001/wlai

   The Application View Console - Logon page is displayed.

   
    

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

6. Configure and deploy your application views by completing the procedures described in Defining Application Views in Using Application Integration.

 

---

How the DBMS Sample Adapter Design-Time GUI Was Developed

The design-time GUI is an interface that allows a user to create application views, add services and events, and deploy an adapter that is hosted in a WebLogic Integration environment. This section explains how the design-time GUI for the DBMS sample adapter was developed:

• Step 1: Identify Requirements

• Step 2: Identify Required Java Server Pages

• Step 3: Create the Message Bundle

• Step 4: Implement the Design-Time GUI

• Step 5: Write Java Server Pages

Step 1: Identify Requirements

Before development of the design-time GUI for the DBMS was begun, values for the following parameters needed to be determined:

• Which database(s) will be supported?

• How many levels of browsing will be supported?

• Determine the DBMS schema generation.

• Will the adapter support testing of services and events?

Step 2: Identify Required Java Server Pages

The DBMS sample adapter uses the Java Server Pages (JSPs) delivered with the ADK for a design-time GUI. Additional JSPs have been added, however, to provide adapter-specific functionality. The additional JSPs are described in the following table.

Table E-4 Additional ADK JSPs  

Filename	Description
addevent.jsp	The Add Event page allows a user to add a new event to the application view.
addservice.jsp	The Add Service page allows the user to add a new service to the application view.
browse.jsp	The Browse page handles the logic flow and display for the Browse window of the DBMS sample adapter. Although this functionality was developed specifically for this adapter, it illustrates a fairly common interaction between a design-time interface and an underlying adapter. The Browse page calls the DesignTimeRequestHandler (handler) of the DBMS sample adapter, which extends the ADK's AbstractDesignTimeRequestHandler. The best way to understand the browse functionality of the DBMS sample adapter is to deploy the adapter and use your Web browser to access the design-time framework.
confconn.jsp	The Confirm Connection page provides a form on which a user can specify connection parameters for the EIS.
testform.jsp	The Testform page is included (<jsp:include page='testform.jsp'/>) in the ADK's testsrvc.jsp page. It accesses the InteractionSpec for this interaction and displays the SQL for the service. It then creates a form for gathering the user input required to test a service. To create a form, Testform gets the RequestDocumentDefinition from the handler's application view and then passes it, with the .jsp Writer, to a utility class called com.bea.adapter.dbms.utils.TestFormBuilder. This class creates the form.

 

Step 3: Create the Message Bundle

To support the internationalization of all text labels, messages, and exceptions, the DBMS sample adapter uses a message bundle based on a text property file. The property file includes both name-value pairs copied from the BEA_WLS_SAMPLE_ADK property file, and new entries, added for properties specific to the DBMS sample adapter.

The message bundle for the DBMS sample adapter resides in the WLI_HOME/adapters/dbms/src directory, which was installed with the ADK. For details, see the BEA_WLS_DBMS_ADK.properties file in the same directory.

For additional instructions on creating a message bundle, see the JavaSoft tutorial on internationalization at:

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

Step 4: Implement 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 provides methods to perform a design-time action. For more information about the DesignTimeRequestHandler, see Step 4: Implement the Design-Time GUI.

The DBMS sample adapter public class DesignTimeRequestHandler extends AbstractDesignTimeRequestHandler, and it provides the methods shown in the following table.

Table E-5 Methods for the DBMS Sample Adapter Design-Time GUI  

Method	Description
browse(java.lang.String dbtype, com.bea.connector.DocumentRecord input)	Handles the back-end behavior for the Browse functionality of the addevent.jsp and addservc.jsp pages.
getAdapterLogicalName()	Returns the adapter's logical name and helps the parent class when entities such as application views are deployed.
getManagedConnectionFactoryClass()	Returns the adapter's SPI ManagedConnectionFactory implementation class, which is then used by a parent class to get a CCI connection to the EIS.
supportsServiceTest()	Indicates that this adapter supports the testing of services at design time.
initServiceDescriptor(ActionResult result, IServiceDescriptor sd, HttpServletRequest request)	Initializes a service descriptor, which involves creating the request and response schemas for a service. A typical approach is to execute an Interaction against the EIS to retrieve metadata and then transform that metadata into an XML schema. Consequently, the CCI interface provided by the adapter was used. This method is called from the addsrvc method of the AbstractDesignTimeRequestHandler.
initEventDescriptor(ActionResult result, IEventDescriptor ed, HttpServletRequest request)	Initializes an event descriptor. The event descriptor provides information about an event on an application view. Subclasses must supply an implementation of this method. If events are not supported, then the implementation should throw an UnsupportedOperationException. This method is not called (by the AbstractDesignTimeRequestHandler) until the name and definition of the event have been validated and it is confirmed that the event does not already exist for the application view.
GetDatabaseType()	Used to determine the type of database management system being used. WebLogic Integration supports PointBase, Oracle, Microsoft SQL Server, and Sybase.

 

Step 5: Write Java Server Pages

Consider incorporating the following practices into your development process:

• Use Custom JSP Tags

• Save an Object's State

• Write the WEB-INF/web.xml Deployment Descriptor

Use Custom JSP Tags

Because the Java Server Pages (JSPs) are displayed on the display.jsp page, display.jsp is the first .jsp file that needs to be written. The ADK provides a library of custom JSP tags, which are used extensively throughout the Java server pages of the ADK and DBMS sample adapter. These tags support numerous features, such as the ability to add validation and to save a value entered in a field when the user clicks a button.

Save an Object's State

While writing the JSPs, with the ADK, for your adapter, you may need to save an object's state. You can do so in any of a number of ways. The AbstractDesignTimeRequestHandler maintains an ApplicationViewDescriptor of the application view being edited. This [file?] is often the best place in which to save state; calls to the handler from this file are fast and efficient.

As an alternative, you can request a Manager Bean from the AbstractDesignTimeRequestHandler, using its convenience methods (getApplicationViewManager(), getSchemaManager(), and getNamespaceManager()) to retrieve information from the repository about an application view. This method is more time-consuming but, occasionally, it may be necessary. Because 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.

Write the WEB-INF/web.xml Deployment Descriptor

Write the WEB-INF/web.xml deployment descriptor. In most cases, you should use the adapter's web.xml file as a starting point and modify components as necessary. To see the web.xml file for this adapter, go to:

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

For detailed information, see the BEA WebLogic Server product documentation at:

http://www.oracle.com/technology/documentation/index.html