How the connector works

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 and metadata

The connector is metadata-driven. Metadata, in the IBM WebSphere Business Integration Adapter environment, is application-specific data that is stored in 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.

Business object processing

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.

Processing business object requests

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.

Note:
The term hierarchical business object refers to a complete business object, including all the child business objects that it contains at any level. The term individual business object refers to a single business object, independent of any child business objects it might contain or that contain it. The term top-level business object refers to the individual business object at the top of the hierarchy that does not itself have a parent business object.

Business object retrieval

When an integration broker asks the connector to retrieve a hierarchical business object from the database, the connector attempts to return a business object that exactly matches the current database representation of that business object. 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 to recursively descend through the corresponding data in the database.

Business object RetrievalByContent

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.

Business object creation

When an integration broker asks the connector to create a hierarchical business object in the database, the connector performs the following steps:

  1. Recursively creates each single-cardinality child business object contained with ownership into the database.
  2. Processes each single-cardinality child business object contained without ownership.
  3. Creates the top-level business object in the database.
  4. Creates each single-cardinality child business object that stores the parent/child relationship in the child.
  5. Creates each multiple-cardinality child business object.

Business object modification

When an integration broker asks the connector to update a hierarchical business object in the database, the connector performs the following steps:

  1. Uses the primary key values of the source business object to retrieve the corresponding entity from the database.
  2. Recursively updates all single-cardinality children of the top-level business object.
  3. For single-cardinality child business objects that store the relationship in the parent, sets each foreign key value in the parent to the value of the primary key in the corresponding single-cardinality child business object.
  4. Updates all simple attributes of the retrieved business object except those whose corresponding attribute in the source business object contain the value CxIgnore.
  5. Sets all foreign key values in each child that stores the parent/child relationship in the child (both multiple-cardinality and single-cardinality) to the primary key value of its corresponding parent business object.
  6. Processes all arrays of the retrieved business object.

Business object deletion

When an integration broker asks the connector to delete a hierarchical business object from the database, the connector performs the following steps:

  1. Deletes the single-cardinality children.
  2. Deletes the multiple-cardinality children.
  3. Deletes the top-level business object.

Processing application events

The connector handles the Create, Update, and Delete events generated by the application in the manner described below.

Create notification

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.

Update notification

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.

Delete notification

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.

Retrieving business objects for event processing

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.

Note:
If the object key does not use name_value pair, the keys in the object key field should follow the same order as the keys in the business object.

Event notification

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.

Note:
You must add the triggers to the database as part of the installation procedure.

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.

Table 1. Archiving behavior

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
false
Successfully processed Not archived and deleted from event table

Unsuccessfully processed Remains in event table with status of Error

No subscription for business object Remains in event table with status of Unsubscribed

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.

Handling lost database connections

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. As this connector supports different databases, there is no single error code definition for a lost connection to a database.

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:

Processing locale-dependent data

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 a different code set, it performs character conversion to preserve the meaning of the data.

The Java(TM) 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 these properties, see Appendix A, Standard configuration properties for connectors.

Note:
For enabling different character code sets, please see the documentation from Manugistics.

Copyright IBM Corp. 1997, 2004