Meta-object attributes configuration

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.

Static meta-object

The JMS configuration static meta-object contains a list of conversion properties defined for different business objects. To define the conversion properties for a business object, create a string attribute and name it using the syntax BusObj_Verb. For example, to define the conversion properties for a Customer object with the verb Create, create an attribute named Customer_Create. In the application-specific information of the attribute, specify the actual conversion properties.

Additionally, a reserved attribute named Default can be defined in the meta-object. When this attribute is present, its properties act as default values for all business object conversion properties.

Note:
If a static meta object is not specified, the connector is unable to map a given message format to a specific business object type during polling. When this is the case, the connector passes the message text to the configured data handler without specifying a business object. If the data handler cannot create a business object based on the text alone, the connector reports an error indicating that this message format is unrecognized.

Table 13 describes the static meta-object properties.

Table 13. JMS static meta-object properties
Property name Description
DataHandlerConfigMO
 
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. If defined in a dynamic child meta-object, this property will override the connector property and the static meta-object property. 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.
DataHandlerMimeType
 
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. If defined in a dynamic child meta-object, this property will override the connector property and the static meta-object property. 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.
InputFormat
 
The InputFormat is the message format to associate with the given business object. When a message is retrieved and is in this format, it is converted to the given business object if possible. Do not set this property using default conversion properties; its value is used to match incoming messages to business objects.
OutputFormat
 
The OutputFormat is set on messages created from the given business object. If the OutputFormat is not specified, the input format is used, if available. An OutputFormat defined in a dynamic child meta-object overrides the value defined in the static meta-object.
InputQueue The input queue that the connector polls to detect new messages. You can use connector-specific properties to configure multiple InputQueues and optionally map different data handlers to each queue. Do not set this property using default conversion properties; its value is used to match incoming messages to business objects.
OutputQueue
 
The OutputQueue is the output queue to which messages derived from the given business object are delivered. An OutputQueue defined in a dynamic child meta-object overrides the value defined in the static meta-object.
ResponseTimeout
 
Indicates the length of time in milliseconds to wait before timing out when waiting for a response. The connector returns SUCCESS immediately without waiting for a response if this is left undefined or with a value less than zero. A ResponseTimeout defined in a dynamic child meta-object overrides the value defined in the static meta-object.
TimeoutFatal
 
If this property is defined and has a value of True, the connector returns APP_RESPONSE_TIMEOUT when a response is not received within the time specified by ResponseTimeout. All other threads waiting for response messages immediately return APP_RESPONSE_TIMEOUT to InterChange Server. This causes InterChange Server to terminate the connector. A TimeoutFatal defined in a dynamic child meta-object overrides the value defined in the static meta-object.


Table 14. JMS static meta-object structure for Customer_Create
Attribute name Application-specific text
Customer_Create
 
OutputFormat=CUST_OUT;
  
 OutputQueue=QueueA;
  
 ResponseTimeout=10000;
  
 TimeoutFatal=False
 

Application-specific information

The application-specific information is structured in name-value pair format, separated by semicolons. For example:

InputFormat=CUST_IN;OutputFormat=CUST_OUT
 

Mapping data handlers to InputQueues

You can use the InputQueue property in the application-specific information of the static meta-object to associate a data handler with an input queue. This feature is useful when dealing with multiple trading partners who have different formats and conversion requirements. To do so you must:

  1. Use connector-specific properties (see InputQueue) to configure one or more input queues.
  2. For each input queue, specify the queue manager and input queue 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 InputQueue named CompReceipts:

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

Overloading input formats

When retrieving a message, the connector normally matches the input format to one specific business object and verb combination. The connector then passes the business object name and the contents of the message to the data handler. This allows the data handler to verify that the message contents correspond to the business object that the user expects.

If, however, the same input format is defined for more than one business object, the connector will be unable to determine which business object the data represents before passing it to the data handler. In such cases, the connector passes the message contents only to the data handler and then looks up conversion properties based on the business object that is generated. Accordingly, the data handler must determine the business object based on the message content alone.

If the verb on the generated business object is not set, the connector searches for conversion properties defined for this business object with any verb. If only one set of conversion properties is found, the connector assigns the specified verb. If more properties are found, the connector fails the message because it is unable to distinguish among the verbs.

A sample meta-object

The static meta-object shown below configures the connector to convert Customer business objects using verbs create, update, delete, and retrieve. Note that attribute Default is defined in the meta-object. The connector uses the conversion properties of this attribute:

OutputQueue=CustomerQueue1;ResponseTimeout=5000;TimeoutFatal=true 
 

as default values for all other conversion properties. Thus, unless specified otherwise by an attribute or overridden by a dynamic child meta-object value, the connector will issue all business objects to queue CustomerQueue1 and then wait for a response message. If a response does not arrive within 5000 milliseconds, the connector terminates immediately.

Customer object with verb create

Attribute Customer_Create indicates to the connector that any messages of format NEW should be converted to a Customer business object with the verb create. Since an output format is not defined, the connector will send messages representing this object-verb combination using the format defined for input (in this case NEW).

Customer object with verbs update and delete

Input format MODIFY is overloaded--defined for both business object customer with verb update and business object customer with verb delete. In order to successfully process retrieved messages of this format, the business object name and possibly the verb should be contained in the message content for the data handler to identify (see Overloading input formats). For request processing operations, the connector will send messages for either verb using the input format MODIFY since an output format is not defined.

Customer object with verb retrieve

Attribute Customer_Retrieve specifies that business objects of type customer with verb retrieve should be sent as messages with format retrieve. Note that the default response time has been overridden so that the connector will wait up 10000 milliseconds before timing out (it will still terminate if a response is not received).

[BusinessObjectDefinition]
 Name = Sample_MO
 Version = 1.0.0
  
 [Attribute]
 Name = Default
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = OutputQueue=CustomerQueue1;ResponseTimeout=5000;
 TimeoutFatal=true
 IsRequiredServerBound = false
 [End]
  
 [Attribute]
 Name = Customer_Create
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputFormat=NEW
 IsRequiredServerBound = false
 [End]
  
 [Attribute]
 Name = Customer_Update
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputFormat=MODIFY
 IsRequiredServerBound = false
 [End]
  
 [Attribute]
 Name = Customer_Delete
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputFormat=MODIFY
 IsRequiredServerBound = false
 [End]
  
 Attribute]
 Name = Customer_Retrieve
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = OutputFormat=RETRIEVE;ResponseTimeout=10000
 IsRequiredServerBound = false
 [End]
  
 [Attribute]
 Name = ObjectEventId
 Type = String
 MaxLength = 255
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
  
 [Verb]
 Name = Create
 [End]
  
 [Verb]
 Name = Delete
 [End]
  
 [Verb]
 Name = Retrieve
 [End]
  
 [Verb]
 Name = Update
 [End]
 [End]
 

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 metadata specified at run-time for each business object instance.

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.

Table 14 and Table 15 show sample static and dynamic child meta-objects, respectively, for business object Customer_Create. Note that the application-specific information consists of semi-colon delimited name-value pairs.

Table 15. JMS dynamic child meta-object structure for Customer_Create
Attribute name Value
DataHandlerMimeType1 text/delimited
OutputFormat CUST_OUT
OutputQueue QueueA
ResponseTimeout 10000
TimeoutFatal False
  1. Assumes that DataHandlerConfigMO has been specified in either the connector configuration properties or the static meta-object.

The connector checks the application-specific information of top-level business object received to determine whether tag cw_mo_conn specifies a child meta-object. If so, the dynamic child meta-object values override those specified in the static 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 16 shows how a dynamic child meta-object might be structured for polling.

Table 16. 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 16, you can define additional attributes, Input_Format and InputQueue, in a dynamic child meta-object. The Input_Format is populated with the format of the message retrieved, while the InputQueue attribute contains the name of the queue 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:

Sample dynamic child meta-object

[BusinessObjectDefinition]
 Name = MO_Sample_Config
 Version = 1.0.0
  
 [Attribute]
 Name = OutputFormat
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 DefaultValue = CUST
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = OutputQueue
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 DefaultValue = OUT
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = ResponseTimeout
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 DefaultValue = -1
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = TimeoutFatal
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 DefaultValue = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = InputFormat
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = InputQueue
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = ObjectEventId
 Type = String
 MaxLength = 255
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
  
 [Verb]
 Name = Create
 [End]
  
 [Verb]
 Name = Delete
 [End]
  
 [Verb]
 Name = Retrieve
 [End]
  
 [Verb]
 Name = Update
 [End]
 [End]
 [BusinessObjectDefinition]
 Name = Customer
 Version = 1.0.0
 AppSpecificInfo = cw_mo_conn=MyConfig
  
 [Attribute]
 Name = FirstName
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = LastName
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = Telephone
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = MyConfig
 Type = MO_Sample_Config
 ContainedObjectVersion = 1.0.0
 Relationship = Containment
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = ObjectEventId
 Type = String
 MaxLength = 255
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
  
 [Verb]
 Name = Create
 [End]
  
 [Verb]
 Name = Delete
 [End]
  
 [Verb]
 Name = Retrieve
 [End]
  
 [Verb]
 Name = Update
 [End]
 [End]
 

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. Adding such attributes allows you to modify JMS properties, to control the ReplyToQueue on a per-request basis (rather than using the default ReplyToQueue specified in the adapter properties), and to re-target a message CorrelationID. This section describes these attributes and how they affect event notification and request processing in both synchronous and asynchronous modes.

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

Table 17. 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.

The interpretation and use of these attributes are described in the sections below.

Note:
None of the above attributes are required. You may add any attributes to the dynamic meta-object that relate to your business process.

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 table below shows application-specific information properties that you must define for attributes in the JMSProperties object.

Table 18. Application-specific information for JMS property attributes
Name Possible values Comments
Name Any valid JMS property name This is the name of the JMS property. 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, Int, Boolean, Float, Double, Long, Short 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.

The figure below 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 3. JMS properties attribute in a dynamic meta-object


Asynchronous event notification

If a dynamic meta-object with header attributes is present in the event business object, the connector performs the following steps (in addition to populating the meta-object with transport-related data):

  1. Populates the CorrelationId attribute of the meta-object with the value specified in the JMSCorrelationID header field of the message.
  2. Populates the ReplyToQueue attribute of the meta-object with the queue specified in the JMSReplyTo header field of the message. Since this header field is represented by a Java object in the message, the attribute is populated with the name of the queue (often a URI).
  3. Populates the DeliveryMode attribute of the meta-object with the value specified in the JMSDeliveryMode header field of the message.
  4. Populates the Priority attribute of the meta-object with the JMSPriority header field of the message.
  5. Populates the Destination attribute of the meta-object with the name of the JMSDestination header field of the message. Since the Destination is represented by an object, the attribute is populated with the name of the Destination object.
  6. Populates the Expiration attribute of the meta-object with the value of the JMSExpiration header field of the message.
  7. Populates the MessageID attribute of the meta-object with the value of the JMSMessageID header field of the message.
  8. Populates the Redelivered attribute of the meta-object with the value of the JMSRedelivered header field of the message.
  9. Populates the TimeStamp attribute of the meta-object with the value of the JMSTimeStamp header field of the message.
  10. Populates the Type attribute of the meta-object with the value of the JMSType header field of the message.
  11. Populates the UserID attribute of the meta-object with the value of the JMSXUserID property field of the message.
  12. Populates the AppID attribute of the meta-object with the value of the JMSXAppID property field of the message.
  13. Populates the DeliveryCount attribute of the meta-object with the value of the JMSXDeliveryCount property field of the message.
  14. Populates the GroupID attribute of the meta-object with the value of the JMSXGroupID property field of the message.
  15. Populates the GroupSeq attribute of the meta-object with the value of the JMSXGroupSeq property field of the message.
  16. Examines the object defined for the JMSProperties attribute of the meta-object. The adapter populates each attribute of this object with the value of the corresponding property in the message. If a specific property is undefined in the message, the adapter sets the value of the attribute to CxBlank.

Synchronous event notification

For synchronous event processing, the adapter posts an event and waits for a response from the integration broker before sending a response message back to the application. Any changes to the business data are reflected in the response message returned. Before posting the event, the adapter populates the dynamic meta-object just as described for asynchronous event notification. The values set in the dynamic meta-object are reflected in the response-issued header as described below (all other read-only header attributes in the dynamic meta-object are ignored.):

Asynchronous request processing

The connector uses the dynamic meta-object, if present, to populate the request message prior to issuing it. The connector performs the following steps before sending a request message:

  1. If attribute CorrelationID is present in the dynamic meta-object, the connector sets the CorrelationID of the outbound request message to this value.
  2. If attribute ReplyToQueue is specified in the dynamic meta-object, the connector passes this queue via the request message and waits on this queue for a response. This allows you to override the ReplyToQueuevalue specified in the connector configuration properties. If you additionally specify a negative ResponseTimeout (meaning that the connector should not wait for a response), theReplyToQueue is set in the response message, even though the connector does not actually wait for a response.
  3. If attribute DeliveryMode is set to 2, the message is sent persistently. If DeliveryMode is set to 1, the message is not sent persistently. Any other value may fail the connector. If DeliveryMode is not specified in the MO, then the JMS provider establishes the persistence setting.
  4. If attribute Priority is specified, the connector sets the value in the outgoing request. The Priority attribute can take values 0 through 9; any other value may cause the connector to terminate.
  5. If attribute JMSProperties is specified in the dynamic meta-object, the corresponding JMS properties specified in the child dynamic meta-object are set in the outbound message sent by the connector.

Note:
If header attributes in the dynamic meta-object are undefined or specify CxIgnore, the connector follows its default settings.

Synchronous request processing

The connector uses the dynamic meta-object, if present, to populate the request message prior to issuing it. If the dynamic meta-object contains header attributes, the connector populates it with corresponding new values found in the response message. The connector performs the following steps (in addition to populating the meta-object with transport-related data) after receiving a response message:

  1. If attribute CorrelationID is present in the dynamic meta-object, the adapter updates this attribute with the JMSCorrelationID specified in the response message.
  2. If attribute ReplyToQueue is defined in the dynamic meta-object, the adapter updates this attribute with the name of the JMSReplyTo specified in the response message.
  3. If attribute DeliveryMode is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSDeliveryMode header field of the message.
  4. If attribute Priority is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSPriority header field of the message.
  5. If attribute Destination is defined in the dynamic meta-object, the adapter updates this attribute with the name of the JMSDestination specified in the response message.
  6. If attribute Expiration is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSExpiration header field of the message.
  7. If attribute MessageID is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSMessageID header field of the message.
  8. If attribute Redelivered is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSRedelivered header field of the message.
  9. If attribute TimeStamp is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSTimeStamp header field of the message.
  10. If attribute Type is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSType header field of the message.
  11. If attribute UserID is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSXUserID header field of the message.
  12. If attribute AppID is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSXAppID property field of the message.
  13. If attribute DeliveryCount is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSXDeliveryCount header field of the message.
  14. If attribute GroupID is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSXGroupID header field of the message.
  15. If attribute GroupSeq is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSXGroupSeq header field of the message.
  16. If attribute JMSProperties is defined in the dynamic meta-object, the adapter updates any properties defined in the child object with the values found in the response message. If a property defined in the child object does not exist in the message, the value is set to CxBlank.

Note:
Using the dynamic meta-object to change the CorrelationID set in the request message does not affect the way the adapter identifies the response message--the adapter by default expects that the CorrelationID of any response message equals the message ID of the request sent by the adapter.

Error handling

If a JMS property cannot be read from or written to a message, the connector logs an error and the request or event fails. If a user-specified ReplyToQueue does not exist or cannot be accessed, the connector logs an error and the request fails. If a CorrelationID is invalid or cannot be set, the connector logs an error and the request fails. In all cases, the message logged is from the connector message file.

Copyright IBM Corp. 2003, 2004