Configure the Java Message Service (JMS) transport policy

We can define a Java Message Service (JMS) transport policy configuration if we are using SOAP over JMS with the JAX-WS applications.

We can configure some settings for policies for custom policy sets. The provided default policy sets cannot be edited. Create a copy of the default policy set or create a new policy set in order to specify the policies for it.

When using the SOAP over JMS transport with JAX-WS applications, we can customize the transport by configuring the JMS transport policy. The SOAP over JMS transport provides an alternative to HTTPS for transporting SOAP requests and response messages between clients and servers. See the documentation on using SOAP over JMS to transport web services to learn more about this transport protocol.

We can only configure a policy through a policy set. Therefore, before we can configure the JMS transport policy, a policy set must exist containing the JMS transport policy. To customize a policy set containing the JMS transport policy, first create a policy set and add the JMS transport policy to the new policy set.

Use the JMS transport policy settings panel to customize the values of the JMS transport policy properties, such as the request timeout value. Your customized values for the JMS transport policy now apply for the policy set containing that custom JMS transport policy. We can attach this policy set containing the customized JMS transport policy to the JAX-WS application, its services, endpoints, or operations. This change affects all JAX-WS applications to which that policy set is attached. To learn more about attaching policy sets to applications, see the documentation for managing policy sets for service providers and service clients at the application level.

1. Create a policy set containing the JMS transport policy.

   1. Create a custom policy set. From the administrative console, click Services > Policy Sets > Application policy sets. From this panel we can create a new policy set, import a copy of a policy set from the default repository, or we can import an existing policy set from your specified location.

   2. Add the JMS transport policy to the policy set. From the administrative console, click Services > Policy Sets > Application policy sets > policy_set_name. In the policy collection, click JMS transport. The JMS transport window displays options for configuring the JMS settings for the transport policy.

   3. Specify the JMS connection properties for the JMS transport requests. The following fields configure the JMS features for this transport:

      Request timeout

      Whether to enable a request timeout value. The request timeout value is the amount of time that the client waits for a response after sending the request to the server. The range is from 0 to 2147483647.

      Allow transactional messaging for one-way and asynchronous operations

      Specifies to enable a client to use transactions in one-way or asynchronous two-way requests. Select this check box to enable transactional messaging.

      When this option is selected, the client runtime environment exchanges SOAP request and response messages with the server over the JMS transport in a transactional manner if the client is operating under a transaction. This process indicates that the clients transaction is used to send the SOAP request message to the destination queue or topic, and the server receives the request message only after the client commits the transaction. Similarly, the server receives the request message under the control of a container-managed transaction and sends the reply message, if applicable, back to the client using that same transaction. The client then receives the reply message only after the server transaction has been committed.

      If this option is not selected, then the client and server runtime environments perform messaging operations in a non-transactional manner as transactions are temporarily suspended for the JMS request. The transactions are enabled again after the request has completed.

      Supported configurations: Transactional messaging operations are not supported for two-way synchronous operations as this leads to a deadlock condition.

2. Customize the JMS transport provider bindings.

   1. Navigate to the JMS transport provider bindings. From the administrative console, click Services > Policy Sets > General provider policy set bindings > provider_policy_set_binding_name > JMS transport.

      The JMS transport provider bindings window displays options for defining basic authentication for asynchronous service responses and custom properties for the JMS service provider binding configuration.

   2. Specify the properties for basic authentication for asynchronous service responses.

      We can use the JMS transport provider policy bindings to configure a service that uses the JMS transport to send asynchronous response messages back to the client. The application server runtime environment uses the user name and password configured when connecting to the JMS messaging provider and this configuration enables the service to send an asynchronous response message to the client in a secure manner.

      The following fields determine the authentication requirements for responses from the server:

      User name

      User name for the asynchronous service responses for the service provider.

      Password

      Specifies a placeholder for the password for the asynchronous service responses from the service provider. We can enter or edit the password in this field. The actual password is masked.

      Confirm password

      Specifies a placeholder for the password for the asynchronous service responses from the service provider that must match the one in the Password field. The actual password is masked.

3. Customize the JMS transport client bindings.

   1. Navigate to the JMS transport client bindings. From the administrative console, click Services > Policy Sets > General client policy set bindings > client_policy_set_binding_name > JMS transport.

      The JMS transport provider bindings window displays options for defining basic authentication for outbound service requests and custom properties for the JMS client binding configuration.

   2. Specify the Basic Authentication for Outbound Service Requests properties.

      We can use the JMS transport client policy bindings to configure a client that uses the JMS transport to send a request message to the server. The client runtime environment uses the user name and password configured when connecting to the JMS messaging provide. This configuration enables the client to send the request message to the server in a secure manner.

      The following fields determine the authentication requirements for requests sent to the server:

      User name

      User name used by the client runtime when connecting to the JMS messaging provider to send an outbound request to the destination queue or topic. Enter a user name in this field.

      Password

      Specifies a placeholder for the password used by the client runtime when connecting to the JMS messaging provider to send an outbound request to the destination queue or topic. We can enter or edit the password in this field. The actual password is masked.

      Confirm password

      Specifies a placeholder for the password used by the client runtime when connecting to the JMS messaging provider to send an outbound request to the destination queue or topic. Re-enter the password in this field. This password must match the one in the Password field. The actual password is masked.

4. Set the com.ibm.ws.websvcs.transport.jms.enableBasicAuthOnResponse JVM custom property to true.

   See the topic Java virtual machine custom properties for a description of how to specify this property.

5. Save the changes.

Results

After you have customized the JMS transport policy, the associated policy set uses this policy to configure the runtime behavior of the SOAP over JMS transport.

Example

We can attach policy sets to an application, its services, endpoints, or operations. In this example scenario, suppose you have two different JAX-WS service clients for the application, but to use different JMS transport request timeout values for each service client. To modify the JMS request timeout values, we can edit the values of the JMS transport policy contained within the policy set that is attached to the application or in this case, the service client. This change affects all applications to which the policy set containing the custom JMS transport policy is attached.

This example describes the steps for configuring different request timeout values for service clients deployed in the same application server. This example includes the following assumptions:

• Two JAX-WS service clients exist, ServiceClient1 and ServiceClient2, that are deployed in the application server.

• The JMS transport policy has not been previously attached to these applications.

1. Create two new policy sets and add the JMS transport policy to them. For example: JMSServiceClient1Policy and JMSServiceClient2Policy

   1. Click Services > Policy sets > Application policy sets > New .

   2. Enter the name of the new application policy set, JMSServiceClient1Policy.

   3. From the Policies collection, click Add > JMS transport.

   4. Click Apply and Save to save the changes to the master configuration.

   5. Repeat these steps to create the JMSServiceClient2Policy.

2. Customize the JMS transport policy settings for the newly created JMSServiceClient1Policy and JMSServiceClient2Policy policy sets. For example, set the request timeout value to 180 seconds for the JMS transport policy contained in the JMSServiceClient1Policy. The JMS transport policy contained in the JMSServiceClient2Policy specifies 300 seconds as the request timeout value.

   1. Click Services > Policy sets > Application policy sets > JMSServiceClient1Policy .

   2. From the Policies collection, click JMS transport.

   3. From the JMS transport policy configuration panel, specify 180 seconds for the request timeout value.

   4. Click Apply and Save to save the changes to the master configuration.

   5. Click Services > Policy sets > Application policy sets > JMSServiceClient2Policy .

   6. From the Policies collection, click JMS transport.

   7. From the JMS transport policy configuration panel, specify 300 seconds for the request timeout value.

   8. Click Apply and Save to save the changes to the master configuration.

3. Attach the custom JMS transport policy, JMSServiceClient1Policy, to the application, ServiceClient1. Similarly, attach the custom JMS transport policy, JMSServiceClient2Policy, to ServiceClient2.

   1. Click Services > Service clients > ServiceClient1.

   2. From the Policy set attachments collection, select the service, ServiceClient1.

   3. Click Attach Client Policy Set, and click JMSServiceClient1Policy.

   4. Click Save to save the changes to the master configuration.

   5. Click Services > Service clients > ServiceClient2.

   6. From the Policy set attachments collection, select the service, ServiceClient1.

   7. Click Attach Client Policy Set, and click JMSServiceClient2Policy.

   8. Click Save to save the changes to the master configuration.

As a result, the ServiceClient1 application now has the JMSServiceClient1Policy attached, and the JMS sessions use a request timeout of 180 seconds. The ServiceClient2 application has the policy, JMSServiceClient2Policy, attached and the JMS sessions use a request timeout of 300 seconds.

What to do next

We can customize other policies that we might need for the application.

Subtopics

• JMS transport policy settings
  Use this page to configure settings for the Java Message Service (JMS) transport policy. We can configure a client that is using the JMS transport policy to exchange request and response messages with the server.

• JMS transport bindings
  Use this page to define the Java Message Service (JMS) transport provider or client bindings configuration.

Related concepts

Web services policies

Related tasks

Manage policy sets and bindings for service providers at the application level using the administrative console

Manage policy sets and bindings for service clients at the application level using the administrative console

Add policies to policy sets using the administrative console

Delete policies from policy sets using the administrative console

Enable policies for policy sets using the administrative console

Disable policies from policy sets using the administrative console

Application policy sets collection

Application policy set settings

Transport header properties best practices

Use SOAP over JMS to transport web services