WebSphere Partner Gateway provides the Attachment data handler to process documents that are sent between WebSphere Partner Gateway 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, WebSphere Partner Gateway 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 page. For more information, see Payload.
When a document contains attachments, WebSphere Partner Gateway 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 is called from a WebSphere Business Integration adapter.
When the adapter 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 22 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 adapter 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 23 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 the XML transport envelope and handle the conversion between the contained data and the corresponding business-object representation, as follows:
Before WebSphere Partner Gateway sends a document to InterChange Server, it must determine whether to wrap the contents in an XML transport envelope. If WebSphere Partner Gateway creates the transport envelope, the payload and any attachments are Base64-encoded. WebSphere Partner Gateway then sends the XML transport envelope to the appropriate adapter with the appropriate transport-level headers. This adapter 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 How documents without a transport envelope are processed.
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 How documents in a transport envelope are processed.
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.
How documents in a transport envelope are processedIf 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 contained in an <attachment> XML tag.
The Attachment data handler uses 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.
The Attachment data handler examines the business-object-level application-specific information of the payload 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. It then creates an instance of this content-information business object and sets the values for the payload content type and encoding.
The Attachment data handler examines the business-object-level application-specific information of the payload business object and determines the name of the attachment-container business object, whose attribute name is specified by the cw_mo_bcg_attachment tag. It then creates an instance of the attachment-container business object and saves 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.
The Attachment data handler examines the business-object-level application-specific information of the attachment-container business object and determines the name of the default attachment business object, whose attribute name is specified by the cw_mo_bcg_default_attribute tag. It then creates an instance of the default attachment business object and saves it in the appropriate attribute of the attachment-container business object.
The Attachment data handler examines the content type and character-set encoding from the attachment and checks 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 WebSphere Partner Gateway receives a document from InterChange Server, an adapter 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 data handler, which handles the actual conversion. This 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 How documents without a transport envelope are created.
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 How documents with a transport envelope are created.
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.
How documents with a transport envelope are createdIf 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.
The Attachment data handler uses 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.
The Attachment data handler uses 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 WebSphere Partner Gateway-supplied Attachment data handler involves the following steps:
You have the option of using the default schema for the Attachment data handler or using a schema (wbipackaging_v1.1_ns.xsd) that lets you pass the contentId in the Backend Integration packaging.
To use the wbipackaging_v1.1_ns.xsd schema, configure the wbipackaging_version property in the bcg.properties file. (The bcg.properties file is described in the Administrator Guide.) This property is specified as:
wbipackaging_version=1.n
where n is 0 or 1. The default value of this property is 1.0.
The meta-object of the Attachment data handler has a wbipackaging_version attribute, which can have a value of 1.0 or 1.1. If you specify 1.1, the Attachment data handler parses and generates the XML messages containing the contentId of the attachment.
To specify the content ID of the attachment, the encoding business object uses the contentId attribute. When the Attachment Data Handler generates the XML from the business object, it uses this attribute to create the contentId tag for the attachment. When the Attachment Data Handler generates the business object from the XML, it sets this attribute, using the value specified in the contentId tag in the XML message.
The Attachment data handler and associated repository file are available on the WebSphere Partner Gateway installation medium, in the locations listed in Table 35.
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:
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 36. 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 36. An example of a child meta-object for the Attachment data handler is shown in Figure 15.
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. |
wbipackaging_version | This attribute can have a value of 1.0 or 1.1. If you specify 1.1, the Attachment data handler parses and generates the XML messages containing the contentId of the attachment. |
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 38.
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 37 lists the tags that the default value for this attribute can contain.
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:
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 |
WebSphere Partner Gateway provides the following InterChange Server repository input files, which contains a sample child meta-object for the Attachment data handler:
ProductDir/Integration/WBI/WICS/Attachment/
MO_DataHandler_DefaultAttachmentConfigV1.0.in
ProductDir/Integration/WBI/WICS/Attachment/
MO_DataHandler_DefaultAttachmentConfigV1.1.in
where ProductDir is the directory of your installed WebSphere Partner Gateway product. The repository files define a single Attachment data handler whose associated child meta-object is MO_DataHandler_DefaultAttachmentConfig. Figure 15 shows the sample child meta-object for the Attachment data handler. This meta-object defines two content-type maps, ContentTypeMap_1 and ContentTypeMap_2.
MO_DataHandler_DefaultAttachmentConfigV1.1.in contains the additional attribute:
[Attribute] Name = WBIPackaging_Version Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = true DefaultValue = 1.0 IsRequiredServerBound = false [End]
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. Add a reference to the Attachment data handler in the meta-object.
To the 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 15. Figure 16 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.
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 17 shows the business-object structure for a payload that is wrapped in an XML transport envelope.
As Figure 17 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 39.
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 17, 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 17 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.
Attribute | Attribute type | Description | Is key attribute? |
---|---|---|---|
attachment | String |
The piece of attachment data.
Note: This attribute is the key attribute of the business
object definition. |
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.
Note: If this attribute does not exist,
the Attachment data handler does not set the attachment data in
the business object.
For more information on the format of the content-information business object, see Representing the content information. |
No |
In Figure 17, 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 the 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 17, 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 17, 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 WebSphere Partner Gateway 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.