Writing safe relationship code

Recommendation: You should use the following defensive coding standards for attributes that require relationship management:

Checking for null source attribute

Before calling one of the Mapping API methods in Table 113, make sure that the source attribute is not null. If the attribute is null, log an error and do not call the method.

Table 113. Handling null source attributes

Mapping API method Error number to log Stop map execution?
maintainSimpleIdentityRelationship()
5000
Yes

foreignKeyXref()

foreignKeyLookup()
5003
The mapping specification should specify whether the map execution should stop.

To stop map execution, you can throw the MapFailureException exception.

Handling exceptions from the mapping API method

To ensure that any exceptions raised by the Mapping API methods in Table 114 are caught, put the call to a method of the Mapping API inside the try/ catch block and log the appropriate error message inside the catch section.

Table 114. Handling Exceptions from mapping API methods

Mapping API method Exception to Catch Error Number to Log

maintainSimpleIdentity
Relationship()

maintainComposite
Relationship()
RelationshipRuntimeException
5001

CxMissingIDException 5002
foreignKeyLookup()
RelationshipRuntimeException 5007 or 5008
foreignKeyXref()
RelationshipRuntimeException 5009

Example: The following code fragment includes a call to the maintainSimpleIdentityRelationship() method that catches both the RelationshipRuntimeException and CxMissingIDException exceptions, logs informational message to display the error text generated by the server, and stops the map execution by throwing MapFailureException:

try 
   {
   // API call
   IdentityRelationship.maintainSimpleIdentityRelationship(...);
   }
 
catch (RelationshipRuntimeException re) 
   {
   logError(5001);
   logInfo(re.toString());
   throw new MapFailureException("RelationshipRuntimeException");
   }
 
catch (CxMissingIDException ce) 
   {
   logError(5002);
   logInfo(ce.toString());
   throw new MapFailureException("RelationshipRuntimeException");
   }

Example: The following code fragment shows exception handling for the foreignKeyLookup() method that catches the RelationshipRuntimeException exception, logs informational message to display the error text generated by the server, and then checks the destination attribute to see whether it was successfully mapped; if not, the fragment displays an error with 5007 if the map has to stop execution or message 5008 if it can continue the map execution:

try 
   {
   // API call
   IdentityRelationship.foreignKeyLookup(...);
   }
 
catch (RelationshipRuntimeException re) 
   {
   logInfo(re.toString());
   }
 
if (ObjDest.isNull("DestAttr") 
   {
   logError(5007, "DestAttrName", "SrcAttrName", "RelationshipName", 
      "ParticipantName", strInitiator);
   throw new MapFailureException("foreignKeyLookup() failed");
   }
If the map execution is to be continued, use the following if statement:
if (ObjDest.isNull("DestAttr") 
   {
   logError(5008, "DestAttrName", "SrcAttrName", "RelationshipName", 
      "ParticipantName", strInitiator);
   }

Example: The following code fragment shows exception handling for the foreignKeyXref() method that catches RelationshipRuntimeException, logs an informational message to display the error text generated by the server, then checks the destination attribute to see whether it was successfully mapped; if not, the fragment displays an error with message 5009 and stops the map execution by throwing MapFailureException:

try 
   {
   // API call
   IdentityRelationship.foreignKeyXref(...);
   }
 
catch (RelationshipRuntimeException re) 
   {
   logInfo(re.toString());
   }
 
if (ObjDest.isNull("DestAttr") 
   {
   logError(5009, "DestAttrName", "SrcAttrName", "RelationshipName", 
      "ParticipantName", strInitiator);
   throw new MapFailureException("foreignKeyXref() failed");
   }

Copyright IBM Corp. 1997, 2004