4 Upgrading WebLogic Web Services

The following sections describe the procedures for upgrading WebLogic and RESTful Web services from WebLogic Server 10.x to the WebLogic Server 12.2.x release. It also describes 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). To use the shared libraries, 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, WebLogic Server supports Jersey 2.21.x (JAX-RS 2.0 RI) by default in this release. 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:

Update your application deployment descriptors to reference the Jersey 2.x container. For details, 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, will continue to work. However Oracle strongly 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 additional advanced configuration options, see Jersey 2.21.1 User Guide.
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.
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 run time was removed In the 12.1.2 release. If you are using 8.1 WebLogic Web services, you need to upgrade the 8.1 WebLogic Web service applications to the JAX-WS Web service stack. The 8.1 WebLogic Web services rely on Apache XMLBeans for the purpose of mapping XML elements in SOAP payloads into Java objects and vice versa. XMLBeans are not supported in 12.1.2 and later.

Note:

You must perform the 8.1 Web service upgrade to JAX-WS on your WebLogic Server release before you upgrade to 12.2.1.1.0. Once you upgrade to 12.2.1.1.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 is determined by 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 in order to use JAXB classes instead of XMLBeans classes. Please note that JAX-WS does not support RPC-encoded style, and 8.1 Web Service applications with RPC-encoded style will need to adopt more interoperable literal style service contracts.

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. 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.

Note that 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, 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.

For more information about JAX-WS, refer to 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.

For more information about JAX-WS, refer to Developing JAX-WS Web Services for Oracle WebLogic Server