This section describes how metadata enhances the connector's flexibility, and presents a high-level description of business object processing and event notification.
The connector is metadata-driven. Metadata, in the WebSphere Business Integration Adapter environment, is application-specific data that is stored in WebSphere Business Integration Adapter business objects and that assists the connector in its interaction with the application. A metadata-driven connector handles each business object that it supports based on metadata encoded in the business object definition rather than on instructions hard coded in the connector.
Business object metadata includes the structure of a business object, the settings of its attribute properties, and the content of its application-specific information. Because the connector is metadata driven, it can handle new or modified business objects without requiring modifications to the connector code.
The connector executes SQL statements or stored procedures to retrieve or change data in the database/application. To build dynamic SQL statements or stored procedures, the connector uses application-specific metadata. These SQL statements and stored procedures perform the required retrieval from or changes to the database/application for the business object and for the verb that the connector is processing. For information using application-specific information, see Understanding business objects for the connector.
This section provides an overview of how the connector processes business object requests and application events. For more detailed information, see Business object verb processing.
When the connector receives a request to perform an application operation, the connector processes hierarchical business objects recursively; that is, it performs the same steps for each child business object until it has processed all individual business objects. The order in which the connector processes child business objects and the top-level business object depends on whether the child business objects are contained with or without ownership and whether they are contained with single cardinality or multiple cardinality.
The connector supports the following four ways to process request business objects:
For more information, see Understanding business objects for the connector. For examples of how to use the interface tables with stored procedures to process business objects, see Appendix C. About sample business objects and stored procedures.
When an integration broker asks the connector to retrieve a hierarchical business object from the Oracle application, the connector attempts to return a business object that exactly matches the current representation of that business object in the application database. In other words, all simple attributes of each individual business object returned to the integration broker match the value of the corresponding field in the database. Also, the number of individual business objects in each array contained by the returned business object match the number of children in the database for that array.
To perform such a retrieval, the connector uses the primary key values in the top-level business object received from the business process to recursively descend through the corresponding data in the database.
When an integration broker asks the connector to retrieve a hierarchical business object based on values in non-key attributes in the top-level business object, the connector uses the value of all non-null attributes as the criteria for retrieving the data.
When an integration broker asks the connector to create a hierarchical business object in the Oracle application, the connector performs the following steps:
When an integration broker asks the connector to update a hierarchical business object in the database, the connector performs the following steps:
When an integration broker asks the connector to delete a hierarchical business object from the database, the connector performs the following steps:
The connector handles the Create, Update, and Delete events generated by the application in the manner described below.
When the connector encounters a Create event in the event table, it creates a business object of the type specified by the event, sets the key values for the business object (using the keys specified in the event table), and retrieves the business object from the database. After it retrieves the business object, the connector sends it with the Create verb to the integration broker.
When the connector encounters an Update event in the event table, it creates a business object of the type specified by the event, sets the key values for the business object (using the keys specified in the event table), and retrieves the business object from the database. After it retrieves the business object, the connector sends it with the Update verb to the integration broker.
When the connector encounters a Delete event in the event table, it creates a business object of the type specified by the event, sets the key values for the business object (using the keys specified in the event table), and sends it with the Delete verb to the integration broker. All values other than the key values are set to CxIgnore. If any of the non-key fields are significant at your site, modify the value of the fields as needed.
The connector handles logical and physical Delete operations that are triggered by its application. In the case of physical deletes, the SmartFiltering mechanism removes all of the business object's unprocessed events (such as Create or Update) before inserting the Delete event into the event table. In the case of logical deletes, the connector inserts a Delete event in the event table without removing other events for the business object.
The event ID is a unique ID that is used to avoid logging duplicate events from the application broker. For example, an event is in progress and is sent to the integration broker, and then the adapter fails. When the adapter is restarted, it reprocesses and resends the event. The integration broker then compares event IDs and discards any duplicate events, because each event ID is unique.
A Retrieve can be done in two ways on a business object for event processing. The first is a Retrieve based on key attributes in a business object. The second is a Retrieve based on both key and non-key attributes. In this case, the business object needs to support the RetrieveByContent verb and must use name_value pair for the object keys.
The connector's event detection mechanism uses an event table, an archive table, stored procedures, and database triggers. Because there are potential failure points associated with the processing of events, the event management process does not delete an event from the event table until it has been inserted into the archive table.
The database triggers populate an event table whenever an event of interest occurs in the database. The connector polls this table at a regular, configurable interval, retrieves the events, and processes the events first by priority and then sequentially. When the connector has processed an event, the event's status is updated.
The setting of its ArchiveProcessed property determines whether the connector archives an event into the archive table after updating its status. For more information on the ArchiveProcessed property, see Configuring the connector.
Table 1 illustrates the archiving behavior depending on the setting of the ArchiveProcessed property.
Archive processed setting | Reason deleted from event table | Connector behavior |
---|---|---|
true or no value | Successfully processed | Archived with status of Sent to InterChange |
Unsuccessfully processed | Archived with status of Error | |
No subscription for business object | Archived with status of Unsubscribed (for subscription information specific to your integration broker, see the broker's implementation guide) | |
false | Successfully processed | Not archived and deleted from event table |
Unsuccessfully processed | Remains in the event table with a status of Error | |
No subscription for business object | Remains in event table with status of Unsubscribed (for subscription information specific to your integration broker, see the broker's implementation guide) |
SmartFiltering is a mechanism within the database triggers that minimizes the amount of processing the integration broker and connector must perform. For example, if an application has updated the Contract business object 15 times since the connector last polled for events, the SmartFiltering stores those changes as a single Update event.
There are numerous reasons for losing a database connection. If this occurs, the connector terminates. The JDBC specification does not provide a mechanism for detecting lost connections; however, the PingQuery property is provided to handle this detection. If a failure occurs during a service call request, the connector executes this PingQuery to confirm that the failure was not due to a lost connection to a database. If the PingQuery fails and the AutoCommit property is set to false, the connector will attempt to create a new connection to the database. If it succeeds in creating a new connection to the database it will continue processing, otherwise the connector returns an APPRESPONSETIMEOUT, which results in the termination of the connector.
The PingQuery is executed if a failure occurs when accessing a database for any type of transaction. For example:
While creating or updating a record pertaining to a business object
This adapter is compatible with Common Event Infrastructure from IBM, a standard for event management that permits interoperability with other IBM WebSphere event-producing applications. If Common Event Infrastructure support is enabled, events produced by the adapter can be received (or used) by another Common Event Infrastructure-compatible application.
For more information, see the Common Event Infrastructure appendix in this guide.
This adapter is compatible with the Application Response Measurement (ARM) application programming interface (API), an API that enables applications to be managed for availability, service level agreements, and capacity planning. An ARM-instrumented application can participate in IBM Tivoli(R) Monitoring for Transaction Performance, enabling collection and review of data concerning transaction metrics.
For more information, see the Application Response Measurement appendix in this guide.
The connector has been internationalized so that it can support double-byte character sets, and deliver message text in the specified language. When the connector transfers data from a location that uses one character code set to a location that uses another code set, it performs character conversion to preserve the meaning of the data.
This adapter supports the processing of bidirectional (bi-di) script data for languages such as Arabic, Hebrew, Urdu, Farsi, and Yiddish. To use the bidirectional capacity, you must configure the bidirectional standard properties. For more information, see Appendix A. Standard configuration properties for connectors.
If your relational database management system (RDBMS) uses a bidirectional format that differs from the Windows standard format, all properties with bidirectional support are transformed from the Windows standard format to the bidirectional format of the target RDBMS.
The JavaTM runtime environment within the Java Virtual Machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single-byte and multibyte). Most components in the WebSphere Business Integration system are written in Java. Therefore, when data is transferred between most WebSphere Business Integration system components, there is no need for character conversion.
To log error and informational messages in the appropriate language and for the appropriate country or territory, configure the Locale standard configuration property for your environment. For more information on that property, see Appendix A. Standard configuration properties for connectors.