Developing Adapters
|
 |
 |
|
|
 |
 |
This section contains information about the following subjects:
The DBMS sample adapters are J2EE-compliant adapters that includes a JSP-based GUI. They provides concrete examples of how an adapter can be constructed by using the WebLogic Integration ADK. A relational database is used as the adapters' EIS to allow adapter providers to focus on details of the adapters and the ADK, instead of investing time to learn about a particular proprietary EIS.
Two DBMS sample adapters are provided:
The DBMS Sample Adapters are intended to help you understand the tasks required to design and develop your own adapter. They are not intended for use in a production environment, nor are they supported in such an environment. Because the adapters are intended as examples, rather than production-ready adapters, they do not include a full set of features and have the following limitations: the adapters are unable to execute complex queries or stored procedures.
Whether you are a developer or a business analyst, the DBMS sample adapters 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 Adapters Work.
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:
The DBMS sample adapters satisfy the following requirements:
When setting connection parameters for these adapters, specify a JDBC Driver and URL. The sample DBMS adapters do not support the specification of a DataSource. Existing service connections which use a DataSource operate as before, but the Application Integration Design Console does not allow you to specify a DataSource for a new adapter.
If you configure a domain using an XA driver, create an additional connection pool for whatever DataSource you create for the event connection.
Do not create two Tx Data Sources that point to the same connection pool. If a transaction uses two different Tx Data Sources which are both pointed to the same connection pool, you will get an XA_PROTO error when you try to access the second connection.
For more information on JDBC DataSources and WebLogic Server, see "JDBC DataSources" in Administration Console Online Help at the following location:
http://download.oracle.com/docs/cd/E13222_01/wls/docs81/ConsoleHelp/jdbc_datasources.html
When using the DBMS sample adapter with a Microsoft SQL Server or Sybase database, use the WebLogic Server Administration Console to enable the TestReservedConnection parameter for the connection pool used for application integration. If the parameter is not enabled, the auto resume or manual resume features do not work and a SQLException similar to the following is thrown:
java.sql.SQLException: [BEA][SQLServer JDBC Driver]No more data
available to read
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 try to access the DBMS sample adapter, make sure you complete the following tasks:
To access the DBMS sample adapter:
http://HOSTNAME:7001/wlai
The Application Integration Design Console Logon page is displayed as shown in Figure E-1.
Warning: You should only have one instance of the Application Integration Design Console running on a single client machine. Running multiple consoles on a single machine may interfere with proper navigation between screens in your web browser.
This section provides a short tour through the DBMS sample adapter. To begin, open the Application Integration Design Console Logon page for the DBMS sample adapter in your browser. For instructions, see Accessing the DBMS Sample Adapter.
Figure E-1 Application Integration Design Console - Logon
Figure E-2 Application View Management Console
For detailed information about application views and how to define them, see Defining an Application View in Using the Application Integration Design Console.
Figure E-3 Define New Application View Page
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.
Figure E-4 Configure Connection Parameters Page
You have finished creating an application view; you can now add a service to it.
Figure E-5 Application View Administration Page for AppViewTest
Use the browse link to browse the DBMS sample adapter database schemas and tables and to specify the database table CUSTOMER_TABLE.
Figure E-8 Browse DBMS Table Types Page
Figure E-9 DBMS Browse Tables Page
Figure E-10 Browse DBMS for Table 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.
Insert into WEBLOGIC.CUSTOMER_TABLE (FIRSTNAME, LASTNAME, DOB) VALUES ([FIRSTNAME VARCHAR], [LASTNAME VARCHAR], [DOB DATE])
For additional information about adding services, see Defining an Application View in Using the Application Integration Design Console.
You can use the Browse DBMS link to browse the DBMS database schemas and tables and to specify the database table. Then you can click the Fill table name with selected table button to populate the field automatically with the specified table name.
Figure E-12 Browse DBMS Tables Page
Figure E-14 Application View Administration Page for AppViewTest
The Edit Event Connection page allows you to define event parameters and configure what information will be logged for the connection factory. Select one of the following settings for the log:
Locate Connection Parameters and click Define to set the event delivery parameters. The Configure Event Delivery Parameters page is displayed.
The event delivery parameters you enter on this page enable connection to an EIS instance and are used when generating events. The properties are specific to the associated adapter and are defined in the wli-ra.xml file within the base adapter.
Figure E-15 Summary for Application View Page
After successfully testing events and services, you can return to the Summary page and publish the application view. This generates an EJB within the application directory, publishes schema files to the WebLogic Workshop application for use in the XML Mapper, and makes the application view visible within WebLogic Workshop.
For more information on publishing application views, see Defining an Application View in Using the Application Integration Design Console.
This section describes each interface used to develop the DBMS sample adapters. 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 adapters were created as a concrete implementation of the abstract classes provided by the ADK.
The procedure for creating the DBMS sample adapters includes the following steps:
To learn how the implementations provided by the ADK are leveraged in the DBMS sample adapters, we recommend that you review the Javadoc and code for the methods defined in this section.
Note: WLI_HOME is the drive or directory in which BEA WebLogic Integration is installed.
To help you identify and collect critical information about the adapter you are developing before you begin coding, see the Adapter Setup Worksheet. For the DBMS sample adapter BEA_WLS_DBMS_ADK, the worksheet questions are answered as follows:
Note: Questions preceded by an asterisk (*) are required to use the GenerateAdapterTemplate utility.
Yes, you can browse data structures.
If so, what information is needed to determine the input requirements for the service?
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:
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.
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.
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
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.
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.
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
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.
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.
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
The ADK's AbstractConnectionMetaData class implements the following:
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.
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.
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
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:
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.
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.
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.
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
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.
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.
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
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.
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.
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
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.
This package contains only one class: the DBMS sample adapter EventGeneratorWorker. It does the work for the event generator for the DBMS sample adapter.
The EventGenerator class implements the following interfaces:
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.
com.bea.adapter.event.AbstractEventGenerator
|
|-->com.bea.adapter.event.AbstractPullEventGenerator
|
|-->com.bea.adapter.dbms.event.DbmsEventGeneratorWorker
This concrete implementation of the ADK's AbstractPullEventGenerator implements the following abstract methods:
protected abstract void postEvents(IEventRouter router) throws Exceptionprotected abstract void setupNewTypes(List listOfNewTypes)protected abstract void removeDeadTypes(List listOfDeadTypes).It also overrides the following methods:
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.
After implementing the SPI, CCI, and event interfaces, deploy the adapter by completing the following steps:
Before deploying the adapter in a BEA 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 BEA WebLogic Integration is installed. We refer to this location as ADAPTER_ROOT.
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:
LogLevelLanguageCodeCountryCodeMessageBundleBaseLogConfigFileRootLogContextAdditionalLogContextThe DBMS sample adapter also requires the declarations listed in the following table.
You can view the complete ra.xml file for the DBMS sample adapter in:
WLI_HOME/adapters/dbms/src/rar/META-INF/
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.
To build the JAR and EAR files, complete the following procedure:
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.The DBMS sample adapter is displayed by creating and deploying an EAR file. To do so, complete the following procedure:
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 BEA WebLogic Integration installation directory for your environment.
In this URL host is the name of your server and port is the port at which your server listens. For example:
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 Integration Design Console Logon page is displayed.
" title="Test Result Page
" width="456" height="269" align="middle" border="0" hspace="0" vspace="0">
When using the DBMS sample adapter, you may see database-specific error messages written to the log file. The section identifies some of the more common database-specific error messages.
From time to time, when using Sybase or MSSQL databases, warnings are issued stating that the active database and/or language has been changed. These warnings come from the Sybase and MSSQL databases when the active database or language is changed on a connection. Since the catalog is changed at various points in the DBMS sample adapter, users of the sample adapter will inevitably see these messages. These warnings are harmless and can be ignored.
When an adapter instance in an MSSQL XA environment is automatically suspended and resumed, error messages similar to the following are thrown.
<Oct 15, 2003 4:40:30 PM PDT> <Error> <JDBC> <BEA-001112>
<Test "SELECT COUNT(*) FROM sysobjects" set up for pool "wlaiPool" failed with
exception: "javax.transaction.xa.XAException: [BEA][SQLServer JDBC Driver]
No more data available to read.".>
This is a JDBC-level error, generated as the JDBC container cleans up existing/dead connections to the restarted DBMS instance. This type of exception is normal in this case; the EIS is available, the adapter instance is resumed successfully, and the JDBC container recovers.
When using the DBMS sample adapter with a Microsoft SQL Server database, use the WebLogic Server Administration Console to enable the TestReservedConnection parameter for the connection pool used for application integration. If the parameter is not enabled, the auto resume or manual resume features do not work and a SQLException similar to the following is thrown:
java.sql.SQLException: [BEA][SQLServer JDBC Driver]No more data
available to read
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 BEA WebLogic Integration environment. This section explains how the design-time GUI for the DBMS sample adapter was developed:
Before development of the design-time GUI for the DBMS was begun, values for the following parameters needed to be determined:
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.
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
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.
Consider incorporating the following practices into your development process:
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.
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. 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
You can manage your application integration run-time environment using the WebLogic Integration Administration Console. For more information, see Application Integration in Managing WebLogic Integration Solutions at the following URL:
http://download.oracle.com/docs/cd/E13214_01/wli/docs81/manage/ai.html
The following sections describe administration issues specific to the DBMS sample adapter.
Please consider the following when modifying the EventSchema parameter of the event connection for DBMS sample adapter instances:
evnt.sql to ensure that this is the case. The location for evnt.sql is as follows:WLI_HOME\adapters\dbms\sql\database_type
where WLI_HOME is the WebLogic Integration installation directory and database_type is the directory for the database you are using.
Note: In WebLogic Integration 8.1 Service Pack 3 or later, you must run both evnt.sql and evnt_trigger.sql if your database type is Oracle.
Note: You may need to redeploy servers if there is a change in the database instance used by the JDBC connection pool for the application integration event.
The schema name/table owner associated with an event trigger retains the information provided at design time. When you edit the event connection from the WebLogic Integration Administration Console, you point to a new connection setting for the event tables; any event metadata is associated with the new connection after the application is redeployed from the WebLogic Integration Administration Console. The event trigger still points to the old schema name.
When changing event connections to a new database, you must ensure that the new database has a schema and a table with the same name as the previous settings. The new table is used for triggering events.
You can point the event trigger to the new schema/table name using environment variables. Note that the old trigger is not deleted and that the adapter instance must be redeployed. To delete the old trigger, redeploy the application from the WebLogic Server Administration Console. The environment variable for the schema name is capable of changing the schema name/table owner where the trigger polls.
It is good practice to limit events to one per table in the database. This avoids multiple event pollers attempting to access one table.
Please consider the following when setting up DBMS sample adapter instances used by multiple application views. Only one adapter instance should be used for all application views needing an event for a given table/trigger type. If you have two application views that each depend on CUSTOMER_TABLE inserts, make sure they both use the same adapter instance. This is because the event generator for the adapter instance deletes the insert trigger from CUSTOMER_TABLE when all its event subscriptions are undeployed. If AppView1 uses adapter_instance_1 and is undeployed, adapter_instance_1 deletes the insert trigger for CUSTOMER_TABLE. If AppView2, which also needs CUSTOMER_TABLE inserts, uses adapter_instance_2, it will be starved of events because adapter_instance_1 previously deleted the trigger. If AppView2 uses adapter_instance_1, adapter_instance_1 knows that AppView2 still needs the CUSTOMER_TABLE insert event and does not delete the trigger even if AppView1 is undeployed.
You can distribute event generators among nodes in a WebLogic Integration cluster. This improves load balancing and fault tolerance of event generation. For an example of multiple event generators using the same DBMS instance, see Example: DBMS Sample Adapter.
You must set event generator targets when in a clustered environment. A blank target ("") does not trigger events on any node in the cluster. (In a single node environment, no entry is needed; a blank event generator target value kicks off events for the one server.)
|
|
|