Connector business object structure

The connector processes business objects used by enterprise beans. This section describes the key concepts related to the structure of business objects processed by the EJB connector.

Attributes

For each public member variable, or attribute, present in an enterprise bean that has been defined in a JAR file, a corresponding business object attribute is generated by the ODA. The JAR file, which contains interfaces (each with methods and properties), is used by the ODA to compile business object definitions that map to remote and local enterprise beans.

If an attribute in the bean class is not a simple attribute, but instead is an object, then the business object (BO) attribute maps to a child object whose definition matches the corresponding Java class or EJB interface.

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 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

The EJB connector requires the business object to have a creator method and one or more business object methods. An attribute is created in the business object for each create method on the home interface and for each method defined in the remote interface. For methods, 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 EJB method. The child BO also has a Return_Value attribute (unless the method being defined is of type void) always appearing last in the order of arguments, that represents the result of the EJB method call. These attributes (of the child BO) can be simple type or object type (complex), depending on the type of the method parameter or return value.

Whenever properties or method names contain special characters, the attribute names corresponding to these are modified to suit WebSphere Business Integration format and the attribute ASI would be used to set the actual name of the property or method.

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 is represented as a name-value pair and can be specified for the overall business object, for each business object attribute, and for each verb.

Business object-level ASI

Object-level ASI provides fundamental information about the nature of a business object and the objects it contains. Table 4 describes the business object-level ASI of business objects that represent enterprise beans.

Note:
ASI names are not recognized for business objects that represent methods, method parameters, and method return values. For details about business object attributes created for methods of enterprise beans, see Methods.

Table 4. Business object-level ASI

Object-level ASI Description
object_type=RemoteEJB Indicates that the object is an enterprise bean deployed on an application server (remote), rather than a standard Java class that is not deployed on an application server (local).
jndi_name=<JNDIName> The JNDI name of the enterprise bean
home_name=<className> The class name of the home interface
proxy_class=<className> The class name of the remote interface

The following example illustrates business object-level ASI for a business object that the connector is processing with enterprise beans deployed on WebSphere Application Server. When the connector receives the business object from the broker, it first locates an instance of the home interface (com.ibm.websphere.AccountBookHome) on the application server, by looking up WsSamples/Account in the configured JNDI context. The connector than uses this home instance to create a new instance of the remote interface (com.ibm.websphere.AccountBook), which it can use to invoke methods on the EJB.

BO ASI=object_type = RemoteEJBObject
            proxy_class = com.ibm.websphere.AccountBook
            home_class = com.ibm.websphere.AccountBookHome
            jndi_name = WsSamples/Account
 

In this code sample:

A standard Java object (local) would have a BO ASI = auto_load_or_write=<boolean value>.

The business object ASI for a data handler-supported message should contain the value object_type=dataHandlerObject; mime_type=<text_value> where <text_value> is the appropriate mime-type defined for the data handler (as specified in the data handler meta-object) that the adapter should use to convert the data.

Verb ASI

Every business object contains a verb. The verb indicates which methods to invoke on the enterprise bean. For the adapter for EJB, the first method should be a creator method from the corresponding bean's home interface, and the remaining methods should be business process methods from the bean's remote interface.

The verb ASI contains a sequence of attribute names, each of which contains a method for the business object handler to call. Typically, the method to be invoked belongs to the object itself (versus belonging to a parent of the business object), in which case you specify the method in the object's verb ASI. For example, an enterprise bean 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 from the child by prefixing the method name with the PARENT tag.

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

Figure 3. 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. A parent business object cannot invoke a child's method.

The connector developer determines the EJB operations assigned to the verb. Supported verbs include:

For a given object, you can specify the four supported verbs (Create, Retrieve, Delete, and Update) and assign as actions of each verb n methods, where n equals the number of methods in the corresponding enterprise bean.

Attribute-level ASI

The attribute-level ASI of a business object can be for simple attributes and complex attributes, which contain child objects. For a complex attribute, the ASI varies, depending on whether the contained child is a property or a method of an object. The mapping of EJB constructs to the ODA-generated business objects is described in Table 8.

Table 5 describes the ASI for simple attributes. A simple attribute is always a non-child, for example a boolean, string, or integer value.

Table 5. Attribute-level ASI for simple attributes

Attribute Description
Name Specifies the business object field name.
Type Specifies the business object field type. See Table 8 for details about mapping EJB constructs to business object attribute types.
MaxLength Not used.
IsKey Each business object must have at least one key attribute, which you specify by setting the key property to true for an attribute. Note that this attribute is used by Business Object Designer, rather than by the connector.
IsForeignKey Specifies that the connector should check whether or not the object must be stored in the per call object pool.
IsRequired Not used.
AppSpecInfo Holds the original Java type. This attribute is formatted
as follows:


property=<propertyName>, type=<typeName>


property is the name of the EJB attribute or object member variable. Use this
name-value pair to capture the original EJB object member variable name.


type is the Java type of a simple attribute (the EJB object member variable).
For example, type=java.lang.String
See Table 8 for details about mapping EJB constructs to
business object attribute types.


This attribute should be set to proxy if the attribute is a business object. If it
does not map to a business object and is not intended to be de-referenced, as
in the case of a simple attribute, you can specify type=PlaceholderOnly. This
tells the BO handler to not de-reference and not populate the attribute. The
attribute can thus continue to be used as part of a multi-call flow if it is marked
as a foreign key (IsForeignKey is checked), or if use_attribute_value is set to
a compatible value.

DefaultValue Not used.

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

Table 6. Attribute-level ASI for attributes containing non-method child objects

Attribute Description
type The type of the contained object. Set to proxy if the type is a business object.
ContainedObjectVersion Not used.
Relationship Specifies that the child is a container attribute. Set to Containment.
IsKey Not used
IsForeignKey Not used
Is Required Not used
AppSpecificInfo Holds the original EJB application field Name. This attribute is
formatted as follows:


property=propertyName, use_attribute_value=<(optional)BOName.AttributeName>,
type=<typeName>


property is the name of the EJB object member variable. Use this
name-value pair to capture the original EJB object attribute
name. In the case of an attribute that holds an argument to a
method, do not set a value for property, as the argument does
not have a name and is simply an argument of any standard
type.


use_attribute_value is the business object name formatted
as BOName.AttributeName. Setting this ASI causes the connector
to access the attribute from the per call object pool. Note that
this value is not set in the ODA when you create the business
object, but rather via Business Object Designer.


type is the Java type of a property. This should be set to proxy
if the attribute is non-simple, in other words, if it holds a business
object. See Table 8 for the mapping of EJB constructs to
business objects.)

Cardinality Set to n if the type represents an array or vector. Otherwise, set to 1.

Table 7 describes the ASI of complex attributes containing child objects that are methods.

Table 7. Attribute-level ASI for attributes containing method child objects

Attribute Description
Name The business object field name.
type The business object.
Relationship Set to Containment, indicating that this is a child object.
IsKey Set to true if the attribute name equals UniqueName, otherwise it is set to false.
IsForeignKey Set to false.
Is Required Set to false.
AppSpecificInfo Holds the exposed remote method name, which is the name of the
method call placed to the EJB server by the enterprise bean. This attribute is
formatted as:


method_name=<remoteClassName.RemoteMethodName>


If the method is a constructor, method_name=CONSTRUCTOR

Cardinality Set to 1.

Note that methods have arguments and return values. Arguments and return values can be complex (containing child objects) or simple.

Copyright IBM Corp. 1997, 2003