Connector business object structure

The connector requires a hierarchical business object. The top-level business object contains attributes whose values are the destination URL string, the MIME type of the data, the business object prefix, and the request and response business objects.

Figure 6 illustrates the required basic structure of a top-level business object for the IBM WebSphere Business Integration Adapter for XML.

Figure 6. Basic Structure of a top-level business object


For example, if you create two business objects, XMLApp_CustCreateRequest and XMLApp_CustCreateResponse, then a top-level business object definition for the connector might look like:

XMLApp_CustCreate 
 
URL      String
MimeType String
BOPrefix String
Response XMLApp_CustCreateResponse
Request  XMLApp_CustCreateRequest

Use Business Object Designer to create the request and response business objects. Create the top-level business object definition, and add the required attributes and the request and response business objects. Then configure the connector to support the top-level business object.

Required attributes for the top-level business object

The top-level business object must have at least one attribute for the URL string, MIME type, BOPrefix, request business object, and response business object. Each of these attributes must be marked IsRequired = True.

Table 13 describes the required attributes of a top-level business object. See the sections that follow for more information.

Table 13. Required attributes for a top-level XML business object

Attribute Type Description
URL String Destination URL.
MimeType String MIME type to be used for the transaction.
BOPrefix String Used with the MIME type to create an instance of the XML data handler.
Response Business object Business object that represents a response message. See "Request and response business objects".
Request Business object The business object that represents a request message. In the top-level business object, place this attribute after the attribute for the response business object.

Note:
The connector requires that you set at least one attribute as the key attribute. However, the connector does not need any attributes to be set as the key.

URL

The URL string defines the destination of the data in the business object and the protocol to use to pass the data. The string contains the entire destination, including the protocol (such as HTTP or HTTPS); therefore, a separate attribute that specifies the protocol is not required.

The URL string is used by the connector to open a connection to the destination URL. When a connection is opened, the connector uses the URL string to create an instance of the appropriate protocol handler.

For example, the string http://www.ibm.com specifies that the HTTP protocol is being used, and an instance of the HTTP Protocol Handler is created.

MIME type

The MIME type defines the content type and format for the data that is being passed to a URL. The connector uses the MIME type to invoke the appropriate data handler. A meta-object identifies the data handler instance for the MIME type/BOPrefix combination. If the data handler implementation handles only one MIME type, the BOPrefix attribute in a child meta-object is optional. In a top-level business object, it is required.

The connector expects the MIME type to be text/xml by default, but you can configure the connector to use other MIME types.

BOPrefix

The connector uses the BOPrefix with the MimeType attribute to invoke the appropriate data handler instance. This attribute is required to guarantee the uniqueness of a business object name. For example, you can have two Purchase Order business objects for different applications: AppA_PO and AppB_PO.

Note:
The BOPrefix attribute in a top-level business object is different from the BOPrefix attribute in a child meta-object for the XML data handler. For more information on XML data handler child meta-objects, see the Data Handler Guide.

When an XML stream returns from a URL, the XML data handler maps the root element name in the XML stream to the business object definition BOPrefix_name. The value of the root element name is always placed after the value of BOPrefix.

For example, if you have the root element as <Customer> in the XML document and BOPrefix=AppA, then the BOPrefix_Name is AppA_Customer.

Request and response business objects

The request and response business objects contain the actual data to be passed to a destination URL. When the connector receives a top-level business object, only the request business object is populated; the response business object is populated with the data returned from the destination URL.

Note these guidelines for defining request and response business objects in the top-level business object:

Business object conformance with data handler requirements

Although you can include any WebSphere Business Integration Adapter business object in the top-level wrapper business object for the connector, the contained business objects must deliver data in a form that is compliant with the requirements of the data handler used to convert the data.

For example, for the BySize data handler, a business object definition must specify a value for the MaxLength attribute property for each business object attribute. For the XML data handler, the business object definition must include application-specific information that enables the data handler to generate an XML document.

Therefore, a good practice is to create your own business object for each type of data to be processed. In the business object, provide only the data required by the application and the information required by the data handler. You can then include these business objects in the top-level connector business object.

See the Data Handler Guide for information specific to each data handler.

Copyright IBM Corp. 1997, 2003