You can define a Java™ Message
Service (JMS) transport policy configuration if you are using SOAP
over JMS with your Java API for XML-Based Web Services
(JAX-WS) applications.
Before you begin
You can configure some settings for policies for custom
policy sets. The provided default policy sets cannot be edited. You
must create a copy of the default policy set or create a new policy
set in order to specify the policies for it.
About this task
When using the SOAP over JMS transport with JAX-WS applications,
you 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.
You can only configure
a policy through a policy set. Therefore, before you can configure
the JMS transport policy, a policy set must exist that contains the
JMS transport policy. To customize a policy set that contains the
JMS transport policy, you must 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 your policy set
that contains that custom JMS transport policy. You can attach this
policy set containing your customized JMS transport policy to your
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.
Procedure
- Create a policy set that contains the JMS transport policy.
- Create a custom policy set.
From the administrative
console, click . From this panel
you can create a new policy set, import a copy of a policy set from
the default repository, or you can import an existing policy set from
your specified location.
- Add the JMS transport policy to the policy set.
From the administrative console, click . In the policy collection, click . The JMS transport window displays
options for configuring the JMS settings for the transport policy.
- Specify the JMS connection properties for the JMS transport
requests.
The following fields configure the JMS features
for this transport:
- Request timeout
- Specifies 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.
- Customize the JMS transport provider bindings.
- Navigate to the JMS transport provider bindings.
From the administrative console, click .
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.
- Specify the properties for basic authentication for
asynchronous service responses.
You 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 that you configure 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
- Specifies the 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. You 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.
- Customize the JMS transport client bindings.
- Navigate to the JMS transport client bindings.
From
the administrative console, click .
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.
- Specify the Basic Authentication for Outbound Service
Requests properties.
You 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 that you configure 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
- Specifies the user name that is 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 that is used by the client
runtime when connecting to the JMS messaging provider to send an outbound
request to the destination queue or topic. You can enter or edit the
password in this field. The actual password is masked.
- Confirm password
- Specifies a placeholder for the password that is 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.
- 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.
- Save your 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
You 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 your application, but you
want to use different JMS transport request timeout values for each
service client. To modify the JMS request timeout values, you can
edit the values of the JMS transport policy that is contained within
the policy set that is attached to your application or in this case,
your 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.
- Create two new policy sets and add the JMS transport policy to
them. For example: JMSServiceClient1Policy and JMSServiceClient2Policy
- Click .
- Enter the name of the new application policy set, JMSServiceClient1Policy.
- From the Policies collection, click .
- Click and to save your changes to
the master configuration.
- Repeat these steps to create the JMSServiceClient2Policy.
- 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.
- Click .
- From the Policies collection, click .
- From the JMS transport policy configuration panel, specify 180 seconds
for the request timeout value.
- Click and to save your changes to
the master configuration.
- Click .
- From the Policies collection, click .
- From the JMS transport policy configuration panel, specify 300
seconds for the request timeout value.
- Click and to save your changes to
the master configuration.
- Attach the custom JMS transport policy, JMSServiceClient1Policy,
to your application, ServiceClient1. Similarly, attach the custom
JMS transport policy, JMSServiceClient2Policy, to ServiceClient2.
- Click ServiceClient1.
- From the Policy set attachments collection, select the service, ServiceClient1.
- Click , and click JMSServiceClient1Policy.
- Click to
save your changes to the master configuration.
- Click ServiceClient2.
- From the Policy set attachments collection, select the service, ServiceClient1.
- Click , and click JMSServiceClient2Policy.
- Click to
save your 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
You can customize other policies that you might need for
your application.