The DBMS Adapter

 

This section contains information on the following subjects:

• Introduction to the DBMS Adapter

• How the DBMS Adapter Works

• How the DBMS Adapter Was Developed

• How the DBMS Adapter Design-Time GUI was Developed

 

---

Introduction to the DBMS Adapter

The DBMS adapter is a J2EE-compliant adapter built with the ADK. It provides a concrete example for adapter providers of how one might use the ADK to construct an adapter. A relational database was used as the EIS of an adapter because it allows adapter providers to focus on the adapter/ADK specifics, rather than become bogged-down in understanding a particular proprietary EIS.

The DBMS 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 might enjoy running through the interface to get a better understanding of an "application view", "service", and "event" as shown in How the DBMS Adapter Works.

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

The DBMS adapter satisfies the following requirements:

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

• Uses the classes and tools of the ADK.

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

• Allow users to test events and services.

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

• Supports the creation of services that perform selects, inserts, deletes, and updates against the database (EIS).

 

---

How the DBMS Adapter Works

This section provides you with an opportunity to see how the DBMS adapter works before you start developing one of your own. 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 then demonstrates how an event is generated to notify others that this action has taken place.

This section contains information on the following subjects:

• Before You Begin

• Accessing the DBMS Adapter

• A Tour of the DBMS Adapter

Before You Begin

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

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

• Set up the ADK Ant-Based Make Process (see Step 2c: Setting Up the Build Process).

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

Accessing the DBMS Adapter

To access the DBMS adapter:

1. Open a new browser window.

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

   http://<HOSTNAME>:7001/wlai

   The Application Integration Console - Logon page displays.

   Figure E-1 Application View Console - Logon

   
    

A Tour of the DBMS Adapter

This section provides you with a short tour through the DBMS Adapter. Before you begin, you need to open the DBMS adapter Application View Console - Logon page on your browser. For information about accessing the DBMS adapter, see Accessing the DBMS Adapter.

Figure E-2 Application View Console - Logon

 
 

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.

   Figure E-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 DBMS adapter.

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

   Figure E-4 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. 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 DBMS adapter to use to create this application view.

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

      Figure E-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 WebLogic User Name and WebLogic Password.

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

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

      The Application View 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 E-6 Application View Administration Page for AppViewTest

      
       
       

5. Now that you have created an application view, you are ready to add a service to it. To add the service you must supply a name for the service, provide a description and enter the SQL statement.

   You can use the browse link to browse the DBMS adapter database schemas and tables and 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 displays.

      Figure E-7 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 leave the Browse window open in order to cut and paste table or column names into your query.

      Figure E-8 Browse DBMS Page

      
       

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

      Figure E-9 Browse DBMS Table Types Page

      
       

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

      Figure E-10 DBMS Browse Tables Page

      
       

   7. In the Tables list for APP page, click CUSTOMER_TABLE. The Browse window now displays the column names and column types.

      Figure E-11 Browse DBMS for Table Page

      
       

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

      This window is included in the tour to introduce you to the functionality and it is not necessary to select any text for this exercise.

   9. In the Service Page, add the following information into 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 the Using Application Integration.

6. Add an event to your application view. In order to add an event, you must provide a unique event name and a description. Then you must specify the database table upon which a trigger should be added for the event. You must also specify if it 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 automatically populate the field with the selected table name.

   To add an event:

   1. In the Application View Administration page, click Add in the Events field. The Add Event page displays.

      Figure E-12 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-13 Browse DBMS Tables Page

      
       

   5. Select the CUSTOMER TABLE radio button, and click Fill table name with selected table.

      Figure E-14 Add Event Page

      
       

   6. Select the Insert Event radio button.

   7. When finished, click Add. The Application View Administration page displays.

      Figure E-15 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.

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.

   Figure E-16 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 - checked

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

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

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

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

   Figure E-17 Application View Security Page

   
    

   To set permissions for the application view:

   1. For Choose an Action, select the Revoke radio button.

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

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

   4. Click Done. The Deploy Application View Page displays.

   5. Click Deploy.

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

    Figure E-18 Summary for Application View Page

    
     

11. Test an event. To ensure that the application view is working correctly, you can test the events and services in the application view. 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 displays.

       Figure E-19 Test Event Page

       
        

    2. In the Test Event page, select the Service radio button, and select InsertCustomer in the Service menu.

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

    4. Click Test. The Test Service page appears.

       Figure E-20 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 edit box.

    8. Click Test. The Test Result page displays to show the contents of the XML documents representing the event you generated and the response generated by the application view.

       Figure E-21 Test Result Page

       
        

 

---

How the DBMS Adapter Was Developed

This section describes each interface used to develop the DBMS 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 DBMS adapter was created to illustrate the detail-specific or concrete implementation of the abstract classes provided in the ADK.

The process of creating the DBMS 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 DBMS 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/dbms/src/com/bea/adapter/dbms/spi

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

Step 1: Development Considerations

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

   SQLServer or Oracle databases.

2. *What is the version of the EIS?

   MSSQLServer 7.0 or Oracle 8.1.6

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

   DBMS

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

   BEA

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

   None - Sample Only

6. *What is the adapter logical name?

   BEA_WLS_DBMS_ADK

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?

   JDBC

9. What information is needed to create a session/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. For all the input requirements, which ones are static across all requests? Your adapter should encode static information into an InteractionSpec object.

    SQL

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.

    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 your adapter can invoke? If so, your adapter should support browsing of services.

    Yes

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

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.

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

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

    Yes

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

    Yes

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

    Multiple

Step 2: Implementing the Server Provider Interface Package

To implement the DBMS 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 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 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 ADKs AbstractManagedConnectionFactory provides much of the required implementation for the methods declared in Sun MicroSystems' interface. To extend the ADKs AbstractManagedConnectionFactory for the DBMS 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 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 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 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 well documented in the Javadoc comments since 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 the physical database connection (not our cci.Connection) is still valid. If an exception occurs, ping() is very specific about checking the type so that a connection is not needlessly destroyed.

Other methods are EIS specific or are simply required setter/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 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 ADKs AbstractConnectionMetaData implements the following:

• javax.resource.cci.ConnectionMetaData

• javax.resource.spi.ManagedConnectionMetaData

This implementation of the ConnectionMetaData class uses a DatabaseMetaData object. Since 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 internal to an EIS resource manager and 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 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 ADKs abstract superclass which provides logging and event notification. The superclass implements both the CCI and SPI LocalTransaction interfaces provided by Sun. The DBMS adapter's concrete class implements the three abstract methods of the superclass:

• doBeginTx()

• doCommitTx()

• doRollbackTx()

Step 3: Implementing the Common Client Interface Package

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

Table E-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 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 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 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 adapter in by implementing 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 adapter's concrete implementation of the javax.resource.cci.Connection interface. It extends the ADKs 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 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 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

This is the concrete implementation of the ADKs Interaction object. As expected, the methods are EIS-specific implementations of Java Connector Architecture/ADK required methods.

Both versions of the Java Connector Architecture's javax.resource.cci.InteractionExecute()method (the central method of this class) were implemented. The main logic for the execute() method has the following signature: public Record execute(InteractionSpec ispec, Record input). This method return the actual output record from the interaction, so it is the one that is called more often.

The second implementation is provided as a convenience method. This form of execute() has 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 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 DBMS 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 InteractionSpec interface is required to implement the java.io.Serializable interface. InteractionSpec extends the ADK InteractionSpec in order to add setter/getter methods for the String attribute m_sql. The getter/setter methods should be based on the Java Beans design pattern as specified in the Java Connector Architecture 1.0 specification.

Step 4: Implementing the Event Package

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

EventGenerator

The EventGenerator class implements the following interfaces:

• com.bea.wlai.event.IEventGenerator

• java.lang.Runnable

Basic Implementation

The DBMS adapter event generator extends the ADK's AbstractPullEventGenerator because a database cannot "push" information to the event generator; you therefore need to "pull" or actually "poll" the database for changes about which you are interested in being 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 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 and 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 create and remove the actual triggers on the database that are fired 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, it populates the event data, and the event is propagated to the router by calling router.postEvent(event). Once the event is sent to the router, the method deletes the row of event data from the database.

The method setupNewTypes()creates new event definitions, making sure that the appropriate trigger is 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 that the event definition represents. A map of trigger keys is kept so that triggers are not redundantly added to the database. If the map doesn't contain the new key, the trigger text for the database is generated.

The method removeDeadTypes() also creates a trigger information object; however, it also checks if one or more event types match it. All event definitions that match this trigger are removed from the map, and then the trigger is removed from the database.

Step 5: Deploying the DBMS Adapter

After implementing the SPI, CCI and event interfaces, deploy the adapter. To deploy the adapter, use the procedures outlined in this section:

• Before You Begin

• Step 5a: Update the ra.xml File

• Step 5b: Create the .rar File

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

• Step 5d: 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/dbms where WLI_HOME is the location of your WebLogic Integration installation. This location is referred to as ADAPTER_ROOT hereafter.

• Make sure the DBMS adapter's .jar and .ear files are built, as described in Step 5: Deploying the DBMS Adapter.

Step 5a: Update the ra.xml File

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

• LogLevel

• LanguageCode

• CountryCode

• MessageBundleBase

• LogConfigFile

• RootLogContext

• AdditionalLogContext

The DBMS adapter requires these additional declarations:

Table E-3 ra.xml Properties

 

Property	Example
UserName	The username for DBMS adapter login.
Password	The password for username.
DataSourceName	The name of the JDBC connection pool.

 

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

WLI_HOME/adapters/dbms/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/dbms/project.

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

Step 5d: Create and Deploy the .ear File

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

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

   Listing E-9 Declaring the DBMS 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 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 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.

 

---

How the DBMS Adapter Design-Time GUI was Developed

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

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

• Step 1: Development Considerations

• Step 2: Determine Necessary Java Server Pages

• 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 DBMS adapter included:

• Determine the database(s) that were going to be supported.

• Determine browsing depth.

• Determine the DBMS schema generation.

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

Step 2: Determine Necessary Java Server Pages

The DBMS adapter uses the ADKs Java Server Pages (JSPs) 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 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 flow logic and display for the Browse window of the DBMS adapter. Although this functionality was developed specifically for this adapter, it illustrates a fairly common interaction between the design-time interface and the underlying adapter. It uses the DesignTimeRequestHandler (handler) of the DBMS adapter, which extends the ADK's AbstractDesignTimeRequestHandler. The best way to understand the browse functionality of the DBMS 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 for a user to 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 on screen. It then creates a form for gathering required user input to test a service. It does this by getting the RequestDocumentDefinition from the handler's application view and then passing it along with the .jsp Writer to a utility class, com.bea.adapter.dbms.utils.TestFormBuilder, which actually creates the required form.

 

Step 3: Create the Message Bundle

To support the internationalization of all text labels, messages and exceptions, the DBMS 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 properties specific to the DBMS adapter.

The message bundle for the DBMS adapter is contained in WLI_HOME/adapters/dbms/src directory, which was installed with the ADK. Please refer to BEA_WLS_DBMS_ADK.properties in the directory above.

For additional instructions on creating a message bundle, 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 provides methods to perform a design-time action. For more information on the DesignTimeRequestHandler, see Step 4: Implementing the Design-Time GUI.

The DBMS adapter public class DesignTimeRequestHandler extends AbstractDesignTimeRequestHandler and it provides the methods shown in Table :

 

Table E-5 Methods for the DBMS 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.
getAdapterLogicalName()	Returns the adapter's logical name and helps parent when deploying application views, etc.
getManagedConnectionFactoryClass()	Returns the adapter's SPI ManagedConnectionFactory implementation class, used by parent to get a CCI connection to the EIS.
supportsServiceTest()	Indicates that this adapter design time supports the testing of services.
initServiceDescriptor(ActionResult result, IServiceDescriptor sd, HttpServletRequest request)	Initializes a service descriptor which involves creating the request and response schemas for the service. A typical approach is to execute an Interaction against the EIS to retrieve metadata and transform it 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 will need to supply an implementation of this method. If events are not supported, then the implementation should throw an UnsupportedOperationException. This method will not be called (by the AbstractDesignTimeRequestHandler) until the event name and definition have been validated and it is confirmed that the event does not already exist for the application view.
GetDatabaseType()	This method is used to determine the type of dbms being used. At present WebLogic Integration supports Oracle and Microsoft SQL Server.

 

Step 5: Writing Java Server Pages

The following issues are relevant for the DBMS adapter, and you may encounter them as you develop your own adapter.

• Custom JSP Tags

• Save an Object's State

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

Custom JSP Tags

The Java Server Pages are displayed within the display.jsp; thus display.jsp is the first .jsp 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 adapter. They provide the ability to add validation, to save field values when the user clicks away, and a number of other features.

Save an Object's State

You may also need to save an object's state as you write the JSPs. 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.

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