Verb processing

This section outlines the steps the connector takes when creating, retrieving, updating, or deleting a business object that it receives from an integration broker. 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.

Note:
A top-level business object that is a wrapper supports the create, retrieve, update and delete verbs. The only difference in processing a wrapper object is that the wrapper object is not processed, only the objects that it contains are processed.

Business object comparison

At various points in the processing outlined below, the connector compares two business objects to see if they are the same. For example, during an update operation, the connector determines whether a particular business object exists in an array of business objects. To perform the check, the connector compares the business object to each business object within the array. For two business objects to be identical, the following two conditions must be satisfied:

Create operations

When creating a business object, the connector returns a status either of VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), or FAIL if the operation failed.

The connector performs the following steps when creating a hierarchical business object:

  1. Recursively inserts each single-cardinality child business object contained with ownership into the database. In other words, the connector creates the child and all child business objects that the child and its children contain.

    If the business object definition specifies that an attribute represents a child business object with single cardinality and that attribute is empty, the connector ignores the attribute. However, if the business object definition requires that attribute to represent a child and it does not, the connector returns an error and stops processing.

  2. Processes each single-cardinality child business object contained without ownership as follows:
    1. Recursively attempts to retrieve the child from the database using the key values passed in by the integration broker.
    2. If the retrieve is unsuccessful, indicating that the child does not currently exist in the database, the connector returns an error and stops processing. If the retrieve is successful, the connector recursively updates the child business object.

    Note:
    For this approach to work correctly when the child business object already exists in the application database, ensure that primary key attributes in child business objects are cross-referenced correctly on create operations. If the child business object does not already exist in the application database, set the primary key attributes to CxBlank.
  3. Inserts the top-level business object in the database as follows:
    1. Sets each of its foreign-key values to the primary-key values of the corresponding child business object represented with single cardinality. Because values in child business objects can be set by database sequences or counters or by the database itself during the creation of the child, this step ensures that the foreign-key values in the parent are correct before the connector inserts the parent in the database.
    2. Generates a new unique ID value for each attribute that is set automatically by the database. The name of the database sequence or counter is stored in the attribute's application-specific information. If an attribute has an associated database sequence or counter, the value generated by the connector overwrites any value passed in by the integration broker. For more information on specifying a database sequence or counter, see UID=AUTO in Application-specific information for simple attributes.
    3. Copies the value of an attribute to the value of another attribute as specified by the CA (CopyAttribute) parameter of the attribute's application-specific information. For more information on using the CA parameter, see CA=set_attr_name in Application-specific information for simple attributes.
    4. Inserts the top-level business object into the database.

    Note:
    A top-level business object that is a wrapper will not be inserted into the database.
  4. Processes each of its single-cardinality child business objects that stores the parent/child relationship in the child, as follows:
    1. Sets the foreign-key values in the child to reference the value in the corresponding primary-key attributes in the parent. Because the parent's primary-key values may have been generated during the creation of the parent, this ensures that the foreign-key values in each child are correct before the connector inserts the child into the database.
    2. Inserts the child into the database.
  5. Processes each of its multiple-cardinality child business objects, as follows:
    1. Sets the foreign-key values in each child to reference the value in the corresponding primary-key attributes in the parent. Because the parent's primary-key values may have been generated during the creation of the parent, this ensures that the foreign-key values in each child are correct before the connector inserts the child into the database.
    2. Inserts each of its multiple-cardinality child business objects into the database.

Retrieve operations

The connector performs the following steps when retrieving a hierarchical business object:

  1. Removes all child business objects from the top-level business object that it received from the integration broker.
  2. Retrieves the top-level business object from the database.

    Note:
    A business object can have attributes that do not correspond to any database column, such as placeholder attributes. During retrieval, the connector does not change such attributes in the top-level business object; they remain set to the values received from the integration broker. In child business objects, the connector sets such attributes to their default values during retrieval.
    Note:
    A top-level business object that is a wrapper must contain any attribute values from the objects at the level immediately below the wrapper object, which would be necessary to retrieve the objects, including keys and placeholder attributes. The wrapper object must have all keys and placeholder attributes populated. Simple attributes in the wrapper object that will be used as foreign keys in the objects one level below the wrapper should be marked as keys in the wrapper object.
  3. Recursively retrieves all multiple-cardinality child business objects.
    Note:
    The connector does not enforce uniqueness when populating an array of business objects. It is the database's responsibility to ensure uniqueness. If the database returns duplicate child business objects, the connector returns duplicate children.
  4. Recursively retrieves each of the single-cardinality children regardless of whether the child business object is contained with or without ownership.
    Note:
    All single cardinality child business objects are processed based on occurrence in the business object and before the parent business object is processed. Child object ownership and non-ownership do not determine the processing sequence, but do determine the type of processing.

RetrieveByContent operations

A RetrieveByContent verb is applicable only for the top-level business object, because the connector performs a retrieval based on attributes only in the top-level business object.

If a top-level business object uses the RetrieveByContent verb, all of the attributes (including non-key attributes) that are not null are used as retrieval criteria.

If more than one row is returned, the connector uses the first row as the result row and returns MULTIPLE_HITS.

Note:
A RetrieveByContent verb is not applicable for a top-level business object that is a wrapper.

Update operations

When updating a business object, the connector returns a status either of VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), or FAIL if the operation failed. When working with an Oracle database, the connector locks data while retrieving it to ensure data integrity.

The connector performs the following steps when updating a hierarchical business object:

  1. Uses the primary-key values of the source business object to retrieve the corresponding entity from the database. The retrieved business object is an accurate representation of the current state of the data in the database.
  2. Recursively updates all single-cardinality children of the top-level business object.

    If the business object definition requires that an attribute represent a child business object, the child must exist in both the source business object and the retrieved business object. If it does not, the update fails, and the connector returns an error.

    The connector handles single-cardinality children contained with ownership in one of the following ways:

    For single-cardinality children contained without ownership, the connector attempts to retrieve every child from the database that is present in the source business object. If it successfully retrieves the child, the connector populates the child business object but does not update it, as single cardinality children contained without ownership are never modified by the connector.

  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. This step is necessary because single-cardinality children may have been added to the database during previous steps, resulting in the generation of new unique IDs.
  4. Updates all simple attributes of the retrieved business object except those whose corresponding attribute in the source business object contain the value CxIgnore.

    Because the business object being updated must be unique, the connector verifies that only one row is processed as a result. It returns an error if more than one row is returned.

  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. (When InterChange Server Express is used as the integration broker, these values have typically been cross-referenced during data mapping.) However, this step is important to ensure that the foreign-key values of new children that store the relationship in the child are correct before the connector updates those children.
  6. Processes each multiple-cardinality child of the retrieved business object in one of the following ways:

Note:
The integration broker must ensure that business objects contained with multiple cardinality in the source business object are unique (that is, that an array does not contain two or more copies of the same business object). If the connector receives duplicates of a business object in a source array, it processes the business object twice, with possibly unpredictable results.

Delete operations

When deleting a business object, the connector returns a status of SUCCESS if the operation was successful or FAIL if the operation failed. If the business object does not exist, the connector throws a warning.

The connector supports logical and physical deletes, depending on the SCN (Status Column Name) value in the object's application-specific information. If the SCN value is defined, the connector performs a logical delete. If the SCN value is not defined, the connector performs a physical delete.

Physical deletes

The connector performs the following steps when physically deleting a hierarchical business object:

  1. Recursively deletes all single-cardinality child business objects contained with ownership and recursively deletes all multiple-cardinality child business objects.
  2. Deletes the top-level business object.

Note:
A top-level business object that is a wrapper does not have a corresponding database table, hence it will not be deleted from the database. Any simple attribute values for a wrapper will be ignored.

When an integration broker sends a hierarchical business object that uses the Update verb for the top-level business object and the Delete verb for child business objects, the connector assumes that the business object exactly matches the current database representation of that data. It is the integration broker's responsibility to ensure that this is the case. A problem occurs if the integration broker sends a business object that does not fully represent the business object to be deleted.

For example, if the source business object contains fewer child business objects than the object in the database, the connector does not delete the missing business objects from the database. Alternatively, if the source business object contains a child business object that does not exist in the database, a warning is displayed and the connector continues processing.

For example, Figure 5 illustrates a delete request that the connector processes successfully. However, the connector does not delete child D from the database, because it does not exist in the business object it received. This example deletion results in a dangling business object remaining in the database.

Figure 5. Business object deletion with hanging child


Alternatively, Figure 6 illustrates a delete request in which the source has more child objects than are present in the database. Because the source business object contains child C and because child C does not exist in the database, the connector displays a warning and continues processing.

Figure 6. Deletion of child business object nonexistent in application database


Logical deletes

When logically deleting a business object, the connector performs the following steps:

  1. Issues an UPDATE that sets the business object's status attribute to the value specified by the business object's application-specific information. The connector ensures that only one database row is updated as a result, and it returns an error if this is not the case.
  2. Recursively logically deletes all single-cardinality children contained with ownership and all multiple-cardinality children. The connector does not delete single-cardinality children contained without ownership. It also does not delete any child not represented in the source business object.

Copyright IBM Corp. 1997, 2003