Creating a business object handler involves the following steps:
In the Java connector library, the base class for a business object handler is named CWConnectorBOHandler. The CWConnectorBOHandler class provides methods for defining and accessing a business object handler. To implement your own business object handler, you extend this business-object-handler base class to create your own business-object-handler class.
To derive a business-object-handler class for a Java connector, follow these steps:
connectorNameBOHandler.java
where connectorName uniquely identifies the application or technology with which the connector communicates. For example, to create a business object handler for a Baan application, you create a business-object-handler class called BaanBOHandler. If your connector design implements multiple business object handlers, include the name of the handled business objects in the name of the business-object-handler class.
com.crossworlds.connectors.connectorName
where connectorName is the same as defined in step 1 above. For example, the package name for the Baan connector would be defined in the business-object-handler-class file as follows:
package com.crossworlds.connectors.Baan;
com.crossworlds.cwconnectorapi.*; com.crossworlds.cwconnectorapi.exceptions.*;
If you create several files to hold the business object handler's code, you must import these classes into every file.
You might need to implement more than one business object handler for your connector, depending on the application and its API. For a discussion of some issues to consider when implementing business object handlers, see Designing business object handlers..
The doVerbFor() method provides the functionality for the business object handler. When the connector framework receives a request business object, it calls the doVerbFor() method for the appropriate business object handler to perform the action of this business object's verb. For a Java connector, the CWConnectorBOHandler class defines the doVerbFor() method in which you define the verb processing.
However, the actual doVerbFor() method that the connector framework invokes is the low-level version of this method, which the CWConnectorBOHandler class inherits from the BOHandlerBase class of the low-level Java connector library. This low-level version of doVerbFor() calls the user-implemented doVerbFor() method. Therefore, as part of your business-object-handler class (an extension of CWConnectorBOHandler), you must provide an implementation of the doVerbFor() method.
The role of the business object handler is to perform the following tasks:
Table 44 summarizes the steps in the basic logic for the verb processing that the doVerbFor() method typically performs. Each of the sections listed in the For More Information column provides more detailed information on the associated step in the basic logic.
Business-object-handler step | For more information | |
---|---|---|
1. | Obtain the active verb from the request business object. | Obtaining the active verb |
2. | Verify that the connector still has a valid connection to the application. | Verifying the connection before processing the verb |
3. | Branch on the value of the valid active verb. | Branching on the active verb |
4. | For a given active verb, perform the appropriate request processing: | |
|
Performing the verb operation | |
|
Processing business objects | |
5. | Send the appropriate status to the connector framework. | Sending the verb-processing response |
In addition to the processing steps in Table 44,, this section also provides additional processing information in Additional processing issues.
If your business integration system uses InterChange Server and collaborations are coded to be multi-threaded, the connector framework might call into doVerbFor() with multiple threads representing request processing.
To determine which actions to take, the doVerbFor() method must first retrieve the verb from the business object that it receives as an argument. This incoming business object is called the request business object. The verb that this business object contains is the active verb, which must be one of the verbs that the business object definition supports. Table 45 lists the method that the Java connector library provides to retrieve the active verb from the request business object.
Java connector library class | Method |
---|---|
CWConnectorBusObj | getVerb() |
Obtaining the active verb from the request business object generally involves the following steps:
Before the connector calls getVerb(), it should verify that the incoming request business object is not null. The incoming business object is passed into the doVerbFor() method as a CWConnectorBusObj object.
Once the request business object is valid, you can use the getVerb() method in the CWConnectorBusObj class to obtain the active verb from this business object.
When the connector has obtained the active verb, it should verify that this verb is neither null nor empty.
If either the request business object or the active verb is invalid, the connector should not continue with verb processing. Instead, it should take the steps outlined in Table 46..
Error-handling step | Method or code to use | |
---|---|---|
1. | Log an error message to the log destination to indicate the cause of the verb-processing error. | CWConnectorUtil.generateAndLogMsg() |
2. | Instantiate an exception-detail object to hold the exception information. | CWConnectorExceptionObject excptnDtailObj = new CWConnectorExceptionObject(); |
3. | Set the status information within an exception-detail object: | |
excptnDtailObj.setMsg() | ||
excptnDtailObj.setStatus() | ||
4. |
Throw a VerbProcessingFailureException exception, which the doVerbFor() uses to tell the connector framework that a verb-processing error has occurred. This exception object contains the exception-detail object you initialized in Step 2. When the low-level doVerbFor() method catches this exception object, it copies the message and status from the exception-detail object into the return-status descriptor that it returns to the connector framework, which in turn returns it to the integration broker. |
throw new VerbProcessingFailureException( excptnDtailObj); |
Figure 55 contains a fragment of the doVerbFor() method that obtains the active verb with the getVerb() method. This code uses the try and catch statements to ensure that the request business object and its active verb are not null. If either of these conditions exists, the code fragment throws the VerbProcessingFailedException exception, which the connector framework catches.
public int doVerbFor(CWConnectorBusObj theBusObj) throws VerbProcessingFailedException, ConnectionFailureException { CWConnectorExceptionObject cwExcpObj = new CWConnectorExceptionObject(); //make sure that the incoming business object is not null if (theBusObj == null) { CWConnectorUtil.logMsg(3456, CWConnectorLogAndTrace.XRD_ERROR); cwExcpObj.setMsg( "doVerbFor(): Invalid business object passed in"); cwExcpObj.setStatus(CWConnectorConstant.FAIL); throw new VerbProcessingFailedException(cwExcpObj); } // obtain the active verb String busObjVerb = theBusObj.getVerb(); // make sure the active verb is neither null nor empty if (busObjVerb == null || busObjVerb.equals("")){ cwExcpObj.setMsgNumber(6548); cwExcpObj.setMsgType(CWConnectorLogAndTrace.XRD_ERROR); cwExcpObj.setMsg("doVerbFor: Invalid active verb"); cwExcpObj.setStatus(CWConnectorConstant.FAIL); throw new VerbProcessingFailedException(cwExcpObj); } try { // perform verb processing here ... } catch (SampleException se) { throw new VerbProcessingFailedException(cwExcpObj); }
When the agentInit() method in the connector class initializes the application-specific component, one of its most common tasks is to establish a connection to the application. The verb processing that doVerbFor() performs requires access to the application. Therefore, before the doVerbFor() method begins processing the verb, it should verify that the connector is still connected to the application. The way to perform this verification is application-specific. Consult your application documentation for more information.
A good design practice is to code the connector application-specific component so that it shuts down whenever the connection to the application is lost. If the connection has been lost, the connector should not continue with verb processing. Instead, it should take the following steps to notify the connector framework of the lost connection:
The connector logs a fatal error message so that email notification is triggered if the LogAtInterchangeEnd connector configuration property is set to True.
CWConnectorExceptionObject.setMsg() | |
CWConnectorExceptionObject.setStatus() |
This exception-detail object is part of the exception object that doVerbFor() throws. For information on these methods, see Exceptions.
When the low-level doVerbFor() method catches this exception object, it copies the message and status from the exception-detail object into the return-status descriptor that it returns to the connector framework. If you have not set the status in the ConnectionFailureException exception-detail object, the connector framework sets the status to APPRESPONSETIMEOUT. The connector framework includes this return-status descriptor as part of its response to the integration broker. The integration broker can check the return-status descriptor to determine that the application is not responding.
After it has sent the return-status descriptor, the connector framework stops the process in which the connector runs. A system administrator must fix the problem with the application and restart the connector to continue processing events and business object requests.
The main task of verb processing is to ensure that the application performs the operation associated with the active verb. The action to take on the active verb depends on whether the doVerbFor() method has been designed as a basic method or a metadata-driven method:
For verb-processing that is not metadata-driven, you branch on the value of the active verb to perform the verb-specific processing. Your doVerbFor() method must handle all verbs that the business object supports.
Table 47 shows the verb constants that the Java connector library provides for comparing with the active verb.
Verb Constant | Active Verb |
---|---|
VERB_CREATE | Create |
VERB_RETRIEVE | Retrieve |
VERB_UPDATE | Update |
VERB_DELETE | Delete |
VERB_EXISTS | Exists |
VERB_RETRIEVEBYCONTENT | RetrieveByContent |
All verb constants in Table 47 are defined in the CWConnectorConstant class. If your connector handles additional verbs, IBM recommends that you define your own String constants as part of your extended CWConnectorBOHandler class.
Figure 56 shows a code fragment of doVerbFor() that branches off the active verb's value for the Create and Update verbs. For each verb your business object supports, you must provide a branch in this code.
// handle the Create verb if(busObjVerb.equals(CWConnectorConstant.VERB_CREATE)){ CWConnectorUtil.initAndValidateAttributes(theBusObj); status=doCreate(theBusObj); // where doCreate() inserts new row into Sample Apps database // using data from theBusObj } // handle the Update verb else if (objVerb.equals(CWConnectorConstant.VERB_UPDATE)){ status=doUpdate(theBusObj); // where doUpdate() locates existing row and updates it with // information from theObj // notify connector framework of invalid verb } else { CWConnectorUtil.logMsg(3456, CWConnectorLogAndTrace.XRD_ERROR); cwExcpObj.setMsg("doVerbFor(): Invalid verb passed in"); cwExcpObj.setStatus(CWConnectorConstant.FAIL); throw new VerbProcessing FailedException(cwExcpObj); }
The code fragment in Figure 56 is modularized; that is, it puts the actual processing of each supported verb into a separate verb method: doCreate() and doUpdate(). Each verb method should meet the following minimal guidelines:
This modular structure greatly simplifies the readability and maintainability of the doVerbFor() method.
For metadata-driven verb processing, the application-specific information for the verb contains metadata, which provides processing instructions for the request business object when that particular verb is active. Table 48 lists the method that the Java connector library provides to obtain application-specific information for the verb of a business object.
Java connector library class | Method |
---|---|
CWConnectorBusObj | getVerbAppText() |
The following call to getVerbAppText() extracts the verb's application-specific information:
String verbAppInfo = theBusObj.getVerbAppText(busObjVerb);
The verb application-specific information can contain the name of the method to call to process the request business object for that particular verb. In this case, the doVerbFor() method does not need to branch off the value of the active verb because the processing information resides in the verb's application-specific information.
Table 49 lists the standard verbs that a doVerbFor() method can implement, as well as an overview of how each verb operation processes the request business object. For more information on how to process business objects, see Processing business objects.
Verb | Use of request business object | For more information |
---|---|---|
Create |
|
Handling the Create verb |
Retrieve |
|
Handling the Retrieve verb |
Update |
|
Handling the Update verb |
Delete |
|
Handling the Delete verb |
Most verb operations involve obtaining information from the request business object. This section provides information about the steps your doVerbFor() method needs to take to process the request business object.
Table 50 summarizes the steps in the basic program logic for deconstructing a request business object that contains metadata.
Step | For more information | |
---|---|---|
1. | Obtain the business object definition for the request business object. | Accessing the business object definition |
2. | Obtain the application-specific information in the business object definition to obtain the application structure to access. | Extracting business object application-specific information |
3. | Obtain the attribute information. | Accessing the attributes |
4. | For each attribute, get the attribute application-specific information in the business object definition to obtain the application substructure to access. | Extracting attribute application-specific information |
5. | Make sure that processing occurs only for those attributes that are appropriate. | Determining whether to process an attribute |
6. | Obtain the value of each attribute whose value needs to be sent to the application entity. | Extracting attribute values from a business object |
7. | Notify the application to perform the appropriate verb operation. | Initiating the application operation |
8. | Save any attribute values in the request business object that are required for the verb-processing response. | Saving attribute values in a business object |
For a Java connector, the doVerbFor() method receives the request business object as an instance of the CWConnectorBusObj class. To begin verb processing, the doVerbFor() method often needs information from the business object definition. The CWConnectorBusObj class provides access to the business object, its business object definition, and its attributes. Therefore, a Java doVerbFor() method does not need to instantiate a separate object for the business object definition; it can obtain information in the business object definition directly from the CWConnectorBusObj object passed into doVerbFor().
The business object definition includes the information shown in Table 51.. For a complete list of CWConnectorBusObj methods, see CWConnectorBusObj class.
Business object definition information | CWConnectorBusObj method |
---|---|
The name of the business object definition | getName() |
A verb list--contains the verbs that the business object supports | isVerbSupported(), getSupportedVerbs() |
A list of attributes--for each attribute, the business object definition defines: | getAttrCount() |
getAttrName() | |
getTypeName(), getTypeNum() | |
getAttrIndex() | |
|
For a complete list, see Table 53.. |
Application-specific information: | |
getAppText(), getBusObjASIHashtable() | |
getAppText(), getAttrASIHashtable() | |
getVerbAppText() |
A business object handler typically uses the business object definition to get information on the business object's attributes or to get the application-specific information from the business object definition, attribute, or verb.
Business objects for metadata-driven connectors are usually designed to have application-specific information that provides information about the application structure. For such connectors, the first step in a typical verb operation is to retrieve the application-specific information from the business object definition associated with the request business object. Table 52 lists the methods that the Java connector library provides to retrieve application-specific information from the business object definition.
Java connector library class | Method |
---|---|
CWConnectorBusObj | getAppText() (with no arguments) |
getBusObjASIHashtable() |
As Table 52 shows, the connector can use either of the following methods to obtain the application-specific information for the business object definition:
For a table-based application, the business objects are often designed to have application-specific information provide the verb operations with information about the application structure (For more information, see Table 27). The application-specific information in a business object definition can contain the name of the database table associated with the business object.
For a Java connector, the CWConnectorBusObj class provides access to the business object, its business object definition, and its attributes. When the doVerbFor() method needs information about attributes in the business object, it can obtain this information directly from the request business object. Therefore, a Java doVerbFor() method does not need to instantiate a separate object for an attribute.
The connector can use attribute methods in the CWConnectorBusObj class (see Table 53) to obtain information about an attribute, such as its cardinality or maximum length. Methods that access attribute properties provide the ability to access an attribute in of two ways:
Table 53 lists the methods that the Java connector library provides to retrieve information about an attribute. For a complete list of methods that access attribute information, see CWConnectorBusObj class.
Attribute property | CWConnectorBusObj method |
---|---|
Name | getAttrName(), hasName() |
Type | getTypeNum(), getTypeName(), hasType(), isObjectType(), isType() |
Key | isKeyAttr() |
Foreign key | isForeignKeyAttr() |
Max Length | getMaxLength() |
Required | isRequiredAttr() |
Cardinality | getCardinality(), hasCardinality(), isMultipleCard() |
Default Value | getDefault(), getDefaultboolean(), getDefaultdouble(), getDefaultfloat(), getDefaultint(), getDefaultlong(), getDefaultString() |
Attribute application-specific information | getAppText() |
If business objects for metadata-driven connectors are designed to have application-specific information that provides information about the application structure, the next step after extracting the application-specific information from the business object definition is to extract the application-specific information from each attribute in the request business object. Table 54 lists the methods that the Java connector library provides to retrieve application-specific information from each attribute.
Java connector library class | Method |
---|---|
CWConnectorBusObj | getAttrCount() |
getAppText() (with the position or name of the attribute as an argument) | |
getAttrASIHashtable() |
As Table 54 shows, the connector can use either of the following methods to obtain the application-specific information for an attribute:
If business objects have been designed to have application-specific information provide information for a table-based application, the application-specific information for the attribute can contain the name of the application table's column associated with this attribute (For more information, see Table 27). After extracting the application-specific information from the business object definition, the next step is to determine what columns in the application table are associated with the attributes in the request business object.
A verb operation can call getAppText(), passing it the position or name of the attribute, to obtain the name of the column within the database table to access. To obtain the application-specific information for each attribute, the verb operation must loop through all attributes in the business object definition. Therefore, it must determine the total number of attributes in the business object definition. The most common syntax for looping through the attributes is a for statement that uses the following limits on the loop index:
If the verb operation processes the first attribute, which contains the key, the loop index variable starts at 0. However, if the verb is Create and your application generates keys, your Create verb operation should not process attributes containing keys. In this case, the loop index variable starts at a value other than 0.
The getAttrCount() method returns the total number of attributes in the business object. However, this total includes the ObjectEventId attribute. Because the ObjectEventId attribute is used by the IBM WebSphere business integration system and is not present in application tables, a verb operation does not need to process this attribute. Therefore, when looping through business object attributes, you loop from zero to one less than the total number of attributes:
getAttrCount() - 1
This increment of the index obtains the next attribute.
Within the for loop, the Java connector can use the getAppText() method to obtain each attribute's application-specific information:
for (i = 0; i < theBusObj.getAttrCount() - 1; i++) { colName = theBusObj.getAppText(i); // process the attribute associated with the column in // 'colName' }
Up to this point, the verb processing has been using the application-specific information to obtain the application location for each attribute of the request business object. With this location information, the verb operation can begin processing the attribute.
As the verb operation loops through the business object attributes, you might need to confirm that the operation processes only certain attributes. Table 55 lists some of the methods that the Java connector library provides to determine whether an attribute should be processed.
Attribute test | CWConnectorBusObj method |
---|---|
An attribute is a simple attribute and not an attribute that represents a contained business object. | isObjectType() |
The value of the attribute is not the special value of Blank (a zero-length string) or Ignore (a null pointer). | isIgnore(), isBlank() |
The attribute is not a place-holder attribute. Place-holder attributes are used in business object definitions to separate attributes that contain child business objects. | getAppText() |
Using the methods in Table 55,, a verb operation can determine that an attribute is one that the operation wants to process:
The isObjectType() method checks that the attribute value does not represent a contained business object. For more information on how to handle an attribute that does contain a business object, see Accessing child business objects.
You can use the getAppText() method to determine if the attribute in the business object definition has application-specific information. Because neither of these special types of attributes represent columns in an application entity, there is no need for the business object definition to include application-specific information for them.
The verb operation can compare the attribute's value to the Ignore and Blank values with the isIgnore() and isBlank() methods, respectively. For more information on the Ignore and Blank values, see Handling the Blank and Ignore values.
Once the verb operation has confirmed that the attribute is ready for processing, it usually needs to extract the attribute value:
Table 56 lists the methods that the Java connector library provides to obtain attribute values from a business object.
Java connector library class | Method |
---|---|
CWConnectorBusObj | getTypeName(),, getTypeNum(),, getbooleanValue(),, getBusObjValue(),, getdoubleValue(),, getfloatValue(),, getintValue(),, getlongValue(),, getLongTextValue(),, getStringValue() |
As Table 56 shows, the CWConnectorBusObj class provides type-specific methods for obtaining attribute values. These methods remove the need to cast the attribute value to match its type. You can choose which type-specific method to use by checking the attribute's data type with the getTypeName() or getTypeNum() method.
Once the verb operation has obtained the information it needs from the request business object, it is ready to send the application-specific command so that the application performs the appropriate operation. The command must be appropriate for the verb of the request business object. For a table-based application, this command might be an SQL statement or a JDBC call. Consult your application documentation for more information.
Once the application operation has completed successfully, the verb operation might need to save new attribute values retrieved from the application into the request business object:
Table 57 lists the methods that the Java connector library provides to save attribute values in a business object.
Java connector library class | Method |
---|---|
CWConnectorBusObj | setAttrValues(),, setbooleanValue(),, setBusObjValue(),, setdoubleValue(),, setfloatValue(),, setintValue(),, setLongTextValue(),, setStringValue() |
As Table 57 shows, the CWConnectorBusObj class provides the following ways to save attribute values:
The Java connector must send a verb-processing response to the connector framework, which in turn sends a response to the integration broker. This verb-processing response includes the following information:
The following sections provide additional information about how a Java connector provides each of the pieces of response information. For general information about the connector response, see Indicating the connector response..
The doVerbFor() method provides an integer outcome status as its return code. As Table 58 shows, the Java connector library provides constants for the outcome-status values that doVerbFor() is mostly likely to return.
The outcome status that doVerbFor() returns depends on the particular active verb it is processing. Table 59 lists the tables in this manual that provide possible return values for the different verbs.
Verb | For more information |
---|---|
Create | |
Retrieve | |
RetrieveByContent | |
Update | |
Delete | |
Exists |
Using the outcome status that doVerbFor() returns, the connector framework determines its next action:
The return-status descriptor is a structure that holds additional information about the state of the verb processing. When the connector framework invokes a business object handler, it actually calls the low-level version of the doVerbFor() method, inherited from the BOHandlerBase class of the low-level Java connector library. To this low-level doVerbFor() method, the connector framework passes in an empty return-status descriptor as an argument. The low-level doVerbFor() then calls the user-implemented doVerbFor() method, which is the version for which the connector developer provides an implementation as part of the CWConnectorBOHandler business-object-handler class. The user-implemented doVerbFor() performs the actual verb processing.
When this user-implemented doVerbFor() method exits, the low-level doVerbFor() updates its return-status descriptor with status information about the verb processing, as follows:
When the low-level doVerbFor() exits, this updated return-status descriptor is accessible by the connector framework. The connector framework then includes the return-status descriptor in the response it sends to the integration broker.
If your business integration system uses InterChange Server, the connector framework returns the response to the connector controller, which routes it to the collaboration. This response includes the return-status descriptor populated by the low-level doVerbFor() method. The collaboration can access the information in this return-status descriptor to obtain the status of its service call request.
The connector framework passes in the request business object as an argument to doVerbFor(). The doVerbFor() method can update this business object with attribute values. This updated business object is then accessible by the connector framework when doVerbFor() exits.
The connector framework uses the outcome status to determine whether to return a business object as part of its response to the integration broker, as follows:
If your doVerbFor() method returns one of these outcome-status values, make sure it updates the request business object with appropriate response information.
This section provides information on the following issues related to processing a business object:
In addition to a regular attribute value, simple attributes in business objects can have either of the special values shown in Table 60..
Special attribute value | Represents |
---|---|
Blank | An "empty" zero-length string value |
Ignore | An attribute value that the connector should ignore |
The connector can call Java connector library methods to determine whether a business object attribute is set to a special value:
When an attribute contains the Blank value, the doVerbFor() method should process the attributes as shown in Table 63..
When attributes are set to the Ignore value, the connector should process the attributes as shown in Table 64..
When a connector creates a new business object, all attribute values are set to Ignore internally. A connector must set appropriate values for attributes, since all unset attribute values remain defined as Ignore. To set attribute values to the special Ignore or Blank values, you use the methods in Table 65 (defined in the CWConnectorUtil class) to obtain a special attribute value and then assign the results of these methods directly to the attribute.
Special attribute value | CWConnectorUtil method |
---|---|
Blank value | getBlankValue() |
Ignore value | getIgnoreValue() |
Once a method in Table 65 retrieves the desired special attribute value, you can pass it to one of the "set" methods for the attribute value (see Table 57), as the following code fragment shows:
attrName = theBusObj.getAttrName(i); theBusObj.setdoubleValue(attrName, CWConnectorUtil.getIgnoreValue());
As discussed in Processing hierarchical business objects,, a Java connector uses the methods of the Java connector library shown in Table 57 to access child business objects.
Java connector library class | Method |
---|---|
CWConnectorBusObj | isObjectType(),, isMultipleCard(),, getObjectCount(),, getBusObjValue() |
CWConnectorAttrType | OBJECT attribute-type constant |
The verb processing in the doVerbFor() method uses the isObjectType() method to determine if the attribute contains a business object (its attribute type is set to the OBJECT attribute-type constant). When a verb operation finds an attribute that is a business object, the method checks the cardinality of the attribute using isMultipleCard(). Based on the results of isMultipleCard(), the method takes one of the following actions:
The Java verb method can access individual business objects by calling CWConnectorBusObj.getObjectCount() to get the number of child business objects in the array. As it iterates through the business object array, the verb method can get each individual child object within the business object array using the CWConnectorBusObj.getBusObjValue(index) method, where index is the array element index. This method returns a CWConnectorBusObj that contains the a child business object. Figure 57 shows the Java code to access child business objects.
// For all attributes in the business object
for (int i=0; i<theBusObj.getAttrCount()-1; i++ ){
if ( theBusObj.isObjectType(i) ){
// cardinality N
if(theBusObj.isMultipleCard(i)){
for (int i=0; i < theBusObj.getObjectCount(); i++) {
CWConnectorBusinessObject childBusObj =
theBusObj.getBusObjValue(i);
status = doVerbMethod(childBusObj);
} // end for i to getObjectCount()
} else {
// Cardinality 1 child
CWConnectorBusObj childBusObj = null;
childBusObj = theBusObj.getBusObjValue(i);
status = doVerbMethod(childBusObj);
} // end else 1 cardinality
} // end isObjectType()
} // end for i to getAttCount()-1
The connector framework calls the doVerbFor() method in the CWConnectorBOHandler class (which implements the business object handler) for all verbs that a particular business object supports.Therefore, all verbs in a business object are processed in one standard way (although they can initiate different actions within the application). However, if your connector supports a business object that requires different processing for some particular verb, you can create a custom business object handler to handle that verb for the business object.
Creating a custom business object handler involves the following steps:
To create a custom business object handler, you must create a class that implements the CWCustomBOHandler interface. The CWCustomBOHandler interface provides the doVerbForCustom() method, which you must implement to define a custom business object handler. Follow these steps to create a custom-business-object-handler class for a Java connector:
connectorNameCustomBOHandlerverbName.java
where connectorName uniquely identifies the application or technology with which the connector communicates and verbName identifies the verb (or verbs) that this custom business object handler processes. For example, to create a custom business object handler for the Retrieve verb in a Baan application, you create a custom-business-object-handler class called BaanCustomBOHandlerRetrieve.
com.crossworlds.connectors.connectorName
where connectorName is the same as defined in step 1 above. For example, the package name for the Baan connector would be defined in the custom-business-object-handler-class file as follows:
package com.crossworlds.connectors.Baan;
com.crossworlds.cwconnectorapi.*; com.crossworlds.cwconnectorapi.exceptions.*;
If you create several files to hold the business object handler's code, you must import these classes into every file.
The doVerbForCustom() method provides the functionality for the custom business object handler. As discussed in Implementing the doVerbFor() method, the connector framework calls the low-level doVerbFor() method (defined in the BOHandlerBase class) for the appropriate business object handler when it receives a request business object. This low-level doVerbFor() method determines which business object handler to call as follows:
The CBOH tag specifies the full name (including the package name) of the custom-business-object-handler class, which implements the CWCustomBOHandlerInterface interface and its doVerbForCustom() method. For more information on this class name, see the description of Adding the verb application-specific information.
If the CBOH tag exists, the low-level doVerbFor() method tries to create a new instance of the class that this tag specifies. If this instantiation is successful, the low-level doVerbFor() calls the doVerbForCustom() method in this class.
The implementation of the doVerbForCustom() method must handle the verb processing of the verb for which its class is specified. You can refer to Implementing the doVerbFor() method for information on the verb processing that the doVerbFor() method usually provides. However, you must customize the behavior of doVerbForCustom() to meet the special processing needs of your business object's verb.
The low-level doVerbFor() method handles return values and exceptions from doVerbForCustom() as follows:
For the connector framework to call a custom business object handler for a particular business object, the verb of this business object must have the CBOH tag in its verb application-specific information. The CBOH tag has the following format:
CBOH=connectorPackageName.CustomBOHandlerClassName
In this format, the connectorPackageName is as follows:
com.crossworlds.connectors.connectorName
with connectorName the name of the connector. The CustomBOHandlerClassName is the name of the class that implements the CWCustomBOHandlerInterface interface.
For example, the following CBOH tag specifies a class called BaanCustomBOHandlerRetrieve:
CBOH=com.crossworlds.connectors.Baan.BaanCustomBOHandlerRetrieve