Connector business object structure

The connector processes two kinds of business objects, both of which are generated by the ODA:

Note that if an IDL component is intended both as a client and server-side object, the ODA has to generate two separate business objects, one for client-side processing and one for server-side processing. In this case, make sure to run the ODA twice against the same IDL component: the first time, run it with the ODA CORBAServerImpl property set to true to generate a server-side business object; then, run the ODA again with the same property set to false. For details about this property, see Configure the agent.

This section describes the key concepts related to the structure of business objects processed by the CORBA connector.

Attributes

For each attribute present in a CORBA class defined in the IDL file, a corresponding business object attribute is generated by the ODA. The IDL file is used by the ODA to compile proxy object definitions.

If an attribute in the CORBA class is not a simple attribute, and instead is a struct (Figure 6), union (Figure 9), or sequence (Figure 8), then the BO attribute maps to a child object whose definition matches the corresponding constructed type (construct) in the CORBA object. The CORBA enum construct (Figure 10) maps to a simple attribute, rather than to a child object attribute.

The primary constructs of CORBA are described in Table 9 and illustrated in Figure 6 through Figure 9. For a complete list of the mapping between CORBA constructs and business objects, see Mapping attributes: CORBA, Java, and business object.


Table 9. CORBA Constructs

CORBA construct Description
struct An object that holds business data, as illustrated in Figure 6
interface An object that holds a list of business operations (methods), as illustrated in Figure 7
sequence An object that holds a list of structs or simple data types, as illustrated in Figure 8. A CORBA sequence maps to a cardinality n business object, as does an array.
union A collection of structs or simple data types, as illustrated in Figure 9. Note that only one attribute within a union can have a value at a given time.
enum An object that contains a list of sequential or enumerated identifiers, as illustrated in Figure 10.



Figure 6. CORBA construct: struct



Figure 7. CORBA construct: interface



Figure 8. CORBA construct: sequence



Figure 9. CORBA construct: union



Figure 10. CORBA construct: enum

Some business object attributes, instead of containing data, point to child business objects or arrays of child business objects that contain the data for these objects. Keys relate the data between the parent record and child records.

Business objects can be flat or hierarchical. A flat business object only contains simple attributes, that is, attributes that represent a single value (such as a string) and do not point to child business objects. A hierarchical business object contains both simple attributes and child business objects or arrays of child business objects that contain attribute values.

A cardinality 1 container object, or single-cardinality relationship, occurs when an attribute in a parent business object contains a single child business object. In this case, the child business object represents a collection that can contain only one record. The attribute type is the same as that of the child business object.

A cardinality n container object, or multiple-cardinality relationship, occurs when an attribute in the parent business object contains an array of child business objects. In this case, the child business object represents a collection that can contain multiple records. The attribute type is the same as that of the array of child business objects.

Methods

For each method defined in the CORBA IDL file, an attribute is created in the business object. The attribute type is a child BO containing attributes that represent method parameters. The attributes of the child BO appear in the exact same order as the parameters of the CORBA method. The child BO also has a Return_Value attribute that represents the result of the CORBA method call. These attributes (of the child BO) can be simple type or object type, depending on the type of the method parameter or return value.

Application-specific information

Application-specific information provides the connector with application-dependent instructions on how to process business objects. If you extend or modify a business object definition, you must make sure that the application-specific information in the definition matches the syntax that the connector expects.

Application-specific information can be specified for the overall business object as well as for each business object attribute.

Business object-level ASI

Object-level ASI provides fundamental information about the nature of a business object and the objects it contains. The required ASI for a business object depends on whether you are generating the object for the connector running as a server or as a client.

Note:
Application specific information is used for business objects that represent methods, method parameters, and method return values. For details about business object attributes created for methods of CORBA objects, see Methods.

Table 10 describes the business object-level ASI of business objects that are processed as client objects when the connector for CORBA runs as a client.


Table 10. Object-level ASI for client objects

Object-level ASI Description
proxy_class=<nameOfProxy> The name of the proxy class that the business object represents. Use this ASI to map a proxy class to a business object. You must specify this using valid Java Package notation (for example, java.lang.Vector).

Table 11 describes the business object-level ASI of business objects that are processed as server objects when the connector acts as a server against which external CORBA client objects can make method calls.


Table 11. Object-level ASI for server objects

Object-level ASI Description
proxy_class=<nameOfProxy> The name of the proxy class that the business object represents. Use this ASI to map a proxy class to a business object. This must be specified using Java Package notation (for example, java.lang.Vector).
object_type=CorbaImplObject If the connector runs as a server and the BO is intended for CORBA clients to invoke method calls against the BO, set this ASI to CorbaImplObject.
implementation_class=

The name of the implementation class that corresponds to the server business object you are creating in the ODA. The implementation class name is always: com.ibm.adapters.corbaadapter.impl.
<ClassName>Impl

where <ClassName> is the name of the original class being implemented. The classes are stored in an output .jar file and saved to the following folder:

com\ibm\adapters\corbaadapter\impl

Figure 11 illustrates the object level ASI for a sample business object acting as a server object.



Figure 11. Sample business object-level ASI of a server-side object

Verb ASI

When the connector runs as a client, every client-side business object that it processes contains a verb. The verb describes how the data in the business object should be handled by the receiving application.

Note:
Server-side objects, processed when the connector runs as a server, do not have a verb ASI.

The verb ASI contains a sequence of attribute names, each of which contains a method for the generic business object handler to call. Typically, the method to be invoked belongs to the object itself (versus belonging to the parent), in which case you specify the method in the object's verb ASI. For example, an object that has the method IncrementCounter would require that you specify that method in the corresponding business object's verb ASI.

If the method to be invoked belongs to a parent in the business object hierarchy, then that parent can be referenced by prefixing the method name with the PARENT tag.

For example, Figure 12 illustrates a business object hierarchy whereby ContactDetails is a child object of Contact, which itself is a child of PSRCustomerAccount.

Figure 12. Business object hierarchy and verb ASI

If a method that belongs to PSRCustomerAccount is called on the ContactDetails business object, then the verb ASI for ContactDetails represents the business object hierarchy as follows:

PARENT.PARENT.<methodName>

If the method belongs instead to the Contact business object, then the verb ASI for ContactDetails must be set as:

PARENT.<methodName>

Note that only methods that belong to parent objects within the hierarchy can be called. Furthermore, a parent business object cannot invoke a child's method.

The connector developer determines the CORBA operations assigned to the verb. Although you can add other verbs manually using Business Object Designer, the supported verbs include:

The following keywords can be used in the verb ASI sequence of attribute names:

Table 12. Keywords allowed in verb ASI

Keyword Description
LoadFromProxy= <attributeName> Loads the specified non-method attribute value from the proxy object.
WriteToProxy = <attributeName> Writes the non-method attribute value from the business object into the proxy object.
LoadFromProxy (no attribute name) Loads all the non-method attributes on the current BO from proxy object.
WriteToProxy (no attribute name) Writes all the non-method attributes on the current BO to the proxy object.
CBOH=<custom BO handler className> The class name of a custom BO handler, in cases where the generic BO handler is not used. For information about custom BO handlers, see Custom business object handlers.

For a given object, you can specify the four supported verbs (Create, Delete, Retrieve, and Update) and assign as actions of each verb n plus two methods, where n equals the number of methods in the corresponding CORBA interface. The two additional methods are those supported by the connector,LoadFromProxy and WriteToProxy, as defined in Table 12.

Attribute-level ASI

The attribute-level ASI of a business object can be for complex attributes, which contain child objects, and simple attributes. For a complex attribute, the ASI varies, depending on whether the contained child is a property (non-method) or a method of the object. The mapping of all the attribute-types in the original CORBA IDL file to the business object is defined in Table 16.

Table 13 describes the ASI for simple attributes.


Table 13. Attribute-level ASI for attributes that contain simple attributes

Attribute ASI Description
Name Specifies the business object field name.
Type Specifies the business object field type.
MaxLength 255 by default
IsKey Each business object must have at least one key attribute, which you specify by setting the key property to true for an attribute.
IsForeignKey Set to true if you want the connector to add the value to the per-call object pool.
IsRequired Set to false.
AppSpecInfo Holds the original Java type. This attribute is formatted as follows:


property=<propertyName>; type=<typeName>


property is the name of the CORBA object attribute. Use this ASI to capture
the original CORBA object attribute name.


type is the name of the CORBA simple attribute type. Use this attribute to
capture the original CORBA type name.

DefaultValue Specifies a default value that the connector uses for a simple attribute in the inbound business object if the attribute is not set and is a required attribute.

Table 14 describes the ASI for complex, non-method attributes. These attributes contain non-method child objects, such as properties of a class in the original CORBA IDL file.


Table 14. Attribute-level ASI for attributes that contain non-method child objects

Attribute Description
Name Specifies the business object field name.
Type Specifies the business object field type.
MaxLength 255 by default
IsKey Each business object must have at least one key attribute, which you specify by setting the key property to true for an attribute.
IsForeignKey Set to true if you want the connector to add the value to the per-call object pool.
IsRequired Set to false.
AppSpecInfo Holds the original Java type. This attribute is formatted
as follows:


type=<typeName>; use_attribute_value=<BOName.AttributeName>;
property=<propertyName>; proxy_class=<proxyClassName>;
enumeration_class=<enumerationClassName>; inout=<true or false>;
union=true; union_key=<unionKeyName>
;



type is the name of the proxy class when you are referring to an object.


use_attribute_value is set to <BOName.AttributeName>. If you specify a
value for this element, the connector pulls the value from the per-call
object pool at runtime.


property is the name of the CORBA object attribute. Use this ASI to capture
the original CORBA object attribute name.


proxy_class is optional. Use only if the attribute is of type in / out.


enumeration_class is the CORBA enumeration class to which this non-method
attribute corresponds. Use this optional element only if the attribute maps to a
CORBA enumeration construct.


inout is set to true or false. Use this optional element only if the attribute is of
type in / out as a method parameter.


union should be set to true. Use this optional element only if the child BO maps
to a CORBA union construct.


union_key is the mapping key to each method that returns a value in the union.
Use this optional element only if the BO maps to a CORBA union construct.


For details about CORBA constructs and structures, see Attributes

DefaultValue Specifies a default value that the connector uses for a simple attribute in the inbound business object if the attribute is not set and is a required attribute.

Table 15 describes the ASI for complex attributes containing child objects that are methods.

Table 15. Attribute-level ASI for attributes that contain method child objects

Attribute Description
Name Specifies the business object field name.
Type Specifies the business object field type.
Relationship If the child is a container attribute, this is set to Containment.
IsKey Not used.
IsForeignKey Set to false.
Is Required Set to false.
AppSpecInfo Holds the original CORBA application method name. This attribute
is formatted as follows:


method_name=<methodName>; verb=<verbName>;



method_name is the name of the method call placed to the external CORBA
server, when the connector runs as a client.


verb is the verb that the connector sets on the business object before invoking
the collaboration, when the connector runs as a server. This verb corresponds
to the method call from the external CORBA client. The method call is a
request to execute a collaboration. Use only if the BO acts as a CORBA
server object that is receiving method calls from an external CORBA client
object. For a list of valid verbs, see Verb ASI

Cardinality Set to N if the type represents an array or vector, otherwise set to 1.

Copyright IBM Corp. 1997, 2003