1. Developing JAX-WS Web Services for Oracle WebLogic Server
  2. Developing Advanced Features of JAX-WS Web Services
  3. Using SOAP Over JMS Transport

17 Using SOAP Over JMS Transport

This chapter describes how to use SOAP over Java Messaging Service (JMS) transport as the connection protocol for WebLogic web services using Java API for XML Web Services (JAX-WS).

Note:

SOAP over JMS transport is not compatible with the following web service features: reliable messaging and HTTP transport-specific security.

This chapter includes the following sections:

Overview of SOAP Over JMS Transport

Typically, web services and clients communicate using SOAP over HTTP/S as the connection protocol. You can, however, configure a WebLogic web service so that client applications use JMS as the transport.

Using SOAP over JMS transport, web services and clients communicate using JMS destinations instead of HTTP connections, offering the following benefits:

  • Reliability

  • Scalability

  • Quality of service

As with web service reliable messaging, if WebLogic Server goes down while the method invocation is still in the queue, it will be handled as soon as WebLogic Server is restarted. When a client invokes a web service, the client does not wait for a response, and the execution of the client can continue. Using SOAP over JMS transport does require slightly more overhead and programming complexity than HTTP/S.

For each transport that you specify, WebLogic Server generates an additional port in the WSDL. For this reason, if you want to give client applications a choice of transports they can use when they invoke the web service (JMS, HTTP, or HTTPS), you should explicitly configure each transport. You configure transports using JWS annotations or child elements of the jwsc Ant task.

If you configure JMS transport only, although you cannot invoke the web service using HTTP, you can view its WSDL using HTTP, which is how the clientgen is still able to generate JAX-WS stubs for the web service.

Note:

Using JMS transport is a WebLogic feature; non-WebLogic client applications, such as a .NET client, may not be able to invoke the web service using the JMS port.

Figure 17-1 shows the flow of request and response messages for a web service invocation using SOAP over JMS transport.

  • The client stub invokes the web service and sends the SOAP request message to the web service via the JMS request queue, and then waits for the response.

  • On the server side, the MDB listener receives the request and invokes the service endpoint.

  • Once processed, the service endpoint sends the response to the JMS response queue.

  • The JMS listener on the client side receives the response and passes it to the client.

  • The JMS response endpoint and listener are removed when the client issues the java.io.Closable.close() command.

Figure 17-1 Web Service Invocation Using SOAP Over JMS Transport

Description of Figure 17-1 follows
Description of "Figure 17-1 Web Service Invocation Using SOAP Over JMS Transport"

Figure 17-2 shows the flow of request and response messages for an asynchronous web service invocation using SOAP over JMS transport.

  • The client stub invokes the web service asynchronously and sends the SOAP request message to the web service via the JMS request queue. The client stub returns a javax.xml.ws.Response or java.util.concurrent.Future<T> instance, and does not wait for the response.

  • On the server side, the MDB listener receives the request and invokes the service endpoint.

  • Once processed, the service endpoint sends the response to the JMS response queue.

  • The JMS listener invokes the response endpoint which populates the Response or Future<T> instance for the client.

  • The JMS response endpoint and listener are removed when the client issues the java.io.Closable.close() command.

Figure 17-2 Asynchronous Web Service Invocation Using SOAP Over JMS Transport

Description of Figure 17-2 follows
Description of "Figure 17-2 Asynchronous Web Service Invocation Using SOAP Over JMS Transport"

Before sending the request message to the JMS destination, the client sets the JMS message properties defined in Table 17-1.

Table 17-1 JMS Message Properties Defined in the Request Message

JMS Message Property Description

SOAPJMS_bindingVersion

Version of the SOAP JMS binding. This value must be set to 1.0 for this release.

SOAPJMS_contentType

MIME content type of the message

SOAPJMS_requestURI

JMS request URI. For more information about how the value is configured, see Configuring the JMS Request URI.

SOAPJMS_soapAction

SOAP action which defines the intent of the request.

SOAPJMS_targetService

Port component name of the web service.

messageType

Message type to use with the request message. A value of BYTES indicates the com.oracle.webservices.api.jms.JMSMessageType.BYTES object is used. A value of TEXT indicates com.oracle.webservices.api.jms.JMSMessageType.TEXT object is used. This value defaults to BYTES.

JMSMessageID

ID that uniquely identifies the JMS message and that is used to correlate the response message with the request. The JMSCorrelationID property of the response message must match the JMSMessageID of the request message.

ECIDContext

Execution Context Identifier (ECID), wrapper code, and encoding details. This content is similar to what is provided for the HTTP header, and is required for the client only.

Before sending the response message to the JMS destination, the service sets the JMS message properties defined in Table 17-1.

Table 17-2 JMS Message Properties Defined in the Response Message

JMS Message Property Description

SOAPJMS_bindingVersion

Version of the SOAP JMS binding. This value must be set to 1.0 for this release.

SOAPJMS_contentType

MIME content type of the message

JMSCorrelationID

ID used to correlate the request and response messages. The JMSCorrelationID must match the JMSMessageID of the request message.

JMSMessageID

ID that uniquely identifies the JMS message and that is used to correlate the response message with the request.

Configuring the WebLogic Server Domain for JMS Transport

Table 17-3 lists the default resources used by JMS transport in your WebLogic Server domain, by default.

Table 17-3 Default Resources Used by JMS Transport

Resource Name (Default) Resource Type Description

WseeSoapjmsJmsServer

JMS server

JMS server management container.

To configure the JMS server manually, see JMS Configuration in Administering JMS Resources for Oracle WebLogic Server.

WseeSoapjmsFileStore

File store

File store, or physical store, used by the WebLogic Server to handle the I/O operations to save and retrieve data from the physical storage (such as file, DBMS, and so on).

To configure the file stores manually, see Using Custom File Stores in Administering the WebLogic Persistent Store.

WseeSoapjmsJmsModule

JMS Module

JMS module that defines the JMS resources needed for SOAP over JMS transport.

To configure the JMS module manually, see JMS Configuration in Administering JMS Resources for Oracle WebLogic Server.

WseeSoapjmsJmsServerSub

JMS subdeployment

JMS subdeployment for targeting the JMS resources to the WseeSoapJmsServer.

To configure the JMS subdeployment manually, see JMS Configuration in Administering JMS Resources for Oracle WebLogic Server.

com.oracle.webservices.api.jms.ConnectionFactory

JMS Connection Factory

Default JMS connection factory used to create connections for SOAP over JMS transport.

You can configure a different connection factory using the jndiConnectionFactoryName JMS transport property, as described in Configuring JMS Transport Properties.

com.oracle.webservices.api.jms.RequestQueue

JMS Queue

Default JMS request queue.

You can configure a different JMS request queue using the destinationName JMS transport property, as described in Configuring JMS Transport Properties.

com.oracle.webservices.api.jms.ResponseQueue

JMS Queue

Default JMS response queue.

You can configure a different JMS response queue, as described in Configuring the JMS Response Queue.

When creating or extending a domain, you can apply the WebLogic JAX-WS SOAP/JMS Extension template (wls_webservice_soapjms.jar) to configure automatically the JMS resources required to support JMS transport.

To configure automatically the JMS resources required to support JMS transport, use one of the following methods:

  • Use the Configuration Wizard to create or extend a domain, as described in Creating a WebLogic Domain in the Creating WebLogic Domains Using the Configuration Wizard. When prompted to specify a template to use to create or extend the domain, select the WebLogic JAX-WS SOAP/JMS Extension template.

  • Use WLST to extend a domain, using the wls_webservice_soapjms.jar extension template JAR file, as described in Editing a WebLogic Domain (Offline) in Understanding the WebLogic Scripting Tool.

Although use of this extension template is not required, it makes the configuration of the required resources much easier. Alternatively, you can manually configure the resources required using the Oracle WebLogic Server Administration Console or WLST.

To configure manually the resources required to support JMS transport, use one of the following methods:

  • Use the WebLogic Server Administration Console to create the resources, as described in Table 17-3. For more information, see JMS Configuration in Administering JMS Resources for Oracle WebLogic Server.

  • Use WLST to create the resources defined in Table 17-3. For more information, see Creating Existing WebLogic Domains in Understanding the WebLogic Scripting Tool.

Developing Web Services Using JMS Transport—Starting From Java

To use JMS transport for web services when starting from Java, you must perform at least one of the following tasks:

  • Add the @com.oracle.webservices.api.jms.JMSTransportService annotation to your JWS file.

  • Add a <jmstransportservice> child element in the <jws> element of the jwsc Ant task. This setting overrides the transports defined in the JWS file.

The following procedure describes the complete set of steps required so that your web service can be invoked using the JMS transport when starting from Java.

Table 17-4 Steps to Develop Web Services With JMS Transport—Starting From Java

# Step Description

1

Complete the prerequisites.

It is assumed that you have created a basic JWS file that implements a web service and that you want to configure the web service to be invoked using JMS transport

It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes targets for running the jwsc Ant task and deploying the service.

For more information, see Developing JAX-WS Web Services.

2

Configure the WebLogic Server domain for the required JMS components.

See Configuring the WebLogic Server Domain for JMS Transport.

3

Add the @com.oracle.webservices.api.jms.JMSTransportService annotation to your JWS file. (Optional)

This step is optional. If you do not add the @JMSTransportService annotation to your JWS file, then you must add a <jmstransportservice> child element in the <jws> element of the jwsc Ant task, as described in Step 4.

See Using the @JMSTransportService Annotation.

4

Add a <jmstransportservice> child element to the jwsc Ant task. (Optional)

Use the <jmstransportservice> child element to override the transports defined in the JWS file.

This step is required if you did not add the @JmsTransportService annotation to your JWS file in Step 3. Otherwise, this step is optional.

See Using the <jmstransportservice> Child Element in the Ant build.xml File for details.

5

Build your web service by running the target in the build.xml Ant file that calls the jwsc task.

For example, if the target that calls the jwsc Ant task is called build-service, then you would run:

prompt> ant build-service

See Running the jwsc WebLogic Web Services Ant Task.

6

Deploy your web service to WebLogic Server.

See Deploying and Undeploying WebLogic Web Services.

See Invoking a WebLogic Web Service Using JMS Transport for information about updating your client application to invoke the web service using JMS transport.

Using the @JMSTransportService Annotation

If you know at the time that you program the JWS file that you want client applications to use JMS transport (instead of HTTP/S) to invoke the web service, you can use the @com.oracle.webservices.api.jms.JMSTransportService annotation to specify the details of the invocation.

You can include only one @JMSTransportService annotation in a JWS file.

Optionally, you can configure the destination name, connection factory, delivery mode, and other JMS transport properties using the @JMSTransportService annotation. For more information, see Configuring JMS Transport Properties.

Later, at build-time, you can override the invocation defined in the JWS file and add additional JMS transport specifications, by specifying the <jmstransportservice> child element in the <jws> element of "jwsc" jwsc Ant task, as described in Using the <jmstransportservice> Child Element in the Ant build.xml File.

Example 17-1 shows an excerpt from a JWS file, implemented as a stateless EJB, that uses the @JMSTransportService annotation, with the relevant code in bold.

Example 17-1 Enabling JMS Transport for a Stateless EJB Using @JMSTransportService Annotation

package jaxws.ejb;
...
import javax.ejb.Stateless;
import javax.jws.WebService;
import com.oracle.webservices.api.jms.JMSTransportService;
 
@WebService(name = "Simple", targetNamespace = "http://example.org")
@JMSTransportService(
  targetService="SimpleEjbService",
  destinationName="com.oracle.webservices.api.jms.RequestQueue",
  jndiConnectionFactoryName="weblogic.jms.ConnectionFactory",
  mdbPerDestination=false,
  activationConfig=("transAttribute=Never;maxBeansInFreePool=1000;
                     dispatchPolicy=weblogic.wsee.jaxws.mdb.DispatchPolicy"
  )
@Stateless
public class SimpleEjb { ... }

Example 17-2 shows an excerpt from a provider-based web service that uses the @JMSTransportService annotation, with the relevant code in bold.

Example 17-2 Enabling JMS Transport for a Provider-based Web Service Using @JMSTransportService Annotation

package examples.webservices.jaxws;
...
import javax.xml.transform.Source;
import javax.xml.ws.Provider;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;
import javax.xml.ws.Service;
import java.io.ByteArrayInputStream;
import com.oracle.webservices.api.jms.JMSTransportService;

@ServiceMode(value=Service.Mode.PAYLOAD)
@WebServiceProvider(portName="WarehouseServicePort", 
                    serviceName="WarehouseService",targetNamespace="http://examples.org/")
@JMSTransportService(destinationName="myQueue")
public class WarehouseServiceImpl implements Provider<Source> {
 
    public Source invoke(Source source) { ... }
}

Using the <jmstransportservice> Child Element in the Ant build.xml File

You can specify the JMS transport at build-time by adding the <jmstransportservice> child element in the <jws> element of the jwsc Ant task. You may want to configure JMS transport at build-time for one of the following reasons:

  • You want to override the attribute values specified in the JWS file using the @JMSTransportService annotation.

  • The JWS file does not include a @JMSTransportService annotation and you determine at build-time that you want clients to use the JMS transport to invoke the web service.

The <jmstransportservice> child element of the jwsc Ant task takes precedence over the @JMSTransportService transport annotation in the JWS file.

Optionally, you can configure the destination name, destination type, delivery mode, and other JMS transport properties, using the <jmstransportservice> element. For a complete list of JMS transport properties supported, see Configuring JMS Transport Properties.

Example 17-3 shows an excerpt from a build.xml file that shows how to enable and configure JMS transport using the <jmstransportservice> child element in the <jws> element of the jwsc Ant task. The relevant code is shown in bold.

Example 17-3 Enabling JMS Transport Using the <jmstransportservice> Child Element

<?xml version="1.0"?>
<project name="jaxws.jms.jwsc" default="all">
   <import file="../build-jms.xml"/>
      <path id="client.class.path">
         <pathelement path="${clientclasses.dir}"/>
         <pathelement path="${java.class.path}"/>
      </path>
   <target name="jwsc">
      <jwsc srcdir="." sourcepath="client" destdir="${output.dir}" debug="on" 
            keepGenerated="yes">
         <jws file="JWSCEndpoint.java" type="JAXWS" explode="true">
            <jmstransportservice
               targetService="JWSCEndpointService"
               destinationName="com.oracle.webservices.api.jms.RequestQueue"
               jndiInitialContextFactory="weblogic.jndi.WLInitialContextFactory"
               jndiConnectionFactoryName="weblogic.jms.XAConnectionFactory"
               jndiURL="t3://localhost:7001"
               deliveryMode=com.oracle.webservices.api.jms.JMSDeliveryMode.PERSISTENT
               timeToLive=60000
               priority=1
               messageType=com.oracle.webservices.api.jms.JMSMessageType.BYTES
               activationConfig = "transAttribute=Supports"
            />
      </jws>
   </jwsc>
</target>
</project>

For more information about using the jwsc Ant task, see jwsc in WebLogic Web Services Reference for Oracle WebLogic Server.

Developing Web Services Using JMS Transport—Starting From WSDL

To use JMS transport for web services when starting from WSDL, you must perform at least one of the following tasks:

  • Update the WSDL to use JMS transport before running the wsdlc Ant task.

  • Update the stubbed-out JWS implementation file generated by the wsdlc Ant task to add the @com.oracle.webservices.api.jms.JMSTransportService annotation.

  • Add a <jmstransportservice> child element in the <jws> element of the jwsc Ant task used to build the JWS implementation file. This setting overrides the transports defined in the JWS file.

The following procedure describes the complete set of steps required so that your web service can be invoked using the JMS transport when starting from WSDL.

Table 17-5 Steps to Developing Web Services With JMS Transport—Starting From WSDL

# Step Description

1

Complete the prerequisites.

It is assumed in this procedure that you have an existing WSDL file.

2

Configure the WebLogic Server domain for the required JMS components.

See Configuring the WebLogic Server Domain for JMS Transport.

3

Update the WSDL to use JMS transport. (Optional)

This step is optional. If you do not update the WSDL to use JMS transport, then you must do at least one of the following:

  • Edit the stubbed out JWS file to add the @JMSTransportService annotation to your JWS file, as described in Step 5.

  • Add a <jmstransportservice> child element in the <jws> element of the jwsc Ant task, as described in Step 7.

See Updating the WSDL to Use JMS Transport.

4

Run the wsdlc Ant task against the WSDL file.

For example, if the target that calls the wsdlc Ant task is called generate-from-wsdl, then you would run:

prompt> ant generate-from-wsdl

See Running the wsdlc WebLogic Web Services Ant Task.

5

Update the stubbed-out JWS file.

The wsdlc Ant task generates a stubbed-out JWS file. You need to add your business code to the web service so it behaves as you want. See Updating the Stubbed-out JWS Implementation Class File Generated By wsdlc.

If you updated the WSDL to use the JMS transport in Step 3, the JWS file includes the @JMSTransportService annotation that defines the JMS transport. If the @JMSTransportService annotation is not included in the JWS file, you must do at least one of the following:

  • Edit the JWS file to add the @JMSTransportService annotation to your JWS file, as described in Using the @JMSTransportService Annotation.

  • Add a <jmstransportservice> child element in the <jws> element of the jwsc Ant task, as described in Step 7.

6

Add a <jmstransportservice> child element to the jwsc Ant task. (Optional)

Use the <jmstransportservice> child element to override the transports defined in the JWS file. This step is required if the JWS file does not include the @JMSTransportService annotation, as noted in Step 5. Otherwise, this step is optional.

See Using the <jmstransportservice> Child Element in the Ant build.xml File for details.

7

Run the jwsc Ant task against the JWS file to build the web service.

Specify the artifacts generated by the wsdlc Ant task as well as your updated JWS implementation file, to generate an Enterprise Application that implements the web service.

See Running the jwsc WebLogic Web Services Ant Task.

8

Deploy the web service to WebLogic Server.

See Deploying and Undeploying WebLogic Web Services.

See Invoking a WebLogic Web Service Using JMS Transport for information about updating your client application to invoke the web service using JMS transport.

Updating the WSDL to Use JMS Transport

To update the WSDL to use JMS transport, you need to add the <wsdl:binding> definition that defines JMS transport information. You can add the definition in one of the following ways, depending on whether you want to specify multiple transport options:

  • Edit the existing HTTP <wsdl:binding> definition.

  • To specify multiple transport options in the WSDL (such as HTTP and JMS transport), copy the existing HTTP <wsdl:binding> definition and edit it to use JMS transport.

Optionally, you can configure JMS transport properties at the binding or JMS URI level.

The following sections describe how to update the WSDL to use JMS transport:

Enabling JMS Transport at the WSDL Binding Level

To enable JMS transport at the WSDL binding level, set the transport attribute of the <soapwsdl:binding> child element of the <wsdl:binding> element to http://www.w3.org/2010/soapjms.

Optionally, you can configure JMS transport properties within the <wsdl:binding> element definition, as described in Configuring JMS Transport Properties in the WSDL.

Example 17-4 provides an example of the <wsdl:binding> element for JMS transport. In this example, an HTTP binding is also defined.

Example 17-4 Enabling JMS Transport at the WSDL Binding Level

...
<binding xmlns:soapjms="http://www.w3.org/2010/soapjms/" 
     name="AddNumbersJMSBinding" type="tns:AddNumbersPortType">
    <soap:binding transport="http://www.w3.org/2010/soapjms/" style="document" />
    <operation name="addNumbers">
        <soap:operation soapAction="" />
            <input>
                <soap:body use="literal" />
            </input>
            <output>
                <soap:body use="literal" />
             </output>
    </operation>
</binding>
<binding name="AddNumbersSOAPBinding" type="tns:AddNumbersPortType">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
     ...
</binding>
...
Configuring JMS Transport Properties in the WSDL

Optionally, you can configure a subset of JMS transport properties within the following WSDL elements:

  • <wsdl:binding> element—Propagates to all ports using the binding.

  • <wsdl:service> element—Propagates to all ports.

  • <wsdl:port> element—Used only by the port.

  • JMS URI, as described in Configuring the JMS URI.

Specifically, you can configure the following JMS transport properties in the WSDL. For a description of the properties, see Table 17-6.

  • deliveryMode

  • jndiConnectionFactoryName

  • jndiContextParameters

  • jndiInitialContextFactory

  • jndiURL

  • priority

  • replyToName

  • timeToLive

Example 17-5 provides an example of the <wsdl:binding> element with JMS transport properties defined. In this case, the JMS transport properties propagate to all ports that use the binding.

Example 17-5 Configuring JMS Transport Properties in the WSDL

...
<binding xmlns:soapjms="http://www.w3.org/2010/soapjms/" 
     name="AddNumbersBinding" type="tns:AddNumbersPortType">
   <soap:binding transport="http://www.w3.org/2010/soapjms/" 
                 style="document" />
      <soapjms:jndiInitialContextFactory>
         weblogic.jndi.WLInitialContextFactory
      </soapjms:jndiInitialContextFactory>
      <soapjms:jndiConnectionFactoryName>
         weblogic.jms.XAConnectionFactory 
      </soapjms:jndiConnectionFactoryName>
      <soapjms:bindingVersion>1.0</soapjms:bindingVersion>
      <soapjms:destinationName>
         com.oracle.webservices.api.jms.RequestQueue 
      </soapjms:destinationName>
      <soapjms:targetService>AddNumbersService</soapjms:targetService>
      <soapjms:deliveryMode>
         com.oracle.webservices.api.jms.JMSDeliveryMode.PERSISTENT
      </soapjms:deliveryMode>
      <soapjms:priority>0</soapjms:priority>
      <soapjms:messageType>
         com.oracle.webservices.api.jms.JMSMessageType.BYTES
      </soapjms:messageType>
      <soapjms:destinationType>
         com.oracle.webservices.api.jms.JMSDestinationType.QUEUE
      </soapjms:destinationType>
            <operation name="addNumbers">
               <soap:operation soapAction="" />
                  <input>
                     <soap:body use="literal" />
                  </input>
                  <output>
                     <soap:body use="literal" />
                  </output>
                </operation>
</binding>
...
Example of Enabling JMS Transport in WSDL

Example 17-6 provides an example of a WSDL that is configured for SOAP over JMS transport.

Example 17-6 Enabling JMS Transport in WSDL

<?xml version="1.0" encoding="UTF-8"?>
 
<definitions
   name="AddNumbers"
   targetNamespace="http://example.org"
   xmlns:tns="http://example.org"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
   <types>
      <xsd:schema
         xmlns="http://www.w3.org/2001/XMLSchema"
         targetNamespace="http://example.org"
         elementFormDefault="qualified">
 
         <complexType name="addNumbersResponse"
            <sequence>
               <element name="return" type="xsd:int" />
            </sequence>
         </complexType>
         <element name="addNumbersResponse" type="tns:addNumbersResponse"/>
 
         <complexType name="addNumbers">
            <sequence>
               <element name="arg0" type="xsd:int" />
               <element name="arg1" type="xsd:int" />
            </sequence>
         </complexType>
         <element name="addNumbers" type="tns:addNumbers"/>
      </xsd:schema>
   </types>
   <message name="addNumbers">
      <part name="parameters" element="tns:addNumbers" />
   </message>
   <message name="addNumbersResponse">
      <part name="result" element="tns:addNumbersResponse" />
   </message>
   <portType name="AddNumbersPortType">
      <operation name="addNumbers">
         <input message="tns:addNumbers" />
         <output message="tns:addNumbersResponse" />
      </operation>
   </portType>
         <binding xmlns:soapjms="http://www.w3.org/2010/soapjms/" name="AddNumbersBinding" 
            type="tns:AddNumbersPortType">
            <soap:binding transport="http://www.w3.org/2010/soapjms/" style="document" />
            <soapjms:jndiInitialContextFactory>weblogic.jndi.WLInitialContextFactory
            </soapjms:jndiInitialContextFactory>
            <soapjms:jndiConnectionFactoryName>weblogic.jms.XAConnectionFactory 
            </soapjms:jndiConnectionFactoryName>
            <soapjms:bindingVersion>1.0</soapjms:bindingVersion>
            <soapjms:destinationName>com.oracle.webservices.api.jms.RequestQueue 
            </soapjms:destinationName>
            <soapjms:targetService>AddNumbersService</soapjms:targetService>
            <soapjms:deliveryMode>com.oracle.webservices.api.jms.JMSDeliveryMode.PERSISTENT
            </soapjms:deliveryMode>
            <soapjms:priority>0</soapjms:priority>
            <soapjms:messageType>com.oracle.webservices.api.jms.JMSMessageType.BYTES
            </soapjms:messageType>
            <soapjms:destinationType>com.oracle.webservices.api.jms.JMSDestinationType.QUEUE
            </soapjms:destinationType>
               <operation name="addNumbers">
                  <soap:operation soapAction="" />
                     <input>
                        <soap:body use="literal" />
                     </input>
                     <output>
                        <soap:body use="literal" />
                     </output>
                   </operation>
      </binding>
      <service name="AddNumbersService">
         <port name="AddNumbersPort" binding="tns:AddNumbersBinding">
            <soap:address location="jms:jndi:com.oracle.webservices.api.jms.RequestQueue?targetService=AddNumbersService&amp;jndiInitialContextFactory=weblogic.jndi.WLInitialContextFactory&amp;jndiConnectionFactoryName=weblogic.jms.XAConnectionFactory"/>
 
      </port>
   </service>
</definitions>

Invoking a WebLogic Web Service Using JMS Transport

You write a client application to invoke a web service using JMS transport in the same way as you write one using the HTTP transport. In the case of JMS transport, the client sends SOAP request messages to the JMS request destination and receives SOAP response messages from the JMS response destination. For examples of invoking a web service, see Examples of Developing JAX-WS Web Service Clients.

You enable and optionally configure JMS transport on the web service client using one of the following methods:

Using the <jmstransportclient> Element in the Ant build.xml File

The clientgen tool generates a JMS transport client proxy from a WSDL file containing a JMS transport binding. When generating the client proxy using clientgen, you can enable JMS transport by adding the <jmstransportclient> element in clientgen Ant task.

Note:

Although you cannot invoke a JMS-transport-configured web service using HTTP, you can view its WSDL using HTTP, which is how the clientgen Ant task is still able to create the JAX-WS artifacts for the web service.

Optionally, you can configure the destination name, destination type, delivery mode, request and response queues, and other JMS transport properties, using the <jmstransportclient> element. For a complete list of JMS transport properties supported, see Configuring JMS Transport Properties.

Example 17-7 shows an excerpt from a build.xml file that shows how to enable and configure JMS transport using the <jmstransportclient> element of the clientgen Ant task. The relevant code is shown in bold.

Example 17-7 Using the <jmstransportclient> Element in the Ant build.xml File

<target name="clientgen">
<clientgen
      wsdl="./WarehouseService.wsdl"
      destDir="clientclasses"
      packageName="client.warehouse"
      type="JAXWS">
      <jmstransportclient
                targetService="JWSCEndpointService"
                destinationName="com.oracle.webservices.api.jms.RequestQueue"
                jndiInitialContextFactory="weblogic.jndi.WLInitialContextFactory"
                jndiConnectionFactoryName="weblogic.jms.ConnectionFactory"
                jndiURL="t3://localhost:7001"
                timeToLive=60000
                priority=1
                messageType=com.oracle.webservices.api.jms.JMSMessageType.TEXT
                replyToName="com.oracle.webservices.api.jms.ResponseQueue"
     />
</clientgen>

For more information about using the clientgen Ant task, see clientgen in WebLogic Web Services Reference for Oracle WebLogic Server.

Using the @JMSTransportClient Annotation

When you run clientgen to generate the web service client artifacts from the WSDL file, the @com.oracle.webservices.api.jms.JMSTransportClient annotation is included automatically to the generated client proxy if JMS transport is enabled in the build file using the <jmstransportclient> element, as described in Using the <jmstransportclient> Element in the Ant build.xml File.

If the @JMSTransportClient annotation is not configured automatically through clientgen, you can add it to the file manually.

Optionally, you can configure the following JMS transport properties using the @JMSTransportClient annotation. For a description of the properties, see Table 17-6.

  • destinationName

  • destinationType

  • enabled

  • jmsMessageHeader

  • jmsMessageProperty

  • jndiConnectionFactoryName

  • jndiContextParameters

  • jndiInitialContextFactory

  • jndiURL

  • messageType

  • priority

  • replyToName

  • targetService

  • timeToLive

Example 17-8 shows an excerpt from a client file that uses the @JMSTransportClient annotation, with the relevant code in bold.

Example 17-8 Enabling JMS Transport for a Client Proxy Using the @JMSTransportClient Annotation

...
import javax.xml.ws.WebServiceClient;
import com.oracle.webservices.api.jms.JMSTransportClient;
...
@WebServiceClient(name = "WarehouseService", targetNamespace = "http://oracle.com/samples/", 
                  wsdlLocation="WarehouseService.wsdl")
@JMSTransportClient (
    destinationName="myQueue", 
    replyToName="myReplyToQueue",
    jndiURL="t3://localhost:7001",
    jndiInitialContextFactory="weblogic.jndi.WLInitialContextFactory" , 
    jndiConnectionFactoryName="weblogic.jms.ConnectionFactory" , 
    timeToLive=1000, priority=1,
    messageType=com.oracle.webservices.api.jms.JMSMessageType.TEXT
)

public class WarehouseService  extends Service { ... }

Using the JMSTransportClientFeature Client API

You can use the com.oracle.webservices.api.jms.JMSTransportClientFeature client API to configure JMS transport in the web service client.

Optionally, you can configure the following JMS transport properties using the com.oracle.webservices.api.jms.JMSTransportClientFeature. For a description of the properties, see Table 17-6.

  • destinationName

  • destinationType

  • enabled

  • jmsMessageHeader

  • jmsMessageProperty

  • jndiConnectionFactoryName

  • jndiContextParameters

  • jndiInitialContextFactory

  • jndiURL

  • messageType

  • priority

  • replyToName

  • targetService

  • timeToLive

Example 17-9 shows an excerpt from a Web client that uses JMSTransportClientFeature, with the relevant code in bold.

Example 17-9 Enabling JMS Transport for a Client Proxy Using JMSTransportClientFeature

...
import javax.xml.namespace.QName;
import java.net.URL;
import com.oracle.webservices.api.jms.JMSTransportClientFeature;
...
URL url = new URL("http://localhost:7001/WarehouseServicePort/WarehouseService?WSDL");
QName serviceName = new QName("http://www.oracle.com/samples/", "WarehouseService");
WarehouseService service = new WarehouseService (url, serviceName);
JMSTransportClientFeature feature = 
JMSTransportClientFeature.builder().jndiInitialContextFactory("weblogic.jndi.WLInitialContextFactory").jndiURL("t3://localhost:7001").build();  
port = service.getWarehouseShipmentsPort(new WebServiceFeature[]{feature});
Item item = new Item();
item.setProductNumber(10001);
item.setQuantity(100);
port.shipGoods(item, "BEA");
...

Example 17-10 shows an excerpt from a Dispatch client that uses JMSTransportClientFeature, with the relevant code in bold.

Example 17-10 Enabling JMS Transport for a Dispatch Client Using JMSTransportClientFeature

...
import javax.xml.namespace.QName;
import java.net.URL;
import javax.xml.bind.JAXBContext;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.Dispatch;
import com.oracle.webservices.api.jms.JMSTransportClientFeature;
...
Service service = Service.create(new URL(wsdl), new QName(nameSpace, serviceName));
JAXBContext jaxbContext = JAXBContext.newInstance(ObjectFactory.class);
JMSTransportClientFeature feature = 
JMSTransportClientFeature.builder().jndiURL("t3://adc2170585:7003").build();  
Dispatch dispatch =
      service.createDispatch(new QName(nameSpace, "WarehouseServicePort"), jaxbContext,
      Service.Mode.PAYLOAD, new WebServiceFeature[]{feature});
...

Configuring the JMS URI as the Target Endpoint Address

You can specify the JMS URI as the target endpoint address for the client binding to enable and configure JMS transport in the web service client. For information about constructing the JMS URI, see Configuring the JMS URI.

Example 17-11 shows an excerpt from a Web client that sets the target endpoint address to the JMS URI with the relevant code in bold. In this example, if the replyToName had been configured using JMSTransportClientFeature, it would take precedence over the target endpoint address value.

Example 17-11 Enabling JMS Transport for a Client Proxy Using JMS URI

...
import javax.xml.namespace.QName;
import java.net.URL;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.MessageContext;
import com.oracle.webservices.api.jms.JMSTransportClientFeature;
...
URL url = new URL("http://localhost:7001/WarehouseServicePort/WarehouseService?WSDL");
QName serviceName = new QName("http://www.oracle.com/samples/", "WarehouseService");
WarehouseService service = new WarehouseService (url, serviceName);
JMSTransportClientFeature feature = new JMSTransportClientFeature().build();
feature.setJndiInitialContextFactory ("weblogic.jndi.WLInitialContextFactory");
feature.setJndiUrl("t3://localhost:7001");
port = service.getWarehouseShipmentsPort(new WebServiceFeature[]{feature});
BindingProvider bp = (BindingProvider) port;
bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, 
     "jms:jndi:myQueue?targetService=WarehouseService&replyToName=myReplyToQueue");
Item item = new Item();
item.setProductNumber(10001);
item.setQuantity(100);
port.shipGoods(item, "BEA");
...

Example 17-12 shows an excerpt from a Dispatch client that uses JMSTransportClientFeature, with the relevant code in bold. In this example, the JMS transport properties specified in the JMSTransportClientFeature take precedence over the JMS URI.

Example 17-12 Example of Enabling JMS Transport for a Dispatch Client Using JMS URI

...
String uri = "jms:jndi:myQueue?targetService=WarehouseService&jndiConnectionFactoryName=weblogic.jms.ConnectionFactory&jndiURL=t3://adc2170585:7003&jndiInitialContextFactory=weblogic.jndi.WLInitialContextFactory";
Service service = Service.create(new URL(wsdl), new QName(nameSpace, serviceName));
JAXBContext jaxbContext = JAXBContext.newInstance(ObjectFactory.class);
JMSTransportClientFeature feature = new JMSTransportClientFeature().build();
feature.setJndiUrl("t3://adc2170585:7003");
 
Dispatch dispatch =
      service.createDispatch(new QName(nameSpace, "WarehouseServicePort"), jaxbContext,
      Service.Mode.PAYLOAD, new WebServiceFeature[]{feature});
 
dispatch.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, uri );
...

Using AsyncClientTransportFeature to Configure Asynchronous Clients

The asynchronous client transport feature, described in Developing Scalable Asynchronous JAX-WS Clients (Asynchronous Client Transport), provides a scalable asynchronous client programming model.

To enable SOAP over JMS transport for an asynchronous client:

  1. Specify the JMS URI as the target endpoint address for the client binding. For information about constructing the JMS URI, see Configuring the JMS URI.

    Note:

    When using JMS transport, the context path of the asynchronous response endpoint is ignored if specified using AsyncClientTransportFeature.

  2. Optionally, configure a permanent response queue by configuring the address or ReplyTo header using the AsyncClientTransportFeature, as described in Enabling and Configuring the Asynchronous Client Transport Feature.

    If you do not configure the address of the JMS response queue or if the destinationName property is set to anonymous (which is not supported by JMS transport), then a temporary response queue is used. For more information about configuring the JMS response queue, see Configuring the JMS Response Queue.

Example 17-13 Example of Enabling JMS Transport and Configuring Permanent Queue for an Asynchronous Client

...
WarehouseService service = new WarehouseService(url, serviceName);
AsyncClientTransportFeature replyTo = new AsyncClientTransportFeature (
                            "jms:jndi:myReplyToQueue?targetService=WarehouseService");
AsyncClientTransportFeature faultTo = new AsyncClientTransportFeature (
                            "jms:jndi:myFaultToQueue?targetService=WarehouseService");
AsyncClientTransportFeature callbackFeature =  new AsyncClientTransportFeature (
               replyTo.getEndpointReference(W3CEndpointReference.class), 
               faultTo.getEndpointReference(W3CEndpointReference.class));
port = service.getWarehouseServicePort(new WebServiceFeature[] { callbackFeature });
status = port.shipGoods(item, "BEAN");
(BindingProvider) port.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, 
                  "jms:jndi:myQueue?targetService=WarehouseService");
((Closable)port).close();
...

When the endpoint is invoked, the client runtime environment publishes the response endpoint and deploys the JMS listener on the response JMS queue. Once attached to the client, the AsyncClientTransportFeature instance determines the response endpoint of all client invocations; the replyToName property in the target endpoint address and JMSTransportClientFeature are ignored.

Example 17-13 shows an excerpt from an asynchronous client that uses AsyncClientTransportFeature, with the relevant code in bold. In this example, the replyTo and faultTo addresses are defined and passed to the client.

Configuring JMS Transport Properties

Optionally, you can configure JMS transport properties when enabling JMS transport, as described in the following sections:

Summary of JMS Transport Configuration Properties

Table 17-6 lists the JMS transport properties that can be configured and the supported configuration methods, defined in Table 17-7.

Table 17-6 Summary of JMS Transport Configuration Properties

Name Description Supported Configuration Methods

activationConfig

Activation configuration properties passed to the JMS provider. Each property is specified as name-value pairs using the following format: "name1=value1;...;nameN=valueN"

For example: "key1=value1;key2=value2"

For a list of activation configuration properties that are supported by this property, see Table 17-7.

This value defaults to: ""

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

bindingVersion

Version of the SOAP JMS binding. This value must be set to 1.0 for this release, which equates to com.oracle.webservices.api.jms.JMSBindingVersion.SOAP_JMS_1_0.

This value maps to the SOAPJMS_bindingVersion JMS message property, as defined in Table 17-1.

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

deliveryMode

Delivery mode indicating whether the request message is persistent. Valid values are com.oracle.webservices.api.jms.JMSDeliveryMode.PERSISTENT and com.oracle.webservices.api.jms.JMSDeliveryMode.NON_PERSISTENT.

This value defaults to: com.oracle.webservices.api.jms.JMSDeliveryMode.PERSISTENT

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

destinationName

JNDI name of the destination queue or topic.

This value defaults to: "com.oracle.webservices.api.jms.RequestQueue"

All configuration methods in Table 17-8

destinationType

Destination type. Valid values include: com.oracle.webservices.api.jms.JMSDestinationType.QUEUE or com.oracle.webservices.api.jms.JMSDestinationType.TOPIC.

This value defaults to: com.oracle.webservices.api.jms.JMSDestinationType.QUEUE

This value overrides the destinationType value specified as an entry in activationConfig property (as defined in Table 17-7), if applicable.

Topics are supported only for one-way communication.

All configuration methods in Table 17-8

enabled

Boolean flag that specifies whether JMS transport is enabled. This value defaults to true.

@JMSTransportService and @JMSTransportClient annotations

enableHttpWsdlAccess

Boolean flag that specifies whether to publish the WSDL through HTTP. This flag defaults to true.

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

jmsMessageHeader

JMS header properties. Each property is specified as name-value pairs using the following format: "name1=value1&...&nameN=valueN"

For example: "JMSType=car&JMSPriority=4"

This value defaults to: ""

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

  • @JMSTransportClient annotation

jmsMessageProperty

JMS message properties. Each property is specified as name-value pairs using the following format: "name1=value1&...&nameN=valueN"

For example: "JMSType=car&JMSPriority=4"

This value defaults to: ""

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

  • @JMSTransportClient annotation

jndiConnectionFactoryName

JNDI name of the connection factory that is used to establish a JMS connection.

This value defaults to: "com.oracle.webservices.api.jms.ConnectionFactory"

All configuration methods in Table 17-8

jndiContextParameter

JNDI properties. Each property is specified as name-value pairs using the following format: "name1=value1&...&nameN=valueN"

The properties are added to the java.util.Hashtable sent to the InitialContext constructor for the JNDI provider.

This value defaults to: ""

All configuration methods in Table 17-8

jndiInitialContextFactory

Name of the initial context factory class used for JNDI lookup. This value maps to the java.naming.factory.initial property.

This value defaults to: "weblogic.jndi.WLInitialContextFactory"

All configuration methods in Table 17-8

jndiURL

JNDI provider URL.

This value defaults to: "t3://localhost:7001"

This value maps to the java.naming.provider.url property.

All configuration methods in Table 17-8

lookupVariant

Method used for looking up the specified destination name. This value must be set to jndi to support JMS transport; this is the default.

None (cannot be modified)

mdbPerDestination

Boolean flag that specifies whether to create one listening message-driven bean (MDB) for each requested destination. This value defaults to true.

If set to false, one listening MDB is created for each web service port, and that MDB cannot be shared by other ports.

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

messageType

Message type to use with the request message. Valid values are com.oracle.webservices.api.jms.JMSMessageType.BYTES and com.oracle.webservices.api.jms.JMSMessageType.TEXT.

This value defaults to: com.oracle.webservices.api.jms.JMSMessageType.BYTES

For more information about configuring the message type, see Configuring the JMS Message Type.

All configuration methods in Table 17-8

priority

JMS priority associated with the request and response message. Specify this value as a positive Integer from 0, the lowest priority, to 9, the highest priority. The default value is 0.

All configuration methods in Table 17-8

replyToName

JNDI name of the JMS destination to which the response message is sent.

For a two-way operation, a temporary response queue is generated by default. Using the default temporary response queue minimizes the configuration that is required. However, in the event of a server failure, the response message may be lost.

This property enables the client to use a previously defined, "permanent" queue or topic rather than use the default temporary queue or topic, for receiving replies. For more information about configuring the JMS response queue, see Configuring the JMS Response Queue.

The value maps to the JMSReplyTo JMS header in the request message.

This value defaults to: ""

All configuration methods in Table 17-8

runAsPrincipal

Principal used to run the listening MDB.

This value defaults to: ""

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

runAsRole

Role used to run the listening MDB.

This value defaults to: ""

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

targetService

Port component name of the web service. This value is used by the service implementation to dispatch the service request. If not specified, the service name from the WSDL or @javax.jws.WebService annotation is used.

This value maps to the SOAPJMS_targetService JMS message property.

This value defaults to: ""

  • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

  • @JMSTransportService annotation

  • @JMSTransportClient annotation

timeToLive

Lifetime, in milliseconds, of the request message. A value of 0 indicates an infinite lifetime. If not specified, the JMS-defined default value of 180000L is used.

On the service side, timeToLive also specifies the expiration time for each MDB transaction.

All configuration methods in Table 17-8

The following table lists the activation properties that are supported by the activationConfig property in Table 17-6. For information about using the activation properties to tune MDBs, see Tuning Message-Driven Beans in Tuning Performance of Oracle WebLogic Server.

Table 17-7 Activation Properties Supported by the activationConfig Property

Name Description

acknowledgeMode

Acknowledgment mode that controls how the JMS provider is notified that the message was received and processed. Valid values include:

  • AUTO_ACKNOWLEDGE—Message is acknowledged immediately. This is the default.

  • DUPS_OK_ACKNOWLEDGE—Acknowledgement may be delayed, allowing duplicate messages to be received.

The acknowledgement mode is ignored if you are using container-managed transactions. (In this case, the acknowledgement is performed within the context of the transaction.)

connectionFactoryJndiName

JNDI name of the JMS connection factory that the MDB uses to create its queues and topics. This value defaults to weblogic.jms.MessageDrivenBeanConnectionFactory.

destinationJndiName

JNDI name used to associate an MDB with an actual JMS queue or topic deployed in the WebLogic Server JNDI tree.

destinationType

Type of the JMS destination. Valid values include: QUEUE and TOPIC.

dispatchPolicy

Work manager for the MDB. This value defaults to weblogic.wsee.jaxws.mdb.DispatchPolicy.

distributedDestinationConnection

Connection setting that specifies whether an MDB that accesses a WebLogic JMS distributed destination (topic or queue) in the same cluster consumes from all distributed destination members or only those members local to the current WebLogic Server instance. Valid values include:

  • LocalOnly—MDB consumes JMS distributed destinations from members local to the current WebLogic Server instance. This is the default.

  • EveryMember—MDB consumes JMS distributed destinations from all distributed destination members.

durableSubscriptionDeletion

Flag that specifies whether you want durable topic subscriptions to be automatically deleted when an MDB is undeployed or removed. This value defaults to false.

initialContextFactory

Initial context factory that the EJB container uses to create its connection factories. This value defaults to weblogic.jndi.WLInitialContextFactory.

initSuspendSeconds

Initial number of seconds to suspend an MDB's JMS connection when the EJB container detects a JMS resource outage. This value can be set to any Integer value and defaults to 5.

jmsClientId

Client ID for the MDB when it connects to a JMS destination. This value is used for durable subscriptions to JMS topics.

jmsPollingIntervalSeconds

Number of seconds between attempts by the EJB container to reconnect to a JMS destination that has become unavailable. This value can be set to any Integer value and defaults to 10.

maxBeansInFreePool

Maximum number of inactive MDBs in the free pool. This value can be set to any positive Integer value or 0. This value defaults to 1000.

maxMessagesInTransaction

Maximum number of messages that can be in a transaction for this MDB. This value can be set to any positive Integer value or 0. This value defaults to 1.

maxSuspendSeconds

Maximum number of seconds to suspend an MDB's JMS connection when the EJB container detects a JMS resource outage. This value can be set to any Integer and defaults to 60.

messageSelector

String used by a client to specify, by header field references and property references, the messages it should receive. Only messages whose header and property values match the specified selector are delivered. This value can be set to a message header or a conditional expression using message properties. This value defaults to null.

providerURL

URL provider to be used by the InitialContext, typically, host:port. This value can be any valid URL and defaults to null.

subscriptionDurability

Flag that specifies whether a JMS topic subscription is Durable or NonDurable. This value defaults to Durable.

topicMessagesDistributionMode

Distribution mode for topic messages. Valid values include: One-Copy-Per-Application, One-Copy-Per-Server, Compatibilty. This value defaults to Compatibility. For more information about the valid values, see Topic Deployment Scenarios in Developing Message-Driven Beans for Oracle WebLogic Server.

transAttribute

Transaction setting that specifies how the container must manage the transaction boundaries when delegating a method invocation to an enterprise bean's business method. Valid values include: Required, NotSupported, Supports, RequiresNew, Mandatory, and Never. This value defaults to Required. For more information about the valid values, see Using Web Services Atomic Transactions.

transTimeoutSeconds

Maximum duration for an EJB's container-initiated transactions, in seconds, after which the transaction is rolled back and the service will return a SOAP fault. This value can be set to any positive Integer or 0.

If the transaction timeout is not specified or is set to 0, the transaction timeout configured for the domain is used. If a timeout is not configured for the domain, the default is 30.

use81StylePolling

Flag that specifies whether backwards compatibility for WebLogic Server version 8.1-style polling is supported. Valid values include: True or False. This value defaults to False.

Configuration Methods and Order of Precedence

Optionally, you can configure JMS transport properties when enabling JMS transport using one of the methods defined in Table 17-8.

Table 17-8 Methods Used to Configure JMS Properties.

Configuration Methods Description

JMSTransportClientFeature API

Create the web service client and pass JMS transport properties as arguments to the weblogic.jws.jaxws.client.JmsTransportClientFeature API. For more information, see Invoking a WebLogic Web Service Using JMS Transport.

Target service endpoint address

Construct the target service endpoint address and include JMS transport properties as part of the query string. For more information, see Configuring the JMS URI.

@JMSTransportClient annotation

Create the web service client and pass JMS transport properties as attributes to the @com.oracle.webservices.api.jms.JMSTransportClient annotation in the JWS file, as described in Using the @JMSTransportClient Annotation.

@JMSTransportService annotation

Create the web service and pass JMS transport properties as attributes to the @com.oracle.webservices.api.jms.JMSTransportService annotation in the JWS file, as described in Using the @JMSTransportService Annotation.

<jmstransportclient> element of the clientgen Ant task

Build the web service including the <jmstransportclient> element in the clientgen Ant task For more information, see Using the <jmstransportclient> Element in the Ant build.xml File.

<jmstransportservice> child element in the <jws> element of the jwsc Ant task

Build the web service including the <jmstransportservice> child element in the <jws> element of the jwsc Ant task For more information, see Using the <jmstransportservice> Child Element in the Ant build.xml File.

WSDL

Create the web service from a WSDL that includes JMS transport property elements, as defined in Configuring JMS Transport Properties in the WSDL.

Administration Console

Configure the JMS transport properties for the deployed web service using the WebLogic Server Administration Console, as described in Configuring JMS Transport Using the Administration Console.

<soapjms-service-endpoint-address> element in the weblogic-webservices.xml deployment descriptor

You can update the weblogic-webservices.xml deployment descriptor manually, though it is not recommended. For more information about the <soapjms-service-endpoint-address> elements, see WebLogic Web Service Deployment Descriptor Schema Reference in WebLogic Web Services Reference for Oracle WebLogic Server.

The following summarizes the order of precedence for JMS transport property configuration on the web service or client at design time and run time:

  • For the web service at design time (from high to low):

    • <jmstransportservice> child element in the <jws> element of the jwsc Ant task

    • @JMSTransportService annotation

  • For the web service at run time (from high to low):

    • Administration Console

    • <soapjms-service-endpoint-address> element in the weblogic-webservices.xml deployment descriptor

    • @JMSTransportService annotation

  • For the client at design time (from high to low):

    • <jmstransportclient> child element of clientgen

    • JMS transport properties defined in the WSDL

  • For the client at run time (from high to low):

    • JMS URI service endpoint address

    • JMSTransportClientFeature API

    • @JMSTransportClient annotation

Configuring JMS Transport Using the Administration Console

After you have deployed your web service with JMS transport enabled, you can configure JMS transport properties using the WebLogic Server Administration Console.

To configure JMS transport properties using the WebLogic Server Administration Console:

  1. Invoke the WebLogic Server Administration Console, as described in Invoking the Administration Console in Understanding WebLogic Web Services for Oracle WebLogic Server.
  2. In the left navigation pane, select Deployments.
  3. Click the name of the web service in the Deployments table.
  4. Select the Configuration tab, then the Port Components tab.
  5. Click the name of the web service endpoint in the Ports table.
  6. Select the SOAP over JMS Transport tab.
  7. Click Customize SOAP over JMS Transport Configuration and follow the instructions to save the deployment plan, if required.
  8. Edit the SOAP over JMS transport properties, as described in Configuring JMS Transport Properties.
  9. Click Save.

For more information, see Configuring SOAP Over JMS Transport in the Oracle WebLogic Server Administration Console Online Help.

Configuring JMS Transport Using WLST

Alternatively, you can use WLST to configure JMS transport. For information about using WLST to extend the domain, see Configuring Existing Domains in Understanding the WebLogic Scripting Tool.

Configuring the JMS URI

When a WebLogic web service is configured to use SOAP over JMS as the connection transport, the endpoint address specified for the corresponding port in the generated WSDL of the web service uses jms: in its URL rather than http://.

The JMS URI format is shown below:

jms:lookupVariant:destinationName[?targetService=value[&property=value][&property=value]...
]

The JMS URI is constructed as follows:

  • Prefix jms:

  • Lookup variant type (must be set to jndi)

  • JMS destination name (destinationName)

  • Query string containing a list of property-value pairs used to specify JMS endpoint information. The targetService property must be specified to define the port component name of the web service.

    Other valid properties include:

    • bindingVersion

    • deliveryMode

    • deliveryType

    • jndiConnectionFactoryName

    • jndiContextParameter

    • jndiInitialContextFactory

    • jndiURL

    • messageType

    • priority

    • replyToName

    • timeToLive

The lookupVariant, destinationName, and targetService JMS properties are required in the JMS endpoint address.

For more information about the JMS transport properties that construct the JMS URI, see Table 17-6. Optionally, you can configure JMS transport properties when enabling JMS transport using one of the methods defined in Table 17-7.

Examples:

The following provides an example of a JMS endpoint address. In this example, the JMS destination is myQueue and the port component name of the web service is WarehouseServicePort. 

jms:jndi:myQueue?targetService=WarehouseServicePort

The following example shows the same JMS endpoint address with replyToName property set to specify the JNDI name of the JMS destination to which the response message is sent.

jms:jndi:myQueue?targetService=WarehouseServicePort&replyToName=myReplyToQueue

The following example shows how to specify additional JNDI environment properties, such as jndi-com.acme.jndi.enable.tracing and jndi-java.naming.referral. 

jms:jndi:myQueue?targetService=WarehouseServicePort&jndi-com.acme.jndi.enable.tracing=true&jndi-java.naming.referral=ignore

Configuring the JMS Request URI

Each JMS transport message has a message property defined as SOAPJMS_requestURI that is derived from the JMS URI. The JMS Request URI is constructed using the JMS URI and stripping off the query parameters.

The JMS request URI format is shown below:

jms:lookupVariant:destinationName

The JMS Request URI is constructed as follows:

  • Prefix jms:

  • Lookup variant type (must be set to jndi)

  • JMS destination name (destinationName)

For more information about the JMS transport properties that construct the JMS Request URI, see Table 17-6. Optionally, you can configure JMS transport properties when enabling JMS transport using one of the methods defined in Table 17-7.

Example:

The following provides an example of a JMS endpoint address. In this example, the JMS destination is myQueue. 

jms:jndi:myQueue

Configuring the WS-Addressing Headers

Web services and clients that use SOAP over JMS transport populate the WS-Addressing headers To and ReplyTo of the request and response messages with a value that is derived from the JMS URI.

The WS-Addressing header format is shown below:

jms:lookupVariant:destinationName?targetService=value

For more information about the JMS transport properties that construct the WS-Addressing headers, see Table 17-6. Optionally, you can configure JMS transport properties when enabling JMS transport using one of the methods defined in Table 17-7.

Examples:

The following provides an example of the WS-Addressing headers in a SOAP request message.

<S:Header>  
   <To xmlns="http://www.w3.org/2005/08/addressing">
      jms:jndi:myQueue?targetService=WarehouseService
   </To> 
   <Action xmlns="http://www.w3.org/2005/08/addressing">
      http://www.oracle.com/samples/ShipGoodsRequest
   </Action>  
   <ReplyTo xmlns="http://www.w3.org/2005/08/addressing">  
      <Address>jms:jndi:myReplyToQueue?targetService=WarehouseService</Address>
   </ReplyTo>  
   <MessageID xmlns="http://www.w3.org/2005/08/addressing">
      uuid:3b9e7b20-3aa0-4a4a-9422-470fa7b9ada1
   </MessageID>  
</S:Header>

The following provides an example of the WS-Addressing headers in a SOAP response message.

<S:Header>
   <To xmlns="http://www.w3.org/2005/08/addressing">
      jms:jndi:myReplyToQueue?targetService=WarehouseService
   </To>  
   <Action xmlns="http://www.w3.org/2005/08/addressing">
      http://www.oracle.com/samples/ShipGoodsResponse
   </Action>  
   <MessageID xmlns="http://www.w3.org/2005/08/addressing">
      uuid:9d0be951-79fc-4a56-b3e6-4775bde2bd82
   </MessageID>  
   <RelatesTo xmlns="http://www.w3.org/2005/08/addressing">
      uuid:3b9e7b20-3aa0-4a4a-9422-470fa7b9ada1
   </RelatesTo>  
</S:Header>

Configuring the JMS Response Queue

For a two-way operation, a temporary response queue is generated by default. Using the default temporary response queue minimizes the configuration that is required. However, in the event of a server failure, the response message may be lost.

You can configure a "permanent" JMS response queue—one that is available after server restart. A permanent JMS response queue provides the following benefits:

  • Ensures that the response message can be restored following a server restart.

  • Improves performance, avoiding the overhead required to create the temporary queue at initial invocation.

  • Enables you to configure the queue for quality of service (QoS).

You can configure the JMS response queue using one of the following methods (in order of precedence):

Note:

If the destinationName property is set to anonymous (which is not supported by JMS transport), then a temporary response queue is used.

By default, the JMS response queue is used as the fault queue for JMS transport service invocation. You can configure the faultTo header using the AsyncClientTransportFeature, as described in Configuring the ReplyTo and FaultTo Headers of the Asynchronous Response Endpoint.

Configuring the JMS Message Type

You can configure one of the following message types to use with the request message.

  • com.oracle.webservices.api.jms.JMSMessageType.BYTES—The body of the JMS message is binary data. This is the default.

  • com.oracle.webservices.api.jms.JMSMessageType.TEXT— The body of the JMS message is String data.

You can configure the messageType property using any of the configuration methods defined in Table 17-8.

The web service uses the same message type when sending the response. If the request is received as a BYTES, the reply will be sent as a BYTES.

When setting the messageType property to TEXT, consider the following:

  • For large payloads, the memory requirements for TEXT messages can be significantly greater than BYTES messages because the data requirements for the in-memory representation is larger.

  • Messages with binary attachments must be base64-encoded, which can also increase the size of the message significantly.

Configuring HTTP Access to the WSDL File

By default, the WSDL of the deployed web service is still accessible using HTTP. If you want to disable access to the WSDL file, in particular if your web service can be accessed outside of a firewall, then you can do one of the following:

  • Use the enableHttpWsdlAccess attribute of the <jmstransportservice> child element of the <jws> element, as described in Using the <jmstransportservice> Child Element in the Ant build.xml File.

  • @JMSTransportService annotation, as described in Using the @JMSTransportService Annotation.

  • Use the WebLogic Server Administration Console to disable access to the WSDL file after the web service has been deployed. In this case, the configuration information will be stored in the deployment plan rather than through the annotation.

    To use the WebLogic Server Administration Console to perform this task, go to the Configuration -> General page of the deployed web service and uncheck the View Dynamic WSDL Enabled check box. After saving the configuration to the deployment plan, you must redeploy (update) the web service, or Enterprise Application which contains it, for the change to take effect.

Monitoring SOAP Over JMS Transport

You can monitor web services that use SOAP over JMS transport from the following perspectives: