Configuring meta-objects

The connector for JMS can recognize and read two kinds of meta-objects:

The attribute values of the dynamic child meta-object duplicate and override those of the static meta-object. For an overview of metadata and static versus dynamic meta-objects, see Metadata and meta-objects.

When deciding upon which meta-object will work best for your implementation, consider the following:

Meta-object properties

Table 10 provides a complete list of properties supported in meta-objects. Refer to these properties when implementing meta-objects.

Not all properties are available in both objects. Nor are all properties are readable from or writable to the message header. See the appropriate sections on event and request processing in Adapter for JMS overview, to determine how a specific property is interpreted and used by the connector.

Table 10. JMS meta-object properties
Property name Definable in static meta-object Definable in dynamic meta-object Description
DataHandlerConfigMO
Yes Yes Meta-object passed to data handler to provide configuration information. If specified in the static meta-object, this will override the value specified in the DataHandlerConfigMO connector property. Use this static meta-object property when different data handlers are required for processing different business object types. Use the dynamic child meta-object for request processing when the data format may be dependent on the actual business data. The specified business object must be supported by the connector agent. See the description in Configuring connector-specific properties.
DataHandlerMimeType
Yes Yes Allows you to request a data handler based on a particular MIME type. If specified in the static meta-object, this will override the value specified in the DataHandlerMimeType connector property.
Use this static meta-object property when different data handlers are required for processing different business object types. Use the dynamic child meta-object for request processing when the data format might be dependent on the actual business data. The business object specified in DataHandlerConfigMO should have an attribute that corresponds to the value of this property. See the description in Configuring connector-specific properties.
DataHandlerClassName
Yes Yes See the description in Configuring connector-specific properties.
InputFormat
Yes Yes Format or type of inbound (event) messages. This value assists in identifying the content of the message and would be specified by the application that generated the message. The field that the connector considers as defining the format in the message can be user-defined via the connector-specific property MessageFormatProperty.
OutputFormat
Yes Yes Format to be populated in outbound messages. If the OutputFormat is not specified, the input format is used, if available.
InputDestination Yes Yes This property is used to match incoming messages to business objects only. By contrast, the InputDestination connector-specific property defines which destinations the adapter polls and is the only property that the adapter uses to determine which destinations to poll. In the MO, the InputDestination property and the InputFormat property can serve as criteria for the adapter to map a given message to a specific business object. To implement this feature, you would use connector-specific properties to configure multiple input destinations and optionally map different data handlers to each one based on the input formats of incoming messages.

Do not set this property using default conversion properties; its value is used
OutputDestination
Yes Yes Destination to which the outbound message is written.
ResponseTimeout
Yes Yes Indicates the length of time in milliseconds to wait before timing out when waiting for a response in synchronous request processing. The connector returns SUCCESS immediately without waiting for a response if this is left undefined or with a value less than zero.
DataEncoding Yes Yes

DataEncoding refers to whether message data is dealt with by the adapter as text, binary, or object type. If this property is not specified in the static meta-object, the connector tries to read the messages without using any specific encoding. DataEncoding defined in a dynamic child meta-object overrides the value defined in the static meta-object. The default value is Text. The format for the value of this attribute is messageType[:enc]. I.e., Text:ISO8859_1, Text:UnicodeLittle, Text, Object, or Binary. This property is related internally to the InputFormat property: specify one and only one DataEncoding per InputFormat.
For more information about DataEncoding, see DataEncoding.

Below are fields mapping specifically to the JMS message header. For specific explanations, interpretation of values, and more, see the JMS API specification. JMS providers may interpret some fields differently so also check your JMS provider documentation for any deviations.
ReplyToDestination Yes Destination to which a response message for a request is to be sent.
Type Yes Type of message. Generally user-definable, depending on JMS provider.
MessageID Yes Unique ID for message (JMS provider specific).
CorrelationID Yes Yes Used in response messages to indicate the ID of the request message that initiated this response.
Delivery Mode Yes Yes Specifies whether the message is persisted or not in the MOM system. Acceptable values:
1=non-persistent
2=persistent
Other values, depending on the JMS provider, may be available.
Priority Yes Numeric priority of message. Acceptable values: 0 through 9 inclusive (low to high priority).
Destination Yes Current or last (if removed) location of message in MOM system.
Expiration Yes Time-to-live of message.
Redelivered Yes Indicates that the JMS provider most likely attempted to deliver the message to the client earlier but receipt was not acknowledged.
Timestamp Yes Time message was handed off to JMS provider.
UserID Yes Identity of the user sending the message.
AppID Yes Identity of the application sending the message.
DeliveryCount Yes Number of delivery attempts.
GroupID Yes Identity of the message group.
GroupSeq Yes Sequence of this message in the message group specified in GroupID.
JMSProperties Yes See JMS properties.

DataEncoding

The JMS standard defines different types of messages for storing different types of data. For example, a text message could contain an XML document, while binary data might contain an image. Explicitly specifying the expected data encoding through the meta-object property DataEncoding helps the adapter understand what types of messages it should be expecting and how to process them.

By default, the adapter assumes that all messages are text. However, the adapter for JMS supports text, binary, and Java object type messages. During request processing, the adapter uses the configured data handler to convert the request business object to text, which it then delivers as a text message. During event notification, the adapter retrieves the text from a text message and passes it to the data handler to create the event business object. If the adapter receives a binary message, it converts the binary body to text using the default encoding of the JVM before passing the content to the data handler.

In some cases, these scenarios are not appropriate. If you want to process binary messages and your data handler is designed for binary data, you must use the DataEncoding property. This property accepts one of three possible values:

When possible, it is always recommended that you send text data in JMS text messages rather than have the adapter handle the conversion from text to binary (or vice-versa). This is because incorrect encoding can cause subtle data corruption that is difficult to detect or diagnose. However, it is possible to specify how you would like the adapter to encode the conversion between binary and text (or vice-versa) using an additional modifier provided in the DataEncoding property. If you append a colon and the name of a supported Java encoding, the adapter will use the specified encoding to convert. The format is text:encoding.

For example, DataEncoding=text;ISO8859_1 informs the adapter that if any binary messages are received, it should convert the binary message body to text using encoding ISO8859_1 before passing it to the data handler. If the message type matches the data encoding (for example, if the binary message and data encoding specifies binary or text message and the data encoding specifies text), this value will have no impact.

Data handler design for binary data

If you plan to design and use a custom data handler with the adapter, consider the following:

Configuring a static meta-object

The JMS configuration static meta-object contains a list of conversion properties defined for different business objects. To view a sample static meta-object, launch Business Object Designer and open the following sample that is shipped with the adapter: connectors\JMS\Samples\Sample_JMS_MO_Config.xsd.

The connector supports at most one static meta-object at any given time. You implement a static meta-object by specifying its name for connector property ConfigurationMetaObject

The structure of the static meta-object is such that each attribute represents a single business object and verb combination and all the meta-data associated with processing that object. The name of each attribute should be the name of the business object type and verb separated by an underscore, such as Customer_Create. The attribute application-specific information should consist of one or more semicolon-delimited name-value pairs representing the meta-data properties you want to specify for this unique object-verb combination.

Table 11. Static meta-object structure
Attribute name Application-specific text
<business object type>_<verb>
    property=value;property=value;...
<business object type>_<verb>
    property=value;property=value;...

For example, consider the following meta-object:

Table 12. Sample static meta-object structure
Attribute name Application-specific information
Customer_Create
    OutputFormat=CUST;OutputDestination=QueueA
Customer_Update
OutputFormat=CUST;OutputDestination=QueueB
Order_Create
OutputFormat=ORDER;OutputDestination=QueueC

The meta-object in this sample informs the connector that when it receives a request business object of type Customer with verb Create, to convert it to a message with format CUST and then to place it in destination QueueA. If the customer object instead had verb Update, the message would be placed in QueueB. If the object type was Order and had verb Create, the connector would convert and deliver it with format ORDER to QueueC. Any other business object passed to the connector would be treated as unsubscribed.

Optionally, you may name one attribute Default and assign to it one or more properties in the ASI. For all attributes contained in the meta-object, the properties of the default attribute are combined with those of the specific object-verb attributes. This is useful when you have one or more properties to apply universally (regardless of object-verb combination). In the following example, the connector would consider object-verb combinations of Customer_Update and Order_Create as having OutputDestination=QueueA in addition to their individual meta-data properties:

Table 13. Sample static meta-object structure
Attribute name Application-specific information
Default
    OutputDestination=QueueA
Customer_Update
OutputFormat=CUST
Order_Create
OutputFormat=ORDER

See Table 10 in Meta-object propertiesdescribes the properties that you can specify as application-specific information in the static meta-object.

To implement a static meta-object:

  1. Launch Business Object Designer. For further information, see the Business Object Development Guide.
  2. Open the sample meta-object connectors\JMS\Samples\Sample_JMS_MO_Config.xsd.
    Figure 3. A sample static meta-object
  3. Edit the attributes and ASI to reflect your requirements, referring to Table 10 and then save the meta-object file.
  4. Specify the name of this meta-object file as the value of the connector property ConfigurationMetaObject.

Mapping data handlers to input destinations

You can use the InputDestination property in the application-specific information of the static meta-object to associate a data handler with an input destination. This feature is useful when dealing with multiple trading partners who have different formats and conversion requirements.

To map a data handler to an input destination:

  1. Launch Connector Configurator. For further information, see Appendix B. Connector Configurator.
  2. Use connector-specific properties (see InputDestination) to configure one or more input destination. Multiple destination names must be delimited by a semicolon.
  3. For each input destination, specify the destination (queue manager if you are implementing PTP messaging style) and input destination name as well as data handler class name and mime type in the application-specific information.

For example, the following attribute in a static meta-object associates a data handler with an InputDestination named CompReceipts:

[Attribute]
Name = Customer_Create
Type = String
Cardinality = 1
MaxLength = 1
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
InputDestination=//queue.manager/CompReceipts;DataHandlerClassName=com.crossworlds.
DataHandlers.MQ.disposition_notification;DataHandlerMimeType=message/
disposition_notification
IsRequiredServerBound = false
[End]

Configuring a dynamic child meta-object

If it is difficult or unfeasible to specify the necessary metadata through a static meta-object, the connector can optionally accept meta-data delivered at run-time for each business object instance.

Dynamic meta-objects allow you to change the meta-data used by the connector to process a business object on a per-request basis during request processing, and to retrieve information about an event message during event processing.

The structure of the dynamic meta-object is such that each attribute represents a single metadata property and value:meta-object property name =meta-object property value

To implement a dynamic meta-object, you add it as a child to your top-level object and include the name-value pair cw_mo_conn=<MO attribute> in your top-level object ASI where <MO attribute> is the name of the attribute in your top-level object representing the dynamic meta-object. For example:

Customer (ASI = cw_mo_conn=MetaData)
  |-- Id
  |-- FirstName
  |-- LastName
  |-- ContactInfo
  |-- MetaData
        |-- OutputFormat = CUST
        |-- OutputDestination = QueueA

Upon receipt of a request populated as shown above, the connector would convert the Customer object to a message with format CUST and then put the message in queue QueueA.

Business objects can use the same or different dynamic meta-object or none at all.

Note:
All standard IBM WebSphere data handlers are designed to ignore this dynamic meta-object attribute by recognizing the cw_mo_ tag. You must do the same when developing custom data handlers for use with the adapter.

The connector recognizes and reads conversion properties from a dynamic meta-object that is added as a child to the top-level business object passed to the connector. The attribute values of the dynamic child meta-object duplicate the conversion properties that you can specify via the static meta-object that is used to configure the connector.

Since dynamic child meta object properties override those found in static meta-objects, if you specify a dynamic child meta-object, you need not include a connector property that specifies the static meta-object. Accordingly, you can use a dynamic child meta-object independently of the static meta-object and vice-versa.

See Table 10 in Meta-object propertiesdescribes the properties that you can specify as application-specific information in the dynamic meta-object.

The following attributes, which reflect JMS header properties, are recognized in the dynamic meta-object.

Table 14. Dynamic meta-object header attributes
Header attribute name Mode Corresponding JMS header
CorrelationID
Read/Write JMSCorrelationID
ReplyToQueue
Read/Write JMSReplyTo
DeliveryMode
Read/Write JMSDeliveryMode
Priority
Read/Write JMSPriority
Destination
Read JMSDestination
Expiration
Read JMSExpiration
MessageID
Read JMSMessageID
Redelivered
Read JMSRedelivered
TimeStamp
Read JMSTimeStamp
Type
Read JMSType
UserID
Read JMSXUserID
AppID
Read JMSXAppID
DeliveryCount
Read JMSXDeliveryCount
GroupID
Read JMSXGroupID
GroupSeq
Read JMSXGroupSeq
JMSProperties
Read/Write

Read-only attributes are read from a message header during event notification and written to the dynamic meta-object. These properties also populate the dynamic MO when a response message is issued during request processing.Read/write attributes are set on message headers created during request processing. During event notification, read/write attributes are read from message headers to populate the dynamic meta-object.

To implement a dynamic meta-object:

  1. Launch Business Object Designer. For further information, see the Business Object Development Guide.
  2. Open the sample meta-object connectors\JMS\Samples\Sample_JMS_DynMO.xsd.
    Figure 4. A sample dynamic meta-object
  3. Edit the attributes and properties to reflect your requirements for this business object and save it.
  4. Add the dynamic meta-object as a child to your top-level object and include the name-value pair cw_mo_conn=<MO attribute> in your top-level object ASI where <MO attribute> is the name of the attribute in your top-level object representing the dynamic meta-object.

Population of the dynamic child meta-object during polling

In order to provide collaborations with more information regarding messages retrieved during polling, the connector populates specific attributes of the dynamic meta-object, if already defined for the business object created.

Table 15 shows how a dynamic child meta-object might be structured for polling.

Table 15. JMS dynamic child meta-object structure for polling
Attribute name Sample value
InputFormat
CUST_IN
InputQueue
MYInputQueue
OutputFormat
CxIgnore
OutputQueue
CxIgnore
ResponseTimeout
CxIgnore
TimeoutFatal
CxIgnore

As shown in Table 15, you can define additional attributes, Input_Format and Inputdestination, in a dynamic child meta-object. The Input_Format is populated with the format of the message retrieved, while the InputDestination attribute contains the name of the destination from which a given message has been retrieved. If these properties are not defined in the child meta-object, they will not be populated.

Example scenario:

JMS headers and dynamic child meta-object attributes

You can add attributes to a dynamic meta-object to gain more information about, and more control over, the message transport. This section describes these attributes and how they affect event notification and request processing.

JMS properties

Unlike other attributes in the dynamic meta-object, JMSProperties must define a single-cardinality child object. Every attribute in this child object must define a single property to be read/written in the variable portion of the JMS message header as follows:

  1. The name of the attribute has no semantic value.
  2. The type of the attribute should always be String regardless of the JMS property type.
  3. The application-specific information of the attribute must contain two name-value pairs defining the name and format of the JMS message property to which the attribute maps. The name is user-definable. The value type must be one of the following:

The table below shows application-specific information properties that you must define for attributes in the JMSProperties object.

Table 16. Application-specific information for JMS property attributes
Attribute Possible values ASI Comments
Name Any valid JMS property name (valid = compatible with type defined in ASI) name=<JMS property name>;type=<JMS property type> Some vendors reserve certain properties to provide extended functionality. In general, users should not define custom properties that begin with JMS unless they are seeking access to these vendor-specific features.
Type String type=<see comments> This is the type of the JMS property. The JMS API provides a number of methods for setting values in the JMS Message: setIntProperty, setLongProperty, setStringProperty, etc. The type of the JMS property specified here dictates which of these methods is used for setting the property value in the message.

In the example below, a JMSProperties child object is defined for the Customer object to allow access to the user-defined fields of the message header:

Customer (ASI = cw_mo_conn=MetaData)
  |-- Id
  |-- FirstName
  |-- LastName
  |-- ContactInfo
  |-- MetaData
        |-- OutputFormat = CUST
        |-- OutputDestination = QueueA
        |-- JMSProperties
             |-- RoutingCode = 123 (ASI= name=RoutingCode;type=Int)
             |-- Dept = FD (ASI= name=RoutingDept;type=String)

To illustrate another example, Figure 5 shows attribute JMSProperties in the dynamic meta-object and definitions for four properties in the JMS message header: ID, GID, RESPONSE and RESPONSE_PERSIST. The application-specific information of the attributes defines the name and type of each. For example, attribute ID maps to JMS property ID of type String).

Figure 5. JMS properties attribute in a dynamic meta-object

Copyright IBM Corporation 2003, 2005. All Rights Reserved.