A business object handler's role is to deconstruct a request business object, process the request, and perform the requested operation in the application. To do this, a business object handler extracts verb and attribute information from the request business object and generates an API call, SQL statement, or other type of application interaction to perform the operation.
Basic business object processing involves extracting metadata from the business object's application-specific information (if it exists) and accessing the attribute values. The actions to take on the attribute value depend on whether the business object is flat or hierarchical. This section provides an overview on how a business object handler can process the following kinds of business objects:
This section provides the following information on how to process flat business objects:
If a business object does not contain any other business objects (called child business objects), it is called a flat business object. All the attributes in a flat business object are simple attribute; that is, each attribute contains an actual value, not a reference to another business object.
Suppose you have to perform verb processing on an example business object named Customer. This business object represents a single database table in a sample table-based application. The database table is named customer, and it contains customer data. Figure 40 shows the Customer business object definition and the corresponding customer table in the application.
Figure 40. A Flat business
object and corresponding application table
As Figure 40 shows, the example Customer business object has four simple attributes: CustomerId, CustomerName, CustomerStatus, and CustomerRegion. These attributes correspond to columns in the customer table. The business object also includes the required ObjectEventId attribute.
Figure 41 shows an expanded business object definition and an instance of the business object. The business object definition contains the business object name, and the attribute name, properties, and application-specific information. The business object instance contains only the business object name, the active verb, and the attribute names and values.
Figure 41. A flat business
object with application-specific information
After the verb operation has accessed information it needs within the business object definition, it often needs to access information about attributes. Attribute properties include the cardinality, key or foreign key designation, and maximum length. For example, the example Create method needs to obtain the attribute's application-specific information. A connector business object handler typically uses the attribute properties to decide how to process the attribute value.
Figure 42 illustrates business object attribute properties of the CustomerId attribute from the business object in Figure 41..
Figure 42. Business object
attribute properties
Each attribute has a zero-based integer index ( ordinal position) within the business object definition. For example, as Figure 42 shows, the CustomerId attribute would be accessed with an ordinal position of zero (0), the CustomerName attribute with an ordinal position of one (1), and so on. The Java connector library provides access to an attribute through its name or ordinal position.
For the business object handler that handles the flat Customer business object, deconstructing a business object includes the following steps:
As Figure 41 shows, the Customer business object definition is designed for a metadata-driven connector. Its business object definition includes application-specific information that the verb operation uses to locate the application entity upon which to operation. The application-specific information is designed as shown in Table 43..
Table 43. Application-specific information for a table-based application
Application-specific information | Purpose |
---|---|
Business object definition | The name of application database table associated with this business object |
Attribute | The name of the application table's column associated with this attribute |
Business objects are hierarchical: parent business objects can contain child business objects, which can in turn contain child business objects, and so on. A hierarchical business object is composed of a top-level business object, which is the business object at the very top of the hierarchy, and child business objects, which are all business objects under the top-level business object. A child business object is contained in a parent object as an attribute.
This section provides the following information on how to process hierarchical business objects:
If a top-level business object has child business objects, it is the parent of its children. Similarly, if a child business object has children, it is the parent of its children. The parent/child terminology describes the relationships between business objects, and it may also be used to describe the relationship between application entities.
There are two types of containment relationships between parent and child business objects:
Figure 43 shows a typical hierarchical business object. The top-level business object has both cardinality 1 and cardinality n relationships with child business objects.
Figure 43. Hierarchical
business object
In a typical table-based application, relationships between entities are represented by primary keys and foreign keys in the database, where the parent entity contains the primary keys and the child entity contains the foreign keys. An hierarchical business object can be organized in a similar way:
The child business object typically contains one or more foreign keys whose values are the same as the corresponding primary keys in the parent business object. Although applications might structure the relationships between entities in different ways, a single cardinality relationship for an application that uses foreign keys might be represented as shown in Figure 44..
Each child business object within the array contains foreign key attributes whose values are the same as the corresponding values in the primary key attributes of the parent business object. A multiple cardinality relationship might be represented as shown in Figure 45..
As part of its verb processing, the doVerbFor() method needs to handle any hierarchical business objects. To process a hierarchical business object, the doVerbFor() method takes the same basic steps as it does to process a flat business object: it obtains any application-specific information and then accesses the attribute. However, if the attribute contains a child business object, doVerbFor() must take the following steps to access the child business object:
The OBJECT type indicates that the attribute is a complex attribute; that is, it contains a business object rather than a simple value. The OBJECT attribute-type constant is defined in the CWConnectorAttrType class. The isObjectType() method returns True if an attribute is complex; that is, if it contains a business object.
If the attribute has single cardinality (cardinality 1), the method can perform the requested operation on the child. One way to perform an operation on a child business object is to recursively call doVerbFor() or a verb method on the child object. However, such a recursive call assumes that the child business object is set as follows:
If an attribute has multiple cardinality (cardinality n), the attribute contains an array of child business objects. In this case, the connector must access the contents of the array before it can process individual child business objects. From the array, the doVerbFor() method can access individual business objects:
Once the doVerbFor() method has access to a child business object, it can recursively process the child as needed.
When a connector a request business object, the business object includes all its arrays even though some or all of the arrays might be empty. If an array contains no child business objects, it is an array of size 0.
You might want to modularize your verb operation so that the main verb method calls a submethod to process child objects. For a business object such as the one shown in Figure 46,, a Create method might first create the application entity for the parent Customer business object, and then call the submethod to traverse the parent business object to find attributes referring to contained business objects.
Figure 46. Example of a
hierarchical business object definition
When the submethod finds an attribute that is an OBJECT type, it can process the attribute as needed. For example, the submethod processes the Address attribute by retrieving each child business object in the Address array and recursively calling doCreate(). One by one, the main method creates each address entity in the database until all Address children in the array are processed. Finally, the submethod processes the single cardinality CustProfile business object.
For more information about how to access a child business object, see Accessing child business objects."Accessing child business objects:" on page 183.