8 Using JMS Transport as the Connection Protocol

The following sections provide information about using JMS transport as the connection protocol:

Overview of Using JMS Transport

Typically, client applications use HTTP/S as the connection protocol when invoking a WebLogic Web service. You can, however, configure a WebLogic Web service so that client applications use JMS as the transport instead.

Using JMS transport offers the following benefits: reliability, scalability, and 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 dealt with as soon as WebLogic Server is restarted. When a client invokes a Web service, the client does not wait for a response from the invoke, and the execution of the client can continue. Using JMS transport does require slightly more overhead and programming complexity than HTTP/S.

You configure transports using either JWS annotations or child elements of the jwsc Ant task, as described in later sections. When a WebLogic Web service is configured to use 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://. An example of a JMS endpoint address is as follows:

jms://myHost:7001/transports/JMSTransport?URI=JMSTransportQueue

The URI=JMSTransportQueue section of the URL specifies the JMS queue that has been configured for the JMS transport feature. 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-RPC stubs for the Web service.

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 add the transports using the appropriate JWS annotations or child elements of jwsc.

Note:

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

Using JMS Transport Starting From Java: Main Steps

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

  • Add the @WLJmsTransport annotation to your JWS file.

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

    Note:

    Because you might not know at the time that you are coding the JWS file which transport best suits your needs, it is often better to specify the transport at build-time using the <WLJmsTransport> child element.

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.

Note:

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. 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 Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Table 8-1 Steps to Use JMS Transport Starting From Java

#
Step Description

1

Configure the WebLogic Server domain for the required JMS components.

See Configuring the Host WebLogic Server Instance for the JMS Transport Web Service.

2

Add the @WLJmsTransport annotation to your JWS file. (Optional)

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

See Using the @WLJmsTransport JWS Annotation.

3

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

Use the <WLJmsTransport> child element to override the transports defined in the JWS file. This step is required if you did not add the @WLJmsTransport annotation to your JWS file in Step 2. Otherwise, this step is optional.

See Using the <WLJmsTransport> Child Element of the jwsc Ant Task for details.

4

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" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Deploy your Web service to WebLogic Server.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.


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 JMS Transport Starting From WSDL: Main Steps

To use JMS transport 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 @WLJmsTransport annotation.

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

    Note:

    Because you might not know at the time that you are coding the JWS file which transport best suits your needs, it is often better to specify the transport at build-time using the <WLJmsTransport> child element.

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.

Note:

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

Table 8-2 Steps to Use JMS Transport Starting From WSDL

#
Step Description

1

Configure the WebLogic Server domain for the required JMS components.

See Configuring the Host WebLogic Server Instance for the JMS Transport Web Service.

2

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 @WLJmsTransport annotation to your JWS file, as described in Step 4.

  • Add a <WLJmsTransport> child element to the jwsc Ant task, as described in Step 5.

See Updating the WSDL to Use JMS Transport.

3

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" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

4

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" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

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

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

  • Add a <WLJmsTransport> child element to the jwsc Ant task, as described in Step 5.

5

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

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

See Using the <WLJmsTransport> Child Element of the jwsc Ant Task for details.

6

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" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

7

Deploy the Web service to WebLogic Server.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.


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

Configuring the Host WebLogic Server Instance for the JMS Transport Web Service

Configuring the WebLogic Server instance on which the JMS transport Web service is deployed involves configuring JMS resources, such as JMS servers and modules, that are used internally by the Web services runtime.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Note:

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

If you prefer to configure the resources manually, perform the following steps.

Table 8-3 Steps to Configure Host WebLogic Server Instance Manually for the JMS Transport Web Service

#
Step Description

1

Invoke the Administration Console for the domain that contains the host WebLogic Server instance.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

  • host refers to the computer on which the Administration Server is running.

  • port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Create a JMS Server.

Create a JMS Server. If a JMS server already exists, you can use it if you do not want to create a new one.

See "Create JMS servers" in Oracle WebLogic Server Administration Console Help.

4

Create JMS module and define queue.

Create a JMS module, and then define a JMS queue in the module. If a JMS module already exists, you can use it if you do not want to create a new one. Target the JMS queue to the JMS server you created in the preceding step. Be sure you specify that this JMS queue is local, typically by setting the local JNDI name. See "Create JMS system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Help.

If you want the JMS transport Web service to use the default Web services queue, set the JNDI name of the JMS queue to weblogic.wsee.DefaultQueue. Otherwise, if you use a different JNDI name, be sure to specify the queue name when specifying the @WLJmsTransport annotation or <WLJmsTransport> child element of the jwsc Ant task.

Clustering Considerations:

If you are using the Web service JMS transport feature in a cluster, you must:

  • Create a local JMS queue, rather than a distributed queue, when creating the JMS queue.

  • Explicitly target this JMS queue to each server in the cluster.


Using the @WLJmsTransport JWS 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 @WLJmsTransport to specify the details of the invocation. Later, at build-time, you can override the invocation defined in the JWS file and add additional JMS transport specifications, by specifying the <WLJmsTransport> child element of the jwsc Ant task, as described in Using the <WLJmsTransport> Child Element of the jwsc Ant Task.

Follow these guidelines when using the @WLJmsTranport annotation:

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

  • Use the queue attribute to specify the JNDI name of the JMS queue you configured earlier in the section. If you want to use the default Web services queue (weblogic.wsee.DefaultQueue) then you do not have to specify the queue attribute.

  • Use the connectionFactory attribute to specify the JNDI name of the connection factory. The default value of this attribute is the default JMS connection factory for your WebLogic Server instance.

The following example shows a simple JWS file that uses the @WLJmsTransport annotation, with the relevant code in bold:

package examples.webservices.jmstransport;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLJmsTransport; 

@WebService(name="JMSTransportPortType",
             serviceName="JMSTransportService",
            targetNamespace="http://example.org")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

// WebLogic-specific JWS annotation that specifies the context path and
// service URI used to build the URI of the Web Service is
// "transports/JMSTransport"

@WLJmsTransport(contextPath="transports", serviceUri="JMSTransport", 
                queue="JMSTransportQueue", portName="JMSTransportServicePort", 
             connectionFactory="JMSTransportConnectionFactory") 

/**
 * This JWS file forms the basis of simple Java-class implemented WebLogic
 * Web Service with a single operation: sayHello
 */

public class JMSTransportImpl {

  @WebMethod()
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

Using the <WLJmsTransport> Child Element of the jwsc Ant Task

You can also specify the JMS transport at build-time by using the <WLJmsTransport> child element of the <jws> element of the jwsc Ant task. Reasons for specifying the transport at build-time include:

  • You need to override the attribute values specified in the JWS file.

  • The JWS file specifies a different transport, and at build-time you decide that JMS should be the transport.

  • The JWS file does not include a @WLXXXTransport annotation; thus by default the HTTP transport is used, but at build-time you decide you want to clients to use the JMS transport to invoke the Web service.

If you specify a transport to the jwsc Ant task, it takes precedence over any transport annotation in the JWS file.

The following example shows how to specify a transport to the jwsc Ant task:

  <target name="build-service">

    <jwsc
      srcdir="src"
      destdir="${ear-dir}">
      <jws file="examples/webservices/jmstransport/JMSTransportImpl.java">

        <WLJmsTransport
                contextPath="transports" 
                serviceUri="JMSTransport"
                portName="JMSTransportServicePort"
               queue="JMSTransportQueue"
                connectionFactory="JMSTransportConnectionFactory"/>

      </jws>

    </jwsc>

  </target>

The preceding example shows how to specify the same values for the URL and JMS queue as were specified in the JWS file shown in Using the @WLJmsTransport JWS Annotation.

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

Updating the WSDL to Use JMS Transport

To update the WSDL to use JMS transport, you need to add <wsdl:binding> and <wsdl:service> definitions that define JMS transport information. You can add the definitions in one of the following ways:

  • Edit the existing HTTP <wsdl:binding> and <wsdl:service> definitions.

  • To specify multiple transport options in the WSDL, copy the existing HTTP <wsdl:binding> and <wsdl:service> definitions and edit them to use JMS transport.

In either case, you must modify the <wsdl:binding> and <wsdl:service> definitions to use JMS transport as follows:

  • Set the transport attribute of the <soapwsdl:binding> child element of the <wsdl:binding> element to http://www.openuri.org/2002/04/soap/jms/. For example:

    <binding name="JmsTransportServiceSoapBindingjms" type="tns:JmsTransportPortType">
        <soap:binding style="document" transport="http://www.openuri.org/2002/04/soap/jms/"/>
    
  • Specify a JMS-style endpoint URL for the location attribute of the <soapwsdl:address> child element of the <wsdl:service>. For example:

    <s0:service name="JmsTransportService">
        <s0:port binding="s1:JmsTransportServiceSoapBindingjms" name="JmsTransportServicePort">
            <s2:address location="jms://localhost:7001/transports/JmsTransport?URI=JMSTransportQueue"/>
        </s0:port>
      </s0:service>
    

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; the only difference is that you must ensure that the JMS queue (specified by the @WLJmsTransport annotation or <WLJmsTransport> child element of the jwsc Ant task) and other JMS objects have been created. See Using JMS Transport Starting From Java: Main Steps or Using JMS Transport Starting From WSDL: Main Steps for more information.

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-RPC stubs for the Web service. For example, the URL for the WSDL of the Web service shown in this section would be:

http://host:port/transports/JMSTransport?WSDL

However, because the endpoint address in the WSDL of the deployed Web service uses jms:// instead of http://, and the address includes the qualifier ?URI=JMS_QUEUE, the clientgen Ant task automatically creates the stubs needed to use the JMS transport when invoking the Web service, and your client application need not do anything different than normal. An example of a JMS endpoint address is as follows:

jms://host:port/transports/JMSTransport?URI=JMSTransportQueue

Note:

If you have specified that the Web service you invoke using JMS transport also runs within the context of a transaction (in other words, the JWS file includes the @weblogic.jws.Transactional annotation), you must use asynchronous request-response when invoking the service. If you do not, a deadlock will occur and the invocation will fail.

For general information about invoking a Web service, see "Invoking Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Overriding the Default Service Address URL

When you write a client application that uses the clientgen-generated JAX-RPC stubs to invoke a Web service, the default service address URL of the Web service is the one specified in the <address> element of the WSDL file argument of the Service constructor.

Sometimes, however, you might need to override this address, in particular when invoking a WebLogic Web service that is deployed to a cluster and you want to specify the cluster address or a list of addresses of the managed servers in the cluster. You might also want to use the t3 protocol to invoke the Web service. To override this service endpoint URL when using JMS transport, use the weblogic.wsee.jaxrpc.WLStub.JMS_TRANSPORT_JNDI_URL stub property as shown in the following example:

package examples.webservices.jmstransport.client;

import weblogic.wsee.jaxrpc.WLStub; 

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;

/**
 * This is a simple standalone client application that invokes the
 * the <code>sayHello</code> operation of the JMSTransport Web service.
 */

public class Main {

  public static void main(String[] args)
      throws ServiceException, RemoteException{

    JMSTransportService service = new JMSTransportService_Impl(args[0] + "?WSDL" );
    JMSTransportPortType port = service.getJMSTransportServicePort();

    Stub stub = (Stub) port; 

    stub._setProperty(WLStub.JMS_TRANSPORT_JNDI_URL, 
                      "t3://shackell01.amer.com:7001"); 
    try {
      String result = null;

      result = port.sayHello("Hi there! ");

      System.out.println( "Got JMS result: " + result );

    } catch (RemoteException e) {
      throw e;
    }
  }
}

See "WLStub" in Oracle WebLogic Server API Reference for additional stub properties.

Using JMS BytesMessage Rather Than the Default TextMessage

When you use JMS transport, the Web services runtime uses, by default, the javax.jms.TextMessage object to send the message. This is usually adequate for most client applications, but sometimes you might need to send binary data rather than ordinary text; in this case you must request that the Web services runtime use javax.jms.BytesMessage instead. To do this, use the WLStub.JMS_TRANSPORT_MESSAGE_TYPE stub property in your client application and set it to the value WLStub.JMS_BYTESMESSAGE, as shown in the following example:

    stub._setProperty(WLStub.JMS_TRANSPORT_MESSAGE_TYPE,
                      WLStub.JMS_BYTESMESSAGE);

The Web services runtime sends back the response using the same message data type as the request.

See Overriding the Default Service Address URL for a full example of a client application in which you can set this property. See "WLStub" in Oracle WebLogic Server API Reference for additional stub properties.

Disabling HTTP Access to the WSDL File

As described in Invoking a WebLogic Web Service Using JMS Transport, the WSDL of the deployed Web service is, by default, 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 weblogic.jws.WSDL annotation in your JWS file to programmatically disable access. For details, see "weblogic.jws.WSDL" in WebLogic Web Services Reference for Oracle WebLogic Server.

  • Use the 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 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.