Generating an MQ JMS export binding

Generating a WebSphere MQ JMS export binding with either a one-way operation or request-response operation is shown. Once generated, the binding properties are discussed.

Prerequisites: You should have a module.

If you intend to use the standard JMS message class with a body type containing the message then you must create business objects for these body types. A function is provided that will create the entire set of business objects for the JMS body types. In your module, open the dependencies editor. Under Predefined Resources, select Schema for simple JMS Data Bindings. Save your work and close the dependencies editor. In the navigation view under Data Types, the business objects are created.

Afterwards, create an interface for your export that contains the appropriate data types for input and output. For example, if you were using the TextMessage body, create an interface with an operation such as handleText with an input type of JMSTextBody and an output type of JMSTextBody. These data types will be selectable from the types in the interface editor.

In this set of steps, you will learn how to create a WebSphere MQ JMS binding for an export. An MQ JMS binding is used when you want to have your service accessed in an asynchronous manner from the WebSphere MQ Messaging client.
  1. Open the assembly editor. From the component group on the palette, select an export and drag it on to the canvas. An export with no implementation and no interface is created. Right-click the component, select Add > Interface from the pop-up menu and add an interface that describes your interaction with a WebSphere MQ application. Create an export with an MQ JMS binding by right-clicking the component and from the pop-up menu selecting Generate Binding > Messaging Binding >MQ JMS Binding.
    Generating an MQ JMS binding
  2. The Configure WebSphere MQ JMS Export Service dialog box opens. An interface with a one-way operation results in the dialog shown below. You must enter an MQ queue name for the receive destination to proceed.
    WebSphere MQ JMS export binding configuration for an interface with a one-way operation
    An interface with a request-response operation produces a similar dialog as shown below with an additional field for a send destination. In the case of a request-response operation, you must enter an MQ queue name for the receive destination and the send destination to proceed.
    MQ JMS export binding configuration for an interface with a request-response operation

    Select the messaging domain: Point-to-Point or Publish-Subscribe. Publish-subscribe is selectable if the interface only has one-way operations.

    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, receive destination for a one-way operation, and receive and send destinations for a request-response operation, and the receive destination listener port name. You may specify the WebSphere MQ queue manager or use the default queue, which is preselected.

    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.

    In the Data format section, select how the data will be serialized between the business object and the JMS message. For data bindings beginning Simple JMS, you must have previously created the business objects required (see the Prerequisites section). The default data bindings are:

    • 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. Your wrapped data objects must be a complex type; they can not be a simple type.
    • 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.

    The alternative is for you to provide your own data binding for the serialization, in which case select User Supplied. The implementation has to conform to the JMS data binding interface.

    The FunctionSelector class provides a valuable service at run time. It selects an operation to invoke on the component. In the Function selector section, if you do not wish to use the default JMS function selector class, deselect it. After deselecting the default JMS FunctionSelector, you should browse and select the FunctionSelector you do wish to use.

    If you intend to use the standard JMS message class with a body type containing the message then you must use a specific function selector, which uses the JMSType message property to determine its operation name. For example, if you had selected for your serialization type, Simple JMS TextMessage Data Binding, then you would use this particular function selector. Deselect the Use the default JMS Function Selector class check box. Click Browse and select JMSFunctionSelector from the Select Type dialog box. The qualified class name is com.ibm.websphere.jms.data.bindings.JMSFunctionSelector.

    Click OK. The MQ JMS binding is created and shown in the properties view when the Binding tab is selected. Sub tabs under the binding tab provide binding information details, which are discussed in the next steps.

    Note: The MQ JMS binding is complete as is and only if you need to change the values do you need to change them in the fields discussed below.
  3. Selecting the Binding tab shows the function selector class name and serialization type.
    Export binding general information
    Note: As you proceed through the fields discussed here, remember that extensive hover help is provided on most of the generated fields.
  4. Selecting the End-point configuration tab and the Request tab, opens the connection factory properties, listener port properties and receive destination properties. You may specify a JNDI lookup name. If a JNDI lookup name is specified, most properties will be hidden as the JNDI name points to a preconfigured set of values specified on the target server. Using a JNDI name often occurs when a system administrator sets up the connection information for you. If you use JNDI, you will still need to set up the MQ queue manager though again this might be done by a system administrator. In our case, a JNDI lookup name was not specified.

    The Connection Factory Properties section specifies the connection factory properties such as the transport, which defaults to BINDINGS. With the bindings mode, WebSphere MQ JMS classes use the Java Native Interface (JNI) to call directly into the existing queue manager API rather than communicating through a network. Since bindings is a shared memory protocol, it may offer better performance. If you select CLIENT for a client binding, then client configuration properties become active requiring you to specify the host name, channel and port. See Using binding or client transports for more information. Further down this page, though not shown in the screen capture below, are MQ local address properties. Show Advanced specifies the listener type.


    Endpoint configuration properties for a request connection

  5. Listener Port Properties found lower on this page provides a field to specify the listener port name and change the number of retries and sessions, which default to one.Receive Destination Properties specifies the type of receive destination, queue or topic, the destination name that you specified earlier and the target client type, JMS by default though MQ is selectable. Alternately, you can use a JNDI name.
    Listener port and receive destination properties
  6. Selecting the Response tab in the case of a request-response operation has fields for the send destination properties similar to the receive destination properties of the request. You can optionally select Configure response connection if you wish to specify your own values such as the transport type similar again to the receive destination properties. If you specify a JNDI name, this information is not available as it is configured on the server; that is, the destination specified on the server under this JNDI name will be used. The default encoding properties for integer, decimal and floating point numbers are listed.
    Endpoint configuration response properties
  7. Selecting Method bindings shows the bound methods. By default, all methods are bound. If you add a method to the interface after you created the binding, however, a Bind operation check box becomes available for you to add it to the bound methods. The JMS type property conforms to the JMSType specified in the JMS specification. This property contains a message type identifier supplied by a client when a message is sent. The JMS correlation ID property conforms to the JMSCorrelationID in the JMS specification. A typical use is to link a response message with its request message. In WebSphere Integration Developer, the ID is used by the message selector to select only messages with that ID. It can be any string value. JMS delivery mode can be either persistent, guaranteed delivery is required, or non-persistent, an occasional lost message is tolerable. JMS priority specifies a level priority value with 0 as the lowest and 9 as the highest. 4, the default, is considered normal priority.Custom Headers allow you to specify a name, type and value for a property.

    Clicking Show Advanced found lower on this page and not in this screen capture lets you specify the input and output serialization types, which determines how the data will be serialized between the business object and the JMS message.
    Method level bindings

  8. Selecting Security attributes with the Request tab shows the authentication properties under Authentication Properties 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. If Show Advanced is selected, authentication properties are shown such as the level of the authentication; for example, at the container level. If the connection transport type has been set to CLIENT, then Secure Sockets Layer (SSL) encryption can be enabled.
    Security attributes
  9. If you selected Configure response connection earlier in the End-point configuration tab, then selecting the Response tab will provide you with authentication properties for the response connection. Also, if the connection transport type has been set to CLIENT, then Secure Sockets Layer (SSL) encryption can be enabled for the response.
  10. 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. The Asynchronous Reliability property can have these values: assured (default) or bestEffort. Select assured if you want a message to persist through a transaction. In other words, if you want guaranteed delivery of the message. Select bestEffort if you want a high throughput of messages and your application can accept and handle the loss of a message, as persistence is not guaranteed. Event sequence required specifies if the same order of events as received from WebSphere MQ must be followed by the component receiving the events.
    Message configuration properties
  11. Selecting the Summary tab specifies the receive and send destination (in the case of a request-response operation) JNDI names, request and response connection factory JNDI names, listener port name, function selector class name and data binding class name. With the exception of the function selector class name and data binding class name, they are names generated by the SCA JMS handler if you did not specify any custom JNDI names. You may need these JNDI names if you are authoring the targeted JMS application.
    Summary properties
You have created an MQ JMS binding for your export. Compare this approach with creating an MQ JMS import binding.
Related tasks
Generating an MQ JMS import binding

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