The connector uses meta-object entries to determine which business object to associate with a message. The type of business object and verb used in processing an event message is based on the FORMAT field contained in the WebSphere MQ message header. You construct a meta-object attribute to store the business object name and verb to associate with the WebSphere MQ message header FORMAT field text. Meta-object attributes also contain message processing guidelines.
When a message is retrieved from the input queue, the connector looks up the business object name associated with the FORMAT text field. The message, along with the business object name, is then passed to the data handler. If a business object is successfully populated with message content, the connector checks to see if it is subscribed, and then delivers it to the integration broker using the gotApplEvents() method.
The connector 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.
When deciding upon which meta-object will work best for your implementation, consider the following:
Table 44 provides a complete list of properties supported in meta-objects. Refer to these properties when implementing meta-objects. Your meta object should have one or more of the properties shown in Table 44.
Not all properties are available in both static and dynamic meta-objects. Nor are all properties are readable from or writable to the message header. See the appropriate sections on event and request processing to determine how a specific property is interpreted and used by the connector.
Table 44. WebSphere MQ adapter meta-object properties
Property name | Definable in static meta-object | Definable in dynamic meta-object | Description |
---|---|---|---|
CollaborationName | Yes | Yes | The CollaborationName must be specified in the application
specific text of the attribute for the business object/verb
combination. For example, if a user expects to handle synchronous event
delivery for the business object Customer with the Create verb, the static
metadata object must contain an attribute named
Customer_Create.
The Customer_Create attribute must contain application specific text that includes a name-value pair. For example, CollaborationName=MyCustomerProcessingCollab. See the Overview of creating static meta-objects section for syntax details. Failure to do this will result in run-time errors when the connector attempts to synchronously process a request involving the Customer business object.
|
DataHandlerConfigMO | Yes | Yes | The 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. You use this 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 Appendix B, Connector specific properties. |
DataHandlerMimeType | Yes | Yes | Allows you to request a data handler based on a particular MIME type. If specified in the meta-object, this will override the value specified in the DataHandlerMimeType connector property. Use this 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 Appendix B, Connector specific properties. |
DataHandlerClassName | Yes | Yes | See the description in Appendix B, Connector specific properties. |
InputFormat | Yes | Yes | The format or type of inbound (event) message to associate with the given business object. This value helps identify the message content and is specified by the application that generated the message. When a message is retrieved and is in this format, it is converted to the given business object, if possible. If this format is not specified for a business object, the connector does not handle subscription deliveries for the given business object. Do not set this property using default meta-object conversion properties; its value is used to match incoming messages to business objects. 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 | The format to be populated in outbound messages. If the OutputFormat is not specified, the input format is used, if available. |
InputQueue | Yes | Yes | The input queue that the connector polls to detect new messages.
This property is used to match incoming messages to business objects
only. Do not set this property using default conversion
properties; its value is used to match incoming messages to business
objects.
|
OutputQueue | Yes | Yes | The queue to which messages derived from the given business object are delivered. |
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. |
TimeoutFatal | Yes | Yes | Used in synchronous request processing to trigger the connector to return an error message if a response is not received. If this property is True, the connector returns APPRESPONSETIMEOUT to the broker when a response is not received within the time specified by ResponseTimeout. If this property is undefined or set to False, then on a response timeout the connector fails the request but does not terminate. Default = False. |
DataEncoding |
|
|
DataEncoding is the encoding to be used to read and write
messages. 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, or
Binary. This property is related internally to the
InputFormat property: specify one and only one DataEncoding per
InputFormat.
|
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. | |||
ReplyToQueue |
| Yes | The queue to which a response message for a request is to be sent. |
Type |
| Yes | The type of message. The type of message is generally user-definable, depending on JMS provider. |
MessageID |
| Yes | The unique ID for the message (JMS provider specific). |
CorrelationID | Yes | Yes | This is 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 incluce the following:
1=non-persistent 2=persistent Other values, depending on the JMS provider, may be available. |
Priority |
| Yes | The numeric priority of a message. Acceptable values include 0 through 9 inclusive (low to high priority). |
Destination |
| Yes | The current or last (if removed) location of the message in the MOM system. |
Redelivered |
| Yes | Indicates that the JMS provider most likely attempted to deliver the message to the client earlier but the receipt was not acknowledged. |
Timestamp |
| Yes | Indicates that the time message was handed off to the JMS provider. |
UserID |
| Yes | The identity of the user sending the message. |
AppID |
| Yes | The identity of the application sending the message. |
DeliveryCount |
| Yes | The number of delivery attempts. |
GroupID |
| Yes | The identity of the message group. |
GroupSeq |
| Yes | The sequence of this message in the message group specified in the GroupID. |
JMSProperties |
| Yes | See JMS properties. |
The WebSphere MQ adapter configuration meta-object consists of a list of conversion properties defined for different business objects. To view an example static meta-object, launch Business Object Designer and open the following example that is shipped with the adapter: connectors\WebSpereMQ\samples\LegacyContact\WebSpereMQ_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 metadata 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 metadata properties you want to specify for this unique object-verb combination.
Table 45. 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 46. Example 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 example 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_Create and Order_Create as having OutputDestination=QueueA in addition to their individual metadata properties:
Table 47. Example static meta-object structure
Attribute name | Application-specific information |
---|---|
Default |
OutputDestination=QueueA |
Customer_Update |
OutputFormat=CUST |
Order_Create |
OutputFormat=ORDER |
Table 44 describes the properties that you can specify as application-specific information in the static meta-object.
A static meta-object contains application-specific information that you specify about business objects and how the connector processes them. A static meta-object provides the connector with all the information it needs to process a business object when the connector is started.
At the time of implementation, if you know which queues different business objects must be sent to, use a static meta-object. When you create and configure the static meta-object, make sure that the connector subscribes to the static meta-object by specifying the name of the static meta-object in the connector-specific property, DataHandlerConfigMO. For more information, see "Connector-specific properties".
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 map a data handler to an InputQueue, perform the following steps:
For example, the following attribute in a static meta-object associates a data handler with an InputQueue named CompReceipts:
[Attribute] Name = Cust_Create Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = InputQueue=//queue.manager/CompReceipts;DataHandlerClassName= com.crossworlds.DataHandlers.WBIMB.disposition_notification;DataHandlerMimeType= message/ disposition_notification IsRequiredServerBound = false [End]
If the connector is required to process a business object differently, depending on the scenario, use a dynamic meta-object. This is a child object that you add to the business object. The dynamic meta-object tells the connector, at run-time, how to process a request. Unlike the static meta-object, which provides the connector with all of the information it needs to process a business object, a dynamic meta-object provides only those additional pieces of logic required to handle the processing for a specific scenario.
Dynamic meta-objects allow you to change the metadata 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 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 44 describes the properties that you can specify as application-specific information in the dynamic meta-object.
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 create and configure a dynamic meta-object, perform the following steps:
The connector will check for the dynamic meta-object and use its information to determine how to process the business object.
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 Table 48 shows how a dynamic child meta-object might be structured
for polling.
Table 48. Dynamic child meta-object structure for polling
Property name | Example value |
---|---|
InputFormat | CUST_IN |
InputQueue | MYInputQueue |
OutputFormat | CxIgnore |
OutputQueue | CxIgnore |
ResponseTimeout | CxIgnore |
TimeoutFatal | CxIgnore |
As shown in Table 48, 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:
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.
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:
The table below shows application-specific information properties that you must define for attributes in the JMSProperties object.
Table 49. 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 6 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 6. JMS properties attribute in a dynamic meta-object
To create a dynamic meta-object, perform the following steps:
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.