Business Integration Connect provides the Attachment data handler to process documents that are sent between Business Integration Connect to InterChange Server and InterChange Server. The Attachment data handler converts a document within the XML transport envelope (with or without attachments) between its serialized format and its business-object representation. You should configure the Attachment data handler as the payload data handler in either of the following cases:
When this flag is set to Yes, Business Integration Connect always wraps a document in an XML transport envelope, regardless of whether it contains attachments. You set this flag to Yes for Backend Integration packaging as part of the profile's B2B Capabilities screen. For more information, see Payload.
When a document contains attachments, Business Integration Connect wraps it in an XML transport envelope. In any document flow, there is one payload and, optionally, multiple attachments. If you are sending or receiving documents that contain attachments, your payload business object needs to contain attachment information.
The Attachment data handler can be called in any of the following contexts:
If Business Integration Connect and a pre-4.2.2 version InterChange Server participate in event notification (Business Integration Connect initiates the request), the WebSphere Business Integration Connect Servlet (an access client) sends the document to Server Access, which calls the Wrapper data handler to convert the document to its business-object representation. If this document is wrapped in an XML transport envelope, the Wrapper data handler calls the Attachment data handler to convert the serialized form of the document (in its XML transport envelope) into the corresponding business object.
Regardless of whether the calling entity is an adapter or Server Access, when the calling entity receives a document within an XML transport envelope, it calls the Attachment data handler to convert this document to its appropriate business-object representation. For example, Figure 20 shows the Adapter for JMS calling the Attachment data handler to convert the serialized format of the document to its business-object representation. Conversely, when the calling entity receives a business-object representation for a document within an XML transport envelope, it calls the Attachment data handler to convert this business-object structure to its appropriate document format. For example, Figure 21 shows the Adapter for JMS calling the Attachment data handler to convert the business-object representation of the document to its serialized format.
This section provides the following information on the Attachment data handler:
The Attachment data handler can interpret the structure of this XML transport envelope and handle the conversion between the contained data and the corresponding business-object representation, as follows:
Before Business Integration Connect sends a document to InterChange Server, it must determine whether to wrap the contents in an XML transport envelope. If Business Integration Connect creates the transport envelope, the payload and any attachments are Base64 encoded. Business Integration Connect then sends the XML transport envelope to the appropriate ICS-compatible component with the appropriate transport-level headers. This ICS-compatible component (a WebSphere Business Integration adapter or the Wrapper data handler) can be configured to call the Attachment data handler to handle the conversion of payload and any attachments in an XML-wrapped document into the corresponding business-object representation.
To convert a document wrapped in an XML transport envelope to its business-object representation, the calling entity instantiates the Attachment data handler, passing it the document (in its transport envelope). The Attachment data handler then takes the following steps:
The content-type maps are defined in the ContentTypeMap_x configuration properties of the child meta-object. The child meta-object is a business object that contains configuration information for the Attachment data handler. Attributes in this business object associate content-type maps with content types. For more information, see Creating the Attachment child meta-object.
The document contains only a payload, which the Attachment data handler must convert to its associated business-object representation. For more information, see Processing a document not in a transport envelope.
The document contains a payload and possibly some attachments. Therefore, the Attachment data handler needs to convert the payload and any attachments to their associated business-object representation. For more information, see Processing a document in a transport envelope.
If the Attachment data handler determines that the document is not contained in an XML transport envelope, it does not need to extract the payload data from the envelope structure. Therefore, the data handler uses the PayloadDataHandlerMimeType configuration property (defined in its child meta-object) to obtain the MIME type that identifies the default payload data handler to instantiate for the document payload. This data handler converts the payload data to its corresponding payload business object and returns the resulting payload business object to its calling entity.
If the Attachment data handler determines that the document is contained in an XML transport envelope, it must extract the payload and any attachments from this envelope structure before it can process them. Therefore, the data handler takes the following steps to process and convert the document:
The payload is contained in the <payload> XML tag. Each attachment is contains in an <attachment> XML tag.
Use the MIME type specified in the matching content-type map to create an instance of a data handler. This data handler converts the payload data to its corresponding payload business object and returns the resulting business object to the Attachment data handler.
Examine the business-object-level application-specific information of the payload business object definition and determine the name of the content-information business object, whose attribute name is specified by the cw_mo_bcg_content_info tag. Create an instance of this content-information business object and set the values for payload's content type and encoding.
Examine the business-object-level application-specific information of the payload business object and determine the name of the attachment-container business object, whose attribute name is specified by the cw_mo_bcg_attachment tag. Create an instance of the attachment-container business object and save it in the appropriate attribute of the payload business object.
If the cw_mo_bcg_attachment tag does not exist (or is empty), assume that the document does not contain any attachments. Therefore, no further processing steps are required. The Attachment data handler returns the converted payload business object.
Examine the business-object-level application-specific information of the attachment-container business object and determine the name of the default attachment business object, whose attribute name is specified by the cw_mo_bcg_default_attribute tag. Create an instance of the default attachment business object and save it in the appropriate attribute of the attachment-container business object.
Get the content type and character-set encoding from the attachment and check to see whether there is a corresponding entry in a content-type map.
Therefore, the data handler creates an instance of the default attachment business object, sets the values for the content type and encoding within its content-information business object, and sets the base64-encoded attachment data (as a string) in the attachment attribute.
The Attachment data handler then populates the attachment-container business object with the default attachment business object.
The Attachment data handler then populates the attachment-container business object with the default attachment business object.
The Attachment data handler then examines the business-object-level application-specific information of the attachment business object definition and determines the name of the content-information business object, whose attribute name is specified by the cw_mo_bcg_content_info tag. If this tag exists, the data handler creates the content-information business object for the attachment and sets the values for attachment's content type and encoding.
Finally, the Attachment data handler populates the attachment-container business object with the attachment business object.
Before Business Integration Connect receives a document from InterChange Server, an ICS-compatible component must determine whether to wrap the business-object representation of the payload and any attachments in the XML transport envelope. InterChange Server sends the business object to the appropriate ICS-compatible component, which handles the actual conversion. This ICS-compatible component (a WebSphere Business Integration adapter or the Wrapper data handler) can be configured to call the Attachment data handler to handle the conversion of payload and any attachment business objects into the corresponding payload and attachments as well as the creation of an XML transport envelope.
To convert a payload business object with attachments to its transport-envelope representation, the calling entity instantiates the Attachment data handler, passing it the payload business object. The Attachment data handler takes the following steps:
The content-type maps are defined in the ContentTypeMap_x configuration properties of the child meta-object. The child meta-object is a business object that contains configuration information for the Attachment data handler. Attributes in this business object associate content-type maps with content types. For more information, see Creating the Attachment child meta-object.
The document contains only a payload, which the Attachment data handler must create from its associated business-object representation. The data handler does not need to create a transport envelope for the document. For more information, see Creating a document without a transport envelope.
The document contains a payload and possibly some attachments. Therefore, the Attachment data handler needs to convert the payload business-object representation to a payload and any attachments and wrap these components in a transport envelope. For more information, see Creating a document with a transport envelope.
If the Attachment data handler determines that the payload business object does not require an XML transport envelope, it does not need to wrap the payload data in the envelope structure. Therefore, the data handler uses the default payload data handler to convert the payload business object to its corresponding payload document. The PayloadDataHandlerMimeType configuration property (defined in the Attachment data handler's child meta-object) contains the MIME type that identifies the default payload data handler to instantiate for the payload business object. This data handler receives the payload business object as an argument and returns the resulting payload document to its calling entity.
If the Attachment data handler determines that the payload business object does require an XML transport envelope, it must wrap the payload and attachment documents in this envelope structure. Therefore, the data handler takes the following steps to process and convert the business object:
The cw_mo_bcg_content_info tag in the business-object-level application-specific information of the payload business object specifies the name of the content-information attribute. This attribute contains the content type and encoding for the payload.
Use the MIME type specified in the matching content-type map to create an instance of a payload data handler. This data handler converts the payload business object to its corresponding payload document and returns the resulting document to the Attachment data handler. From the string that is returned by the payload data handler, the Attachment data handler encodes the bytes using Base64 and stores the result in the payload tag of the XML transport envelope.
The attachment container resides in the attachment-container attribute of the payload business object. The business-object-level application-specific information of the payload business object contains the cw_mo_bcg_attachment tag, which identifies the attachment-container attribute. This attribute contains the attachments.
If the cw_mo_bcg_attachment tag does not exist (or is empty), assume that the document does not contain any attachments. Therefore, no further processing steps are required. The Attachment data handler returns the converted payload in its transport envelope.
The Attachment data handler takes the following steps to process the attachment business object:
The business-object-level application-specific information of the attachment business object contains the cw_mo_bcg_content_info tag, which identifies the content-information attribute. This attribute contains the content type and encoding for this attachment. The Attachment data handler stores this content information in the attachment tag of the document.
Use the MIME type in the matching content-type map to create an instance of a data handler. This data handler converts the attachment business object to its corresponding attachment document and returns the resulting document (as a string) to the Attachment data handler.
The Attachment data handler gets the bytes from the returned string (using the character set, if one was present) and encodes the bytes using Base64. It then stores the result in the attachment tag.
Use of the Business Integration Connect-supplied Attachment data handler involves the following steps:
The Attachment data handler and associated repository file are available on
the Business Integration Connect installation medium, in the locations listed
in Table 38.
Table 38. Location of the components for Attachment data handler
Component | Location |
---|---|
Attachment data handler |
Integration/WBI/WICS/Attachment/ bcgwbiattachmentdh.jar |
Repository file |
Integration/WBI/WICS/Attachment/ MO_DataHandler_DefaultAttachmentConfig.in |
Deploy the files into the Web server according to the documentation for the Web server.
WebSphere InterChange Server needs to know the location of the Attachment data handler, so that it can load it at run-time. To specify the location of the Attachment data handler, take the following steps:
Add the jar file for the Attachment data handler, bcgwbiattachmentdh.jar, to the list of jar files included at ICS startup.
Configuring the Attachment data handler consists of the following steps to create the configuration business objects:
To configure the Attachment data handler, you must create a child meta-object to provide the class name and configuration properties that the Attachment data handler needs. To create this meta-object, you create a business object definition that contains the attributes listed in Table 39. Use Business Object Designer, which is part of the WebSphere Business Integration Toolset, to create this business object definition
The child meta-object provides the class name and configuration properties that the Attachment data handler needs. In the Business Object Designer tool, create a child meta-object that includes MIME types for the payload and for the types of attachments you expect to receive.
The attributes of the child meta-object are shown in Table 39. An example of a child meta-object for the Attachment data handler is shown in Figure 6.
Table 39. Configuration properties in the Attachment child meta-object
Attribute Name | Description |
---|---|
ClassName |
Class name (required), which points to the following data handler class: com.ibm.bcg.DataHandlers.AttachmentDataHandler |
ContentTypeMap_x |
The content-type map for the payload and for each type of attachment you expect to receive in the XML wrapper. For more information, see Content-type maps.
|
PayloadDataHandlerMimeType | MIME type used to identify the default data handler, which processes a payload that does not have associated attachments. |
The content-type map determines the data handler that the Attachment data handler calls to convert information formatted in the associated content type. For example, if the content type of the payload is application/xml, the Attachment data handler looks for a content-type map whose ContentType attribute contains the value application/xml. If no matching content type can be found, the data handler assumes that it should not convert the associated attachment to a business object.
You would create a content-type map for each of these content types, with the attribute-level application-specific information as shown in Table 41.
When you create an attribute in the child meta-object that represents a content-type map, keep the following in mind:
ContentTypeMap_x
where x is an integer that uniquely identifies the content-type map within the business object definition.
Table 40 lists the tags that the default value for this attribute can
contain.
Table 40. Valid tags for default value of content-type-map attribute
Tag name | Description | Required? |
---|---|---|
ContentType |
Actual content type that comes in the transport envelope (for example,
text/xml).
| Yes |
MimeType |
MIME type used to identify the data handler to convert the associated
content type to a business object. If you do not specify
MimeType, the data handler uses the value of ContentType
to instantiate the data handler.
| No |
CharSet |
Name of a character set (for example, UTF-8) that the Attachment data handler uses to convert bytes to a string or a string to bytes. If you do not specify CharSet, the Attachment data handler takes the following actions:
| No |
ConvertAttachment |
Boolean value to indicate whether the attachment should be converted to a
business object. The default is false.
| No |
The content-type map can also specify the character set for encoding as well as whether an attachment should be converted to a business object. For a description of the child meta-object attributes and an example, see Creating the Attachment child meta-object.
For example, suppose you have the following content types in your document:
Table 41. Sample content-type maps
Content type | Attribute name | Default value |
---|---|---|
text/xml | ContentType_1 | ContentType=text/xml;MimeType=myxml; CharSet=UTF-8;ConvertAttachment=false; |
application/xml | ContentType_2 | ContentType=application/xml; MimeType=mynewxml;CharSet=UTF-16; ConvertAttachment=true; |
application/octet-stream | ContentType_3 | ContentType=application/octet-stream; MimeType=myoctet |
Business Integration Connect provides the following InterChange Server repository input file, which contains a sample child meta-object for the Attachment data handler:
ProductDir/Integration/WBI/WICS/Attachment/ MO_DataHandler_DefaultAttachmentConfig.in
where ProductDir is the directory of your installed Business Integration Connect product. This repository file defines a single Attachment data handler whose MIME type is wbic_attachment and whose associated child meta-object is MO_DataHandler_DefaultAttachmentConfig. Figure 6 shows the sample child meta-object for the Attachment data handler. This meta-object defines two content-type maps, ContentTypeMap_1 and ContentTypeMap_2.
Figure 6. Sample child meta-object for the Attachment data handler
A WebSphere Business Integration Adapter (such as the Adapter for JMS) uses the MO_DataHandler_Default meta-object to identify the data handlers it can use. WebSphere Server Access uses the MO_Server_DataHandler meta-object for the same purpose. Add a reference to the Attachment data handler in one of these meta-objects.
To associate MIME types that documents contain with the data handlers that
provide support for these MIME types, an ICS-compatible component refers to a
top-level data-handler meta-object. Table 42 summarizes the names of the top-level meta-object, depending
on the component that needs access to a data handler.
Table 42. Top-level data-handler meta-objects for InterChange Server
To the MO_Server_DataHandler or MO_DataHandler_Default meta-object, you make the following modifications:
The attribute type of this attribute is the business object definition for the Attachment data handler's child meta-object (see Creating the Attachment child meta-object).
The attribute type of these attributes would be the child meta-object of the associated data handler.
For example, suppose you have the Attachment data handler as configured in Figure 6.. Figure 7 shows the MO_DataHandler_Default meta-object with an attribute that associates the wbic_attachment MIME type with the instance of the Attachment data handler that is configured by the MO_DataHandler_DefaultAttachmentConfig child meta-object. This top-level data-handler meta-object also associates the document MIME type (text/xml) with the XML data handler's child meta-object.
Figure 7. Associating the wbic_attachment MIME type with the Attachment data handler
For each unique combination of supported content types that you need to support, repeat the process by adding an attribute in the appropriate top-level data-handler meta-object, whose attribute name is the MIME type associated with the Attachment data handler instance and whose type is the name of the associated child meta-object. Also ensure that the configured MIME types (and their child meta-objects) exist in the top-level meta-object.
If you are sending or receiving documents that are wrapped in an XML transport envelope, your payload business object needs to contain attachment information. In any document flow, there is one payload and, optionally, multiple attachments. The Attachment data handler expects this attachment information to be in attachment-related business objects. Therefore, you must create business object definitions to represent this information. A business object definition is the form of information that InterChange Server uses. You use the Business Object Designer tool to create business object definitions.
Figure 8 shows the business-object structure for a payload that is wrapped in an XML transport envelope.
Figure 8. Relationship of the payload business object to the attachment business objects
As Figure 8 shows, all the attachments are contained in the attachment-container business object. If there are attachments, the payload business object has an attribute that corresponds to the attachment-container business object
Make sure your business-object structure includes attachment-required business objects by taking the following steps:
Each of these steps is described in the sections below.
To store the content type and encoding of the associated payload or
attachment, you create the content-information business
object. To create a content-information business object
definition, create the attributes shown in Table 43.
Table 43. Attributes of the content-information business object
Attribute | Attribute type | Description | Is key attribute? |
---|---|---|---|
contentType | String |
The content type for the associated payload or attachment.
| Yes |
encoding | String | The character encoding for the associated payload or attachment | No |
In Figure 8, the contentInfo_BusObj business object definition contains attributes for the content type and encoding of the attachment. These attributes all have attribute-level application-specific information to specify the name of the related protocol header. For example, the x-aux-sender-id attribute has the application-specific information set as follows:
name=x-aux-sender-id
You can choose whatever name you want to identify the content-information business object definition. The application-specific information of the attachment business object determines if this is a Content Type Encoding business object type. Figure 8 shows an example of a content-type-encoding business object definition called contentType_BusObj.
For attachment data that is not to be converted into a business object, you create the default attachment business object. This business object is useful for containing base64-encoded data that comes from the transport envelope.
To create a default-attachment business object definition, take the following steps:
This cw_mo_bcg_content_info tag has the following format:
cw_mo_bcg_content_info=contentInfoAttr
where contentInfoAttr is the name of the attribute that contains the attachment-container business object.
Table 44. Attributes of the default attachment business object
Attribute | Attribute type | Description | Is key attribute? |
---|---|---|---|
attachment | String |
The piece of attachment data.
| Yes |
An attribute to hold the content information
| Business object |
An optional attribute to hold the content -information business object, which provides the content type and encoding for the attachment data. This attribute should have single cardinality.
For more information on the format of the content-information business object, see Representing the content information. | No |
In Figure 8, the defaultAttach_BusObj business object definition contains attributes for the piece of attachment data, including a content-information business object to hold its content type and encoding. The piece of attachment data that this default attachment business object represents does have a content-type encoding, represented by contentType_attach attribute. Therefore, the default attachment business object definition includes the following tag in its business-object-level application-specific information:
cw_mo_bcg_content_info=contentType_attach
For each kind of attachment in your document that converts to a business object, you must create a separate attachment business object definition. The attachment business object definition represents the actual data in a document attachment. To create an attachment business object definition, take the following steps:
Possible attribute types can include String (for simple pieces of data) or a business object definition (for complex data).
The attribute type for this attribute is the content-type-encoding business object definition (see Representing the content information).
This cw_mo_bcg_content_info tag has the following format:
cw_mo_bcg_content_info=contentTypeEncodingAttr
where contentTypeEncodingAttr is the name of the attribute that contains the content-type-encoding business object.
In Figure 8, the payload document has one attachment, represented by the attachment1_BusObj business object definition. This attachment does have a content-type encoding, represented by contentTypeEncoding attribute. Therefore, the attachment business object definition includes the following tag in its business-object-level application-specific information:
cw_mo_bcg_content_info=contentTypeEncoding
The attachment container contains all document attachments in the transport envelope. To represent the attachment container for InterChange Server, you create the attachment-container business object. Each attribute in the attachment-container business object represents one attachment.
To create the attachment-container business object definition, take the following steps:
The attribute type for each of these attributes is the associated attachment business object (see Representing the attachments). Each attribute should have multiple cardinality.
The wbic_type tag has the following format:
wbic_type=Attachment
The attribute type for this attribute is the default attachment business object (see Representing attachment data). It is the key attribute for the attachment-container business object. This attribute does not require the wbic_type tag in its application-specific information.
This cw_mo_bcg_default_attribute tag has the following format:
cw_mo_bcg_content_info=defaultAttachmentAttr
where defaultAttachmentAttr is the name of the attribute that contains the default attachment business object.
In Figure 8, the attachment container is represented by the attachContainer_BusObj business object definition. This attachment-container business object definition has the following attributes:
wbic_type=Attachment
This attachment is represented by the attachment1_BusObj business object definition.
cw_mo_bcg_default_attribute=defaultAttach
The payload business object definition represents the information in your document. It contains an attribute for each piece of information you are transferring between Business Integration Connect and InterChange Server. For information on the creation of the payload business object definition, see Business object for the document.
If you are sending or receiving documents that contain attachments, your payload business object needs to contain attachment information. In any document flow, there is one payload and, optionally, multiple attachments. If the payload of your document contains attachments, you must modify the payload business object definition as follows:
You might find it easier to use if your actual payload data is stored in a separate payload business object definition. In this case, the top-level payload business object contains an attribute for the payload data whose attribute type is the business object definition of actual payload data.
The attribute type of this attribute is the attachment-container business object definition (see Representing the attachment container). This attribute should have single cardinality.
This cw_mo_bcg_attachment tag has the following format:
cw_mo_bcg_attachment=attachContainerAttr
where attachContainerAttr is the name of the attribute that contains the attachment-container business object.
This cw_mo_bcg_content_info tag has the following format:
cw_mo_bcg_attachment=contentInfoAttr
where contentInfoAttr is the name of the attribute that contains the content-information business object. For more information on the format of the content-information business object, see Representing the content information.
For example, if you are using the JMS transport protocol, your payload business object definition must contain the JMS dynamic business object. For more information, see the section on how to create business object definitions in support of your transport protocol.