4 Upgrading WebLogic Web Services

Learn the procedures for upgrading WebLogic and RESTful Web services from Oracle WebLogic Server 10.x to 12.2.x . Also, learn how to upgrade 8.1 WebLogic Web services to 12.2.x WebLogic JAX-WS Web services.

This chapter includes the following sections:

Note:

10.3.x WebLogic Web services (JAX-WS or JAX-RPC) will continue to run, without any changes, on version 12.2.x of WebLogic Server because the associated Web services run time is still supported in this release, although they are deprecated and will be removed from the product in future releases. For this reason, Oracle highly recommends that you follow the instructions in this chapter to upgrade your 10.3.x Web services to 12.2.x.

The JAX-RPC API has been deprecated in 12.2.x and will be removed in a future release. Oracle does not recommend upgrading to the JAX-RPC stack.

Upgrading a 10.3.x RESTful Web Service (JAX-RS) to 12.2.x

In 10.3.x, a set of pre-built shared libraries were delivered with WebLogic Server to support Jersey 1.9 and 1.1.5.1 Java API for RESTful Web Services (JAX-RS) Reference Implementations (RIs). In 12.2.x, WebLogic Server supports Jersey 2.21.x (JAX-RS 2.0 RI) by default.To use the pre-built shared libraries of 10.3.x, you needed to register them with the WebLogic Server instance, and modify the web.xml and weblogic.xml deployment descriptors to use the Jersey servlet and reference the shared libraries, respectively.

In 12.2.x, as WebLogic Server supports Jersey 2.21.x (JAX-RS 2.0 RI) by default, registration as a shared library with WebLogic Server is no longer required.

To use the Jersey 2.21.x (JAX-RS 2.0 RI), you need to modify your 10.3.x RESTful Web service applications as follows:

  1. Update your application deployment descriptors to reference the Jersey 2.x container. See Servlet-based Deployment in Jersey 2.21 User Guide.

    Note:

    For backward compatibility, references to com.sun.jersey.spi.container.servlet.ServletContainer, as shown in the following example, continues to work. However, Oracle recommends that you update your application deployment descriptors to reference the Jersey 2.x container instead.

    For example, replace com.sun.jersey.spi.container.servlet.ServletContainer with org.glassfish.jersey.servlet.ServletContainer in the following <web-app> content:

    <web-app>
        <servlet>
            <display-name>My Jersey Application</display-name>
            <servlet-name>MyJerseyApp</servlet-name>
            <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
            <init-param>
                <param-name>javax.ws.rs.Application</param-name>
                <param-value>myPackage.myJerseyApplication</param-value>
            </init-param>
        </servlet>
        <servlet-mapping>
            <servlet-name>MyJerseyApp</servlet-name>
            <url-pattern>/*</url-pattern>
        </servlet-mapping>
    </web-app>
    

    For more advanced configuration options, see Jersey 2.21.1 User Guide.

  2. If applicable, update all applications that use Jersey 1.x server APIs to use the corresponding standard JAX-RS 2.0 or Jersey 2.x APIs instead. Support for the Jersey 1.x (JAX-RS 1.1 RI) server APIs has been removed in this release and applications that reference them will not work.
  3. Update your clients to use the javax.ws.rs.client API, as described in Developing RESTful Web Service Clients in Developing and Securing RESTful Web Services for Oracle WebLogic Server.

    Note:

    Support for the Jersey 1.18 client packages, including the com.sun.jerseypackage, its nested packages, and the weblogic.jaxrs.api.client package, is deprecated in this release of WebLogic Server, but are maintained for backward compatibility. However, many Fusion Middleware components, such as Oracle Web Services Manager, have been migrated to the standard JAX-RS 2.0 client API and are not compatible with the Jersey 1.x JAX-RS client APIs. Therefore, Oracle strongly recommends that you update your RESTful client applications as soon as possible to use the standard JAX-RS 2.0 API.

    The Jersey 1.x JAX-RS RI client APIs are not compatible with Jersey 2.x (JAX-RS 2.0 RI).

Upgrading a 10.x WebLogic Web Service (JAX-WS) to 12.2.x

No steps are required to upgrade a 10.x WebLogic Web service to 12.2.x. You can redeploy the JAX-WS Web service to WebLogic Server 12.2.x without making any changes or recompiling.

Upgrading an 8.1 WebLogic Web Service to the WebLogic JAX-WS Stack

The 8.1 WebLogic Web services runtime was removed in the 12.1.2 release. If you are using 8.1 WebLogic Web services, you must upgrade the 8.1 WebLogic Web service applications to the JAX-WS (Java API for XML-Based Web Services) stack. The 8.1 WebLogic Web services rely on Apache XMLBeans for mapping XML elements in SOAP payloads into Java objects and vice versa. XMLBeans are not supported in 12.1.2 and later.

Note:

Upgrade 8.1 Web service to JAX-WS on your WebLogic Server release before you upgrade to 14.1.1.0.0. After you upgrade to 14.1.1.0.0, your 8.1 Web services will no longer work.

Upgrading to the JAX-WS stack allows you to take advantage of the latest technologies and standards support in WebLogic Server. This path requires a manual upgrade process, and the level of effort depends on the nature of the existing 8.1 Web service applications. For example, if the applications have little XMLBeans usage, then the upgrade process is relatively easy. For 8.1 Web Service applications with heavy XMLBeans dependencies, you must modify the business logic in the service implementation to use JAXB classes instead of XMLBeans classes. JAX-WS does not support RPC-encoded style. The 8.1 Web Service applications with RPC-encoded style must adopt more interoperable literal style service contracts.

The WebLogic JAX-WS runtime is based on the JAX-WS 2.2 specification and the Web Services for Java EE v1.3 (JSR 109) specifications. These define annotations that are used in a Java Web Service (JWS) source file to define a Web service. Ant tasks are then used to compile the JWS into a Java class and generate all the associated artifacts. The Java Web Service (JWS) is the core of your JAX-WS web service.

Upgrading your 8.1 Web service includes the following high-level tasks:

  • Upgrade any Web service EJBs from 2.x to 3.x.

    JAX-WS supports EJB 3.0 and 3.x. It does not support EJB 2.x.

  • Rewrite the 8.1 Web service class as a JAX-WS JWS file and map any proprietary 8.x features to similar JAX-WS features.

    There is not a one-to-one correspondence between 8.1 Web service features and JAX-WS 12.1.x features.

  • Update the Ant build script that builds the Web service to call the 12.1.x WebLogic Web service Ant task jwsc instead of the 8.1 servicegen task.

  • Generate new JAX-WS clients using the JAX-WS clientgen Ant task.

JAX-WS Upgrade Considerations

Before upgrading to JAX-WS, consider the following:

  • The JAX-WS specification supports the document-literal and rpc-literal styles, but not rpc-encoded.

  • The JAX-WS specification does not support SOAP Arrays.

See Developing JAX-WS Web Services for Oracle WebLogic Server.

Upgrading a WebLogic JAX-RPC Web Service to the WebLogic JAX-WS Stack

The WebLogic JAX-WS run time is based on the JAX-WS (The Java API for XML-Based Web Services) 2.2 specification and the Web Services for Java EE v1.3 (JSR 109) specifications. Starting with JAX-WS 2.0, the JAX-WS technology has replaced JAX-RPC in the Java Platform and in WebLogic Server. JAX-RPC Web Services in WebLogic applications should be upgraded to JAX-WS.

This section summarizes how to upgrade a WebLogic JAX-RPC Web service to use the WebLogic JAX-WS stack.

Upgrading your WebLogic Server JAX-RPC Web service includes the following high-level tasks:

  • Upgrade any Web service EJBs from 2.x to 3.x.

    JAX-WS supports EJB 3.0 and 3.x. It does not support EJB 2.x.

  • Upgrade your JWS, mapping any proprietary JAX-RPC features to similar JAX-WS features.

    Note that there is not a one-to-one correspondence between WebLogic JAX-RPC Web service features and JAX-WS 12.x features.

  • Update the Ant build script that builds the Web service to change the value of the type attribute on the jws, wsdlc, and clientgen tasks to be "JAXWS" (for example, type="JAXWS").

  • Generate new JAX-WS clients using the JAX-WS clientgen Ant task.

JAX-WS Upgrade Considerations

When upgrading to JAX-WS, you should consider the following:

  • The JAX-WS specification supports the document-literal and rpc-literal styles, but not rpc-encoded.

  • SOAP Arrays are not supported by JAX-WS.

See Developing JAX-WS Web Services for Oracle WebLogic Server