Adapter Cookbook. Configuring a Native WebsphereMQ Adapter. Adaptris Development

Transcription

1 Adapter Cookbook Configuring a Native WebsphereMQ Adapter Adaptris Development

2 Table of contents Adapter Cookbook Disclaimer About This Document Software pre-requisites Adapter Configuration Connections Sending and Receiving messages FieldMapper MetadataMapper MessageIdMapper ConfiguredField XpathField ByteTranslator Options

3 1 Disclaimer This document is not intended as a user guide, and may not be suitable for your specific configuration. Adaptris cannot accept any liability or responsibility for any problems howsoever caused in conjunction with its use or as a result of following the examples within. 3

4 2 About This Document This is a brief checklist and documentation of what you have to do to configure the mediation framework to work directly with Websphere MQ using its native interface. You will already be familiar with the Adapter and its underlying concepts. No additional Websphere MQ knowledge is required. As with everything, it is important to have an adequate rollback and recovery plan in case things don t go as expected. 3 Software pre-requisites You will need to have access to a configured WebsphereMQ installation, and be able to install the WebsphereMQ client, if this is appropriate. For the Adapter, you will need a installation or better. Depending on your WebsphereMQ installation specifics, you will need to copy com.ibm.mq.jar, com.ibm.mqjms.jar, connector.jar, dhbcore.jar and jta.jar from your WebsphereMQ installation into the Adapter lib directory so that the required classes are available. Additionally, you will find it useful to download the information centre for the WebsphereMQ version you are using from IBM. This document will refer to various elements that are available in the Information Centre. 4 Adapter Configuration Generally, it is preferred to treat WebsphereMQ as a standard JMS Provider, using MqSeriesImplementation to provide the necessary mapping between the standard JMS interfaces and WebsphereMQ. In some situations, it is preferable to use the native api for accessing WebsphereMQ, perhaps because not all the fields from MQMessage are mapped when using the JMS API. All the classes referred to here are either part of the package com.adaptris.core.wmq or a sub-package. There are examples available in the example-xml directory. 4.1 Connections There are two types of connection available to use; AttachedConnection and DetachedConnection

5 Both types of connection have exactly the same configuration. The key <connection xsi:type="java:com.adaptris.core.wmq.detachedconnection"> <redirect-exception-logging>false</redirect-exception-logging> <environment-properties> <key-value-pair> <key>ccsid</key> <value>myccsid</value> </key-value-pair> </environment-properties> <queue-manager>your_q_manager</queue-manager> </connection> difference between the two connections is that an AttachedConnection reuses the same MQQueueManager instance for the lifecycle of the connection. DetachedConnection creates a new MQQueueManager instance every time it is required. AttachedConnection may have added performance benefits, if MQQueueManager is a resource hungry component; however, in testing, using AttachedConnection stopped WebsphereMQ from performing a controlled shutdown, and caused additional issues when attempting to recover from an uncontrolled shutdown. Element Name <queue-manager> <redirect-exception-logging> <environment-properties> 4.2 Sending and Receiving messages Description The name of the queue manager within WebsphereMQ to connect to Defaults to false. MQException exposes a static field log which receives additional logging information when an MQException is encountered. Set this to be true, if you wish for that additional logging to be redirected from stderr to the log4j logging system. A KeyValuePairSet that contains additional properties that are provided to the MQQueueManager constructor. This exposes primitive values (such as String, Boolean, integer) so that the default WebsphereMQ Client settings can be overridden. Consult the javadocs for com.adaptris.core.wmq.nativeconnection for additional information Both the AdaptrisMessageProducer and AdaptrisMessageConsumer implementations for WebsphereMQ have broadly the same type of configuration. The standard implementation for consuming messages from WebsphereMQ is a PollingConsumer implementation. There is no facility within the WebsphereMQ API to register a listener, so we physically poll the MQQueueManager for any new messages and process them upon each poll trigger. 5

6 Each implementation contains a list of field-mapper elements that are <consumer xsi:type="java:com.adaptris.core.wmq.nativeconsumer"> <field-mapper xsi:type="java:com.adaptris.core.wmq.mapping.messageidmapper"> <mq-field-name>messageid</mq-field-name> <convert-null>false</convert-null> <byte-translator xsi:type="java:com.adaptris.core.wmq.mapping.base64bytetranslator"/> </field-mapper> <field-mapper xsi:type="java:com.adaptris.core.wmq.mapping.metadatafieldmapper"> <mq-field-name>applicationiddata</mq-field-name> <convert-null>false</convert-null> <metadata-key>application_id_data_metadatakey</metadata-key> </field-mapper> <log-all-exceptions>false</log-all-exceptions> <destination xsi:type="java:com.adaptris.core.configuredconsumedestination"> <destination>system.default.local.queue</destination> </destination> <options> <message-options>4</message-options> <queue-close-options>0</queue-close-options> <message-format>text</message-format> <queue-open-options>49</queue-open-options> </options> </consumer responsible for mapping each MQMessage field to and from the AdaptrisMessage. Additionally, each implementation has a number of configurable options available so that the MQQueue is accessible with a variety of options FieldMapper There are a number of ways you can map specific MQMessage fields into AdaptrisMessage and vice versa. All field mapper instances contain some common configuration elements: mq-field-name This refers to the specific field within the MQMessage that you wish to map. Refer to the javadocs for com.adaptris.core.wmq.mapping.fieldmapper.field to see the supported fields. byte-translator Some MQMessage fields are byte[] fields. The bytetranslator is responsible for mapping the byte[] into Strings and vice versa. convert-null Whenever a null value is encountered, and this field is true, an attempt is made to convert the null into something meaningful MetadataMapper This maps an item of AdaptrisMessage metadata to a specific MQMessage field (and vice versa). The metadata-key element determines the metadata key that will be used to derive the content of the mapping MessageIdMapper This maps the AdaptrisMessage unique id into a specific MQMessage field (and vice versa). 6

7 ConfiguredField This simply sets a specific MQMessage field to the configured value. MQMessage fields may not be mapped into AdaptrisMessage using this FieldMapper instance XpathField This resolves an XPath against the AdaptrisMessage payload and sets a specific MQMessage field based on this value. MQMessage fields may not be mapped into AdaptrisMessage instances using this FieldMapper instance ByteTranslator There are currently 3 different byte translator implementations. CharsetByteTranslator Translates to and from bytes using the specified character set (the default is UTF-8) SimpleByteTranslator Translates to and from bytes using the default platform encoding Base64ByteTranslator Converts bytes into a base64 encoded string, and a base64 encoded string into bytes Options The options on the consumer and producer control the behaviour when you Open the queue Close the queue Message Type that is sent/received from the queue Specific message options that control the behaviour of MQQueue.put() and MQQueue.get() All the options available are integers and are used as-is from configuration. What this means is that if you have specific options (other than the default) which need to be applied, you will have to manually follow the notes in the information centre for those values. The easiest way to figure out the integer values that you require is to decompile MQC.java (from com.ibm.mq.jar) using your preferred de-compiler (e.g. jad), and to manually add up all the required integer values (e.g. MQC.MQOO_INPUT_AS_Q_DEF + MQC.MQOO_OUTPUT = 4) and to use the result of your calculation as the configured value. The default values are fairly sensible, and you should not have to modify these in most situations. If the options you have specified do not enable features that are specifically required by the Producer or Consumer at runtime, they will be added dynamically and a log message will be displayed indicating the option that was missing. Element Name <queue-open-options> Description Sets the open options on the queue when accessing the Queue. 7

8 <queue-close-options> <message-format> <message-options> Any or none of the literal values associated with the following MQC fields may be used. If more than one option is required, the values can be combined using '+' or ' ' to create an integer to populate this field. MQC.MQOO_INQUIRE, MQC.MQOO_BROWSE, MQC.MQOO_INPUT_AS_Q_DEF, MQC.MQOO_INPUT_SHARED, MQC.MQOO_INPUT_EXCLUSIVE, MQC.MQOO_OUTPUT, MQC.MQOO_SAVE_ALL_CONTEXT, MQC.MQOO_PASS_IDENTITY_CONTEXT, MQC.MQOO_PASS_ALL_CONTEXT, MQC.MQOO_SET_IDENTITY_CONTEXT, MQC.MQOO_SET_ALL_CONTEXT, MQC.MQOO_ALTERNATE_USER_AUTHORITY, MQC.MQOO_FAIL_IF_QUIESCING, Set the specific options to be used when closing a queue. The default value ismqc.mqco_none, but you may opt to use MQC.MQCO_DELETE or MQC.MQCO_DELETE_PURGE if you are working with permanent dynamic queues. Specify the format of the message. Valid values are Text, String, Bytes, and Object. They correspond to the values MQC.MQFMT_STRING, MQC.MQFMT_STRING, MQC.MQFMT_NONE and "Object" respectively. Bear in mind that Text implies UTF-8, so if you wish to use the platform default encoding, then use the String type. This controls the options that are used when invoking MQQueue.put() and MQQueue.get(). Depending on whether it is the consumer or producer, you will need to use different values. If the context of the message options is part of a producer, then the following values have meaning. MQC.MQPMO_SYNCPOINT, MQC.MQPMO_NO_SYNCPOINT, MQC.MQPMO_NO_SYNCPOINT, MQC.MQPMO_NO_CONTEXT, MQC.MQPMO_DEFAULT_CONTEXT, MQC.MQPMO_SET_IDENTITY_CONTEXT, MQC.MQPMO_SET_ALL_CONTEXT, MQC.MQPMO_FAIL_IF_QUIESCING, MQC.MQPMO_NEW_MSG_ID, MQC.MQPMO_NEW_CORREL_ID, MQC.MQPMO_LOGICAL_ORDER, MQC.MQPMO_ALTERNATE_USER_AUTHORITY, MQC.MQPMO_RESOLVE_LOCAL_Q. If the context of the message options is part of a consumer, then the following values have meaning. MQC.MQGMO_WAIT, MQC.MQGMO_NO_WAIT, MQC.MQGMO_SYNCPOINT, MQC.MQGMO_NO_SYNCPOINT, MQC.MQGMO_BROWSE_FIRST, MQC.MQGMO_BROWSE_NEXT, MQC.MQGMO_BROWSE_MSG_UNDER_CURSOR, MQC.MQGMO_MSG_UNDER_CURSOR, MQC.MQGMO_LOCK MQC.MQGMO_UNLOCK, MQC.MQGMO_ACCEPT_TRUNCATED_MSG, MQC.MQGMO_FAIL_IF_QUIESCING, MQC.MQGMO_CONVERT 8