Creating an MQ JMS import to communicate with an MQ JMS or JMS client

You may wish to connect your service-oriented architecture (SOA) application to an existing MQ JMS or JMS client. In this task, we will take you step by step through the steps necessary to do this.

Prerequisite: The JMS administered objects are configured for the MQ JMS or JMS client and known. In addition, there should be a module that contains your service oriented architecture application. The message format expected by the JMS client is also known

Note: For simplicity, we will refer to an MQ JMS or JMS client as a JMS client.
  1. In order for your SOA application to communicate to an existing MQ JMS or JMS client, you will need to have created a business object and an interface that would represent your JMS client application in an SOA manner. Mapping a JMS, MQ or MQ JMS message to an SCA interface provides guidance on how to create such a business object and interface.
  2. You must create a component that will enable your existing SOA application to communicate to the existing JMS client application. To do this, you will create an import and add a binding type of MQ JMS to it.

    There are two main types of information that need to be captured by the MQ JMS binding. One set of information is needed by the service component architecture (SCA). This includes information such as the interface, which we discussed earlier, and the serialization type, which we will discuss later. The other set of information is the configuration needed to communicate using JMS such as the specification of JMS destination objects, which we will also discuss later.

    Open the assembly editor of your module. From the import group on the palette, select an import and drag it on to the canvas. An import with no implementation and no interface is created. Right-click the component, select Add Interface from the contextual menu and add the interface created in step 1. Generate the MQ JMS binding by selecting the import and from the contextual menu select Generate Binding > Messaging Binding > MQ JMS Binding.


    Invoking the MQ JMS binding

  3. The Configure WebSphere MQ JMS Import Service dialog opens.

    You may select the JMS messaging domain as either Publish-Subscribe or Point-to-Point. The consequences of selecting publish-subscribe is that the values for the JMS Destination type will default to use javax.jms.Topic. Similarly, the consequences of selecting point-to-point is that the values for the JMS Destination type will be default to use javax.jms.Queue. You may change these defaults within the wizard. If your interface contains a request-response operation, the wizard will default the JMS messaging domain to point-to-point.

    Select if you wish to Configure new messaging provider resources (the default) or Use pre-configured messaging provider resources. If you choose pre-configured, then add the JNDI names for the connection factory and the send destination for a one-way operation, and send and receive destinations for a request-response operation. We chose to configure the messaging resources. With the MQ JMS binding, you must specify the WebSphere MQ queue name for the send destination and receive destination (for request-response operations, which in our case we will be using). The WebSphere MQ queue manager must also be specified. The existing default queue manager is selected by default.

    In the Security configuration section, the J2C Authentication Data Entry property lets you specify an authentication alias that should be configured on the server with a userid and password.

    You must choose the serialization type that is expected by the JMS client application. The serialization type is used to map between the business object used in your SOA application and the message format expected by the JMS client application. There are several serialization types provided as listed below. For serialization types beginning Simple JMS, you must have previously created the business objects required (see the Prerequisites section of Generating an MQ JMS import binding for a quick way of creating these business objects).

    • Serialized Business Object using JMS ObjectMessage sends the business object whose underlying implementation is a service data object (SDO) in a JMS object message to and from the JMS client. This serialization type is preferred when dealing with other SOA components using JMS.
    • Business Object XML Using JMS TextMessage serializes the business object to and from XML and uses a JMS text message to communicate with the JMS client. To see how the business object is serialized to XML, see Business object XML using JMS text message serialization.
    • Simple JMS TextMessage Data Binding sends the JMSTextBody business object in a TextMessage message body to the client. The message body type is a String.
    • Simple JMS BytesMessage Data Binding sends the JMSBytesBody business object in a BytesMessage message body to the client. The message body type is a byte array.
    • Simple JMS MapMessage Data Binding sends the JMSMapBody business object in a MapMessage message body to the client. The message body type is a set of name/value pairs that can be addressed by name. The data type of the value is a Java primitive.
    • Simple JMS StreamMessage Data Binding sends the JMSStreamBody business object in a StreamMessage message body to the client. The message body type is a stream of Java primitives.
    • Simple JMS ObjectMessage Data Binding sends the JMSObjectBody business object in an ObjectMessage message body to the client. The message body type is a serialized Java Object.
    • Simple JMS Message Data Binding does not have a message body. It can be used to notify the JMS client of an event or to send some simple data in the message headers or properties.

    If the JMS client is expecting a different serialization style than those above, select User Defined and specify the appropriate data binding implementation. An example of this different serialization would be if the JMS client is expecting a JavaBean as the payload of a JMS object message, then a user-supplied data binding implementation would be used that would map between the Service Data Object (SDO) and the JavaBean. See Creating a user-defined JMS data binding for an illustration on how this would be done.

    For more information on JMS data bindings, see JMS and MQ JMS data bindings.

    Lastly, you must specify if you wish to generate the TargetFunctionName message header property for the default function selector class. Checking this box causes a header property to be generated, which is expected by the default function selector implementation. If this is the desired behavior, keep it checked, otherwise uncheck the box. See JMS and MQ JMS function selector for more information.

    In this task, the JMS client is expecting XML in a JMS text message so we chose the appropriate serialization type Business Object XML using JMS TextMessage. In addition, because you are communicating with an existing JMS client, you will uncheck the Generate "TargetFunctionName" message header property for default JMS Function Selector because the JMS client would not know how to handle the custom JMS header tag that would have been generated if it were checked.


    MQ JMS import binding configuration using an interface with a request-response operation

  4. The MQ JMS binding is created and shown in the properties view when the Binding tab is selected. The following chart provides some guidance for the configuration you see in the next few screen captures.
    Table 1. Relationship of request and response to configuration
    Request or response Connection factory Send destination Receive destination Listener port Correlation scheme
    Configuration elements in a request or response Creates the connection to the messaging provider. Destination where the message is sent. Destination where the response message is received. Port that listens to the response from the WebSphere MQ server Correlates response messages with request messages in request-response operations.
    Import request A JNDI name or one created with default settings when the application is deployed. A JNDI name or the queue name of the WebSphere MQ queue manager. Not applicable Not applicable Adds a request ID to the request message (default) or adds a correlation ID to the request message.
    Import response Uses the same connection factory as the request or one that is specified by you. Not applicable A JNDI name or the queue name of the WebSphere MQ queue manager. A name is created on deployment or one that is specified by you. Not applicable

    Select the End-point configuration tab under the Binding tab. Under the Request tab, you can accept the defaults and the tools will create a connection factory when the application is deployed or you can specify a connection factory JNDI name if it has been pre-configured on the messaging provider resource. In our case, we accepted the defaults.

    We chose a BINDINGS transport option, which is the default.. With this setting, you do not need to specify host name, channel or port as WebSphere MQ JMS classes will use the Java Native Interface (JNI) to call directly into the existing queue manager API rather than communicating through a network. Bindings is a shared memory protocol and may offer better performance. An alternative is the CLIENT setting, which means you must specify the values for the client configuration including host name, channel and port and optionally the client channel definition table. The WebSphere MQ client connection is used to connect to the queue manager.


    Connection factory properties

    Expanding Send Destination Properties , you can specify a JNDI name or you can accept the defaults, in which case the tools create the properties. Specify the appropriate settings to ensure your SOA application is able to communicate to the JMS client. For this task, we accepted the defaults for the settings but provided the send destination, which was specified earlier when we created the bindings. The name contains the WebSphere MQ queue name.


    Send destination properties

  5. For the Receive Destination Properties section beneath the Response tab, we accepted the defaults but specified the receive destination, which we entered earlier when creating the binding. It contains the WebSphere MQ queue name. Note that in the response, the default connection factory is the same as the request connection factory unless you choose to create a different one.


    Receive destination properties

  6. The existing JMS client may expect certain header properties to be configured. You may specify these under the Method bindings tab. For each business method that represents a corresponding JMS client application method, you may specify unique JMS message header properties required. For example, if the existing JMS client application requires the message header JMSType to specify the application method name for which the JMS message is targeted, you will specify it here.


    Method bindings

  7. The Message Configuration tab shows the correlation scheme for the response message. Request Message ID to Correlation ID adds a request ID to the request message. It is expected that the reply copies the request ID to the correlation ID field of the response message so that the requestor can correlate the reply message with the request message. Request Correlation ID to Correlation ID adds the correlation ID to the request message. It is expected that the reply copies the request correlation ID to the correlation ID field of the response message so that the requestor can correlate the reply message with the request message.


    Message configuration properties

  8. Selecting the Summary tab specifies the send and receive destination (in the case of a request-response operation) JNDI names, request and response connection factory JNDI names, listener port name and data binding class name. This is a page you should check to verify the configured resources.


    Summary of binding properties

The import that will communicate to the existing JMS client application is completed. You should test it before you attach it to your SOA application to ensure it is working as designed. To do this, you can use the test component feature of the integration test client. Once you are certain that it is correct, you can then connect your SOA application to the import you just created.

Feedback
(C) Copyright IBM Corporation 2005, 2007. All Rights Reserved.