8 Migrating JAX-RPC Web Services and Clients to JAX-WS

This chapter describes how to migrate Java API for XML-based RPC (JAX-RPC) Web services and clients to Java API for XML-based Web services (JAX-WS).

When migrating your JAX-RPC Web services, to preserve the original WSDL file, use the top-down approach, starting from a WSDL file, to generate the JAX-WS Web service. For more information, see "Developing WebLogic Web Services Starting From a WSDL File: Main Steps".

Note:

In some cases, a JAX-RPC feature may not be supported currently by JAX-WS. In this case, the application cannot be migrated unless it is re-architected.

The following table summarizes the topics that are covered.

Table 8-1 Tips for Migrating JAX-RPC Web Services and Clients to JAX-WS

Topic Description

Setting the Final Context Root of a WebLogic Web Service

Describes the methods that can be used to set the final context root of a WebLogic Web service. The use of @WLXXXTransport JWS annotations is not supported for JAX-WS; these annotations are supported by JAX-RPC only.

Using WebLogic-specific Annotations

Describes the WebLogic-specific annotations that are supported by JAX-WS.

Generating a WSDL File

Describes how to generate a WSDL file when you are generating a JAX-WS Web service using the jwsc Ant task.

Using JAXB Custom Types

Describes the use of Java Architecture for XML Binding (JAXB) for managing all of the data binding tasks.

Using EJB 3.0

Describes changes in EJB 3.0 from EJB 2.1. JAX-WS supports EJB 3.0. JAX-RPC supports EJB 2.1 only.

Migrating from RPC Style SOAP Binding

Provides guidelines for setting the SOAP binding. RPC style is supported, but not recommended for JAX-WS.

Updating SOAP Message Handlers

Explains how you must re-write your JAX-RPC SOAP message handlers when migrating to JAX-WS.

Invoking JAX-WS Clients

Explains how you must re-write your JAX-RPC client to invoke JAX-WS clients.


Setting the Final Context Root of a WebLogic Web Service

You can set the final context root of a WebLogic Web service using a variety of methods, as described in "Defining the Context Path of a WebLogic Web Service" in WebLogic Web Services Reference for Oracle WebLogic Server.

As described in this section, when defining a JAX-RPC Web service, you can use the @WLXXXTransport JWS annotations to specify the context root. For JAX-WS Web services, the @WLXXXTransport JWS annotations are not valid. If used in the JAX-RPC Web service, the JWS file needs to be updated to remove the annotations in favor of one of the other methods.

Using WebLogic-specific Annotations

JAX-WS supports the following WebLogic-specific annotations:

  • @Policy

  • @Policies

  • @SecurityPolicy

  • @SecurityPolicies

  • @WssConfiguration

All other WebLogic-specific annotations must be removed from your JAX-RPC applications when migrating to JAX-WS. For more information, see "WebLogic-specific Annotations" in WebLogic Web Services Reference for Oracle WebLogic Server.

Generating a WSDL File

When you run the jwsc file on a JAX-RPC Web service, a WSDL file is generated in the specified output directory. For JAX-WS Web services, the WSDL file is generated when the service endpoint is deployed. In order to generate a WSDL file in the output directory, you must specify the wsdlOnly attribute of the <jws> child element of the jwsc Ant task. For more information, see "jwsc" in the WebLogic Web Services Reference for Oracle WebLogic Server.

Using JAXB Custom Types

JAX-WS uses Java Architecture for XML Binding (JAXB), described at http://jcp.org/en/jsr/detail?id=222, to manage all of the data binding tasks. If your application supports custom types using XMLBeans or Tylar, you will need to modify them to use JAXB. For more information about using JAXB, see Chapter 5, "Using JAXB Data Binding."

Using EJB 3.0

JAX-WS supports EJB 3.0. JAX-RPC supports EJB 2.1 only.

EJB 3.0 introduced metadata annotations that enable you to automatically generate, rather than manually create, the EJB Remote and Home interface classes and deployment descriptor files needed when implementing an EJB.

For more information about EJB 3.0 bean class requirements and changes from 2.x, see "Programming the Bean File: Requirements and Changes from 2.X" in Enterprise JavaBeans (EJB) 3.0.

Migrating from RPC Style SOAP Binding

Use of the SOAPBinding.Style.RPC style, although supported, is not recommended with JAX-WS. It is recommended that you change the style to SOAPBinding.Style.DOCUMENT.

Updating SOAP Message Handlers

Although the SOAP APIs are similar, JAX-RPC SOAP handlers will need to be modified to run with JAX-WS. For more information, see "Creating and Using SOAP Message Handlers" in Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server.

Invoking JAX-WS Clients

JAX-RPC clients will need to be re-written as the JAX-RPC and JAX-WS client APIs are completely different. For more information about writing JAX-WS clients, see "Invoking Web Services" in Getting Started With WebLogic Web Services Using JAX-WS.