Performing foreign key lookups

A foreign key is an attribute within one business object that contains the key value of another business object. This key value is considered "foreign" to the source business object because it identifies some other business object. To transform a foreign key in a source business object, you must access the relationship table associated with the business object that the foreign key references (the foreign relationship table). From this foreign relationship table, you can obtain the associated key value for the foreign key of the destination business object.

The Mapping API provides the methods in Table 88 to perform foreign key lookups.

Table 88. Function blocks for foreign key lookups
Function block Description
General/APIs/Identity Relationship/Foreign Key Lookup Performs a foreign key lookup, failing to find a relationship instance if the foreign key does not exist in the foreign relationship table.
General/APIs/Identity Relationship/Foreign Key Cross-Reference Performs a foreign key lookup, adding a new relationship instance in the foreign relationship table if the foreign key does not exist.

Using the Foreign Key Lookup function block

The Java code generated by the Foreign Key Lookup function block performs a lookup in a foreign relationship table for the foreign key of the source business object. This function block takes the following actions:

  1. Verify that the application-specific participant contains a single key, not a composite key.

    Determine the participant type of the application-specific participant, which is the application-specific business object. In this business object, verify that only one key attribute exists. If more than one key attribute exists, the Foreign Key Lookup function block does not know which application-specific key attribute to populate with the application-specific equivalent of the generic business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.

  2. Locate the relationship instance in the foreign relationship table that matches the value of the foreign key in the generic business object.
  3. Obtain the application-specific key value from the retrieved relationship instance.
  4. Copy the application-specific key value into the foreign key of the application-specific business object.

The Java code generated by the Foreign Key Lookup function block takes these actions on the foreign relationship table regardless of the verb in the source business object.

Using the Foreign Key Cross-Reference function block

As with the Foreign Key Lookup function block, the Foreign Key Cross-Reference function block performs a lookup in a foreign relationship table based on the foreign key of the source business object. However, the Foreign Key Cross-Reference function block provides the additional functionality that it can add an entry to the foreign relationship table if the lookup fails. The following sections discuss the behavior of the Foreign Key Cross-Reference function block with each of the calling contexts.

EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE calling contexts

When the calling context is EVENT_DELIVERY, ACCESS_REQUEST, or SERVICE_CALL_RESPONSE, the map is being called is an inbound map; that is, it transforms an application-specific business object to a generic business object. The inbound map receives an application-specific business object as input and returns a generic business object as output. Therefore, the task for the Foreign Key Cross-Reference function block is to obtain from the foreign relationship table the generic key for a given application-specific key value.

For the EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE calling contexts, the Foreign Key Cross-Reference function block takes the following actions:

  1. Verify that the generic participant contains a single key, not a composite key.

    Determine the participant type of the generic participant, which is the generic business object. In this business object, verify that only one key attribute exists. If more than one key attribute exists, the Foreign Key Cross-Reference function block does not know which generic key attribute to populate with the generic equivalent of the application-specific business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.

  2. Locate the relationship instance in the foreign relationship table that matches the value of the foreign key in the application-specific business object. Table 89 shows the actions that the Foreign Key Cross-Reference function block takes on the foreign relationship table based on the verb of the application-specific business object.
  3. Obtain the instance ID from the retrieved relationship instance.
  4. Copy the instance ID into the foreign key of the generic business object.

    Table 89. Actions for EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE
    Verb of application-specific business object Action performed by the Foreign Key Cross-Reference function block
    Create For the EVENT_DELIVERY and ACCESS_REQUEST calling contexts, insert a new relationship entry into the foreign relationship table for the application-specific business object's key value.

    For the SERVICE_CALL_RESPONSE calling context, insert into the relationship table the new relationship entry containing the application-specific business object's key value and its associated relationship instance ID. The method obtains the relationship instance ID from the original-request business object in the map execution context (cwExecCtx). For more information on the behavior of the SERVICE_CALL_RESPONSE, see "SERVICE_CALL_RESPONSE calling context".


    If an entry for this key value already exists, retrieve the existing one; do not add another one to the table.
    Update Retrieve the relationship entry from the foreign relationship table for the given application-specific business object's foreign key value.

    If an entry for this foreign key value does not exist, insert a new relationship instance into the foreign relationship table for the application-specific business object's foreign key value.
    Retrieve Retrieve the relationship entry from the foreign relationship table for the given application-specific business object's foreign key value

Figure 118 shows how the Foreign Key Cross-Reference function block accesses the foreign relationship table (for App Obj C) when a calling context is EVENT_DELIVERY, ACCESS_REQUEST, or SERVICE_CALL_RESPONSE and the verb for the application-specific business object (App Obj A) is either Create or Update.

Figure 118. Foreign key lookup for a create or update verb


Note:
The Foreign Key Cross-Reference function block only adds relationship instances to the foreign relationship table for inbound maps.

SERVICE_CALL_REQUEST calling context and Foreign Keys

When the calling context is SERVICE_CALL_REQUEST, the map is being called is an outbound map; that is, it transforms a generic business object to an application-specific business object. The outbound map receives a generic business object as input and returns an application-specific business object as output. For the SERVICE_CALL_REQUEST calling context, the Foreign Key Cross-Reference function block takes the following actions:

  1. Verify that the application-specific participant contains a single key, not a composite key.

    Determine the participant type of the application-specific participant, which is the application-specific business object. In this business object, verify that only one key attribute exists. If more than one key attribute exists, the Foreign Key Cross-Reference function block does not know which application-specific key attribute to populate with the application-specific equivalent of the generic business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.

  2. Perform the task outlined in Table 90, based on the verb of the application-specific business object.

    The Foreign Key Cross-Reference function block obtains from the foreign relationship table an application-specific business object's key value for a given a relationship instance ID only if the verb is Update, Delete, or Retrieve. The Foreign Key Cross-Reference function block does not obtain the application-specific key value for a Create verb.

Table 90 shows the action that the Foreign Key Cross-Reference function block takes on the foreign relationship table based on the verb of the generic business object.

Table 90. Actions for the SERVICE_CALL_REQUEST calling context and a Foreign Key
Verb of generic business object Action performed by the Foreign Key Cross-Reference function block
Create Take no action.

The method writes a new relationship instance to the foreign relationship table when the calling context is SERVICE_CALL_RESPONSE. For more information, see "EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE calling contexts".

Update Delete Retrieve
  1. Obtain the generic business object's key value (the relationship instance ID) from the original-request business object in the map execution context.
  2. Retrieve the relationship instance from the foreign relationship table for the given generic business object's key value. If a relationship instance for this key value does not exist, throw a RelationshipRuntimeException exception. If no participants are found when the verb is Retrieve, throw a CxMissingIDException exception.
  3. Obtain the application-specific key value from the retrieved relationship instance.
  4. Copy the application-specific key value into the application-specific business object.

As Table 90 shows, when the verb is Create, the Foreign Key Cross-Reference function block does not write a new relationship instance to the relationship table. It does not perform this write operation because it does not yet have the application-specific foreign key value that corresponds to the instance ID. When the connector processes the application-specific business object, it notifies the application of the need to insert a new row (or rows). If this insert is successful, the application notifies the connector, which creates the appropriate application-specific business object with a Create verb and the application's key value.

Note:
For the SERVICE_CALL_REQUEST calling context, the Foreign Key Cross-Reference function block manages the foreign relationship table in the same way that the Maintain Simple Identity Relationship function block manages a relationship table.

ACCESS_RESPONSE calling context and foreign keys

When the calling context is ACCESS_RESPONSE, the map is being called is an outbound map; that is, it transforms a generic business object to an application-specific business object. The outbound map receives a generic business object as input and returns an application-specific business object as output. Therefore, the task for the Foreign Key Cross-Reference function block is to obtain from the foreign relationship table the application-specific key for a given generic key value.

For the ACCESS_RESPONSE calling context, the Foreign Key Cross-Reference function block takes the following actions:

  1. Verify that the application-specific participant contains a single key, not a composite key.

    Determine the participant type of the application-specific participant, which is the application-specific business object. In this business object, verify that only one key attribute exists. If more than one key attribute exists, the Foreign Key Cross-Reference function block does not know which application-specific key attribute to populate with the application-specific equivalent of the generic business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.

  2. Locate the relationship instance in the foreign relationship table that matches the value of the foreign key in the generic business object.
  3. Obtain the application-specific key value from the retrieved relationship instance.
  4. Copy the application-specific key value into the foreign key of the application-specific business object.

The Foreign Key Cross-Reference function block takes these actions on the foreign relationship table regardless of the verb in the generic business object.

Tips for using the Foreign Key Cross-Reference and Foreign Key Lookup function blocks

Keep the following tips in mind when using the Foreign Key Cross-Reference and Foreign Key Lookup function blocks:

Copyright IBM Corp. 1997, 2003