Previous Next vertical dots separating previous/next from contents/index/pdf

Upgrading Web Services

This topic gives more detail about upgrade changes noted for web services.

For a more complete list of changes affecting applications upgraded from version 8.1, see Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.0.

Deprecated UseWLW81BindingTypes and WLWRollbackOnCheckedException Annotations are Added to Upgraded Code

Supported but deprecated. Upgraded web service and Service control code will include the @UseWLW81BindingTypes and/or @WLWRollbackOnCheckedException annotations applied at the class level. Even though these annotations are deprecated, they are required in order to support clients that used the version 8.1 code.

Upgrade Changes for Web Services That Combine Stateful and Stateless Operations

Supported but deprecated. In version 9.x stateless operations must be marked with the NONE phase constant. During upgrade, upgrade tools will ensure that all operations are legal by adding an annotation to the version 8.1 stateless operations so that they are marked with @Conversation(value = Conversation.Phase.NONE).

Note: The NONE phase constant is deprecated, included for backward compatibility only. To ensure that your web services functionality is supported in future releases, you should plan to rewrite the service so that stateless and stateful functionality is placed into separate web services.

Version 8.1. For example, the following version 8.1 snippet shows a stateful operation preceding a stateless operation.

 * @common:operation
 * @jws:conversation phase="start"
public void startShopping(int customerId)
    ... stateful ...

// Other stateful operations, including a FINISH operation.

 * @common:operation
public String buyWithOneClick(int customerId)
    ... stateless ... 

Version 10.0. When upgraded, this would result in something like the following:

@Conversation(value = Conversation.Phase.START)
@WebResult(name = "startShoppingResult")
public void startShopping(int customerId)

// Other stateful operations, including a FINISH operation.

@Conversation(value = Conversation.Phase.NONE)
@WebResult(name = "noPhaseResult")
public String butWithOneClick(int customerId)

Ensuring START and FINISH Methods for Conversations

In version 8.1 it was possible to compile a "conversational" web service that did not have START or FINISH operations. In other words, you could annotate the web service class as conversational (setting, for example, the annotation's maxAge attribute) but not annotate any of the web service's operations with conversation phase attributes. In version 10.0 a conversational web service must have both a START and FINISH operation in order to compile.

Setting Conversation Phase

In version 8.1, you can set conversation phase by opening the web service in Design view, then selecting operations and setting their phase attribute each in turn. In version 10.0, open the web service source code and place a cursor at the operation whose phase attribute you want to set, then locate and set the Conversation value in the Annotations view. You can also apply the annotation in source, as shown here for a START method:

public void startConversation()

Multiple SOAP Versions are Not Supported for Bindings Defined in a Web Service

Unlike version 8.1, version 9.x doesn't support using multiple SOAP versions for bindings defined in a web service. When upgrading, you'll need to manually edit any web services that use more than one SOAP version so that they use only one.

Upgrading from Version 8.1 Implementation of SOAP 1.2

Version 8.1 included a SOAP 1.2 implementation that was based on a working draft of the SOAP 1.2 specification. The version 10.0 implementation is based on the final version of the specification, and so differs from the older implementation. After you upgrade a web service that uses the version 8.1 SOAP 1.2 implementation, the service's clients will no longer be able to use it.

To ensure compatibility for clients of a SOAP 1.2 web service you created with version 8.1, you should rebuild the client using a WSDL generated from an upgraded (version 10.0) version of the web service. In version 10.0, you can generate a WSDL by right-clicking the web service file in Package Explorer view, then clicking Generate WSDL.

Details: Non-SOAP XML Message Format Over HTTP or JMS is Not Supported

If you have version 8.1 web services that use a non-SOAP XML format over HTTP or JMS, you must change your web service on version 9.x so that it either uses the SOAP protocol or some alternative. In other words, version 10.0 web services do not support message formats that do not include SOAP headers.

In version 8.1, the @jws:protocol annotation supported the following attributes and values:

These attributes and values have no counterparts in version 10.0. If you upgrade to version 10.0, upgrade tools will simply ignore a protocol setting that isn't supported.

Details: form-get and form-post Message Formats are Not Supported to Receive Data

Version 9.x doesn't support using the form-get and form-post message formats to receive messages sent from an HTML form. When upgrading web services that use these formats, you'll need to use another method for receiving data sent from a form in a web browser.

In other words, version 10.0 web services do not support message formats that do not include SOAP headers.

In version 8.1, the @jws:protocol annotation supported the following attributes and values:

These attributes have no counterparts in version 10.0 and there are no suggested workarounds. If you upgrade to version 10.0, upgrade tools will simply ignore a protocol setting that isn't supported.

Upgrade Changes for Multiple Protocols in a Web Service

While version 9.x supports multiple protocols at the web service level, it does not continue the version 8.1 support for protocols set at the operation level. For example, in version 8.1 the following annotation was supported on a web service operation:

@jws:protocol jms-soap="true"
public void myOperation()

During upgrade, this annotation will be interpreted as a desire to support web service invocations over JMS. Your upgraded code will feature an annotation at the web service level, but not at the operation level:

@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, 
             use = SOAPBinding.Use.LITERAL, 
             parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
@WLJmsTransport(queue = "jws.queue",
                serviceUri = "myservices/MyWebService.jws")
@WebService(serviceName = "MyWebService",
            targetNamespace = "")
public class MyWebService

If supporting multiple protocols for different operations is a requirement, consider splitting your web services code into multiple web services, each with its own protocol support. For example, operations requiring JMS support would go into a web service designed for that purpose, while operations to be invoked over HTTP would go into another web service.

Resolving Namespace Differences from Mixed Operations with Document and RPC SOAP Bindings

If a version 8.1 web service includes one or more operations that use the RPC SOAP binding and one or more operations that use the document SOAP binding, then after upgrade types generated for those operations will be placed into different namespaces. This will be different from the version 8.1 web service itself, in which the types were in the same namespace. A WSDL generated from the upgraded web service will differ from the version 8.1-generated WSDL.

Note that this issue will probably only arise for web services that were written from scratch in Java, rather than generated from an existing WSDL file. Also, this may not be an issue at all if it is not important that your web service interface honor a WSDL.

If you need to honor a WSDL contract, you can work around this issue by generating a WSDL in version 8.1, then creating a new web service in version 10.0 from that WSDL. You can then copy and paste the implementation code from the version 8.1 service to the version 10.0 service.

Upgrading Web Services or Service Controls Whose WSDLs Define Multiple Services

In version 8.1 it was possible to have a web service (JWS) or Service control whose WSDL defined multiple services. The web service or control would represent only one of these services. When upgrading such code to version 10.0 upgrade will fail. To ensure that upgrade succeeds for this code, you should edit the WSDL so that it defines only the service that is represented by the JWS or Service control.

Upgrading WSDLs with Multiple <wsdl:import> Statements

Even though it was supported for WSDLs associated with version 8.1 service controls, in version 10.0 multiple occurrences of the <wsdl:import> element is not supported in the same WSDL. For example, you might have used one import to get WSDL portions of the WSDL and another import to get XSD portions for needed types.

You can work around this change by, before upgrading, including only one <wsdl:import> statement whose namespace attribute value is the namespace of the imported WSDL. The WSDL and XSD portions will both be imported with the single statement.

Ensuring Correct Handling of xs:anyType in Messages

If you created a version 8.1 web service by generating it from a WSDL that specified xs:anyType instead of xs:any, the web service will expect and send incorrect XML payloads after upgrade to version 10.0. You can ensure correct handling of xs:anyType by applying the following annotation to the web service at the class level:


Updating WSDLs from 1999 Namespace to 2001

Version 8.1 supported using types in the 1999 schema namespace for Service controls and web services generated from WSDLs that used the types. Because version 10.0 does not support types in this namespace, you will need to manually migrate the WSDL to the 2001 namespace. In simple cases, this will mean changing the following URIs:

... to these:

In more complex WSDLs, you will need to change parts of the WSDL to migrate the types themselves. Keep in mind that these changes may break clients that communicate with your web service.

Supporting Mismatch Between Operation Parameter Names and Names in WSDL

After upgrading a web service in which one or more method parameter names do not match their corresponding names in the WSDL from which the web service was created, you will need to add a @WebParam annotation to each parameter.

You might have this situation if a parameter name was modified after generating the web service, or if the WSDL name is not valid as a Java identifier. To work around this issue, add a @WebParam annotation with the matching WSDL name to each parameter in the JWS operation.

Resolving Deployment Error for Same-Named Web Services

Due to a difference in the way versions 8.1 and 10.0 generate the default targetNamespace value for web services, you may enounter a deployment error if you have two or more web services with the same class name in an application. For web services in version 10.0, WebLogic Server uses the fully-qualified port name — which includes the web service's targetNamespace value — to bind resources it uses internally. As a result, the port name must be unique within an application.

In version 8.1, the targetNamespace value defaulted to "". Because it is the default, this qualifying value could potentially be the same for multiple web services in the application. As a result, after upgrading to version 10.0, if there are two or more web services with the same simple class name (name without package) and this default value, a conflict can occur that results in a deployment error. The error will take the form "<web_service_name> is already bound."

If you encounter this error you can work around it by setting the value of the @java.jws.WebService annotation's name and serviceName attributes. This changes the name values within the WSDL portType and port elements. Even so, it should not affect the web service's interaction with its version 8.1 clients.

Note that for web services created with version 10.0, the default targetNamespace value is based on the web service package name rather than the same value for all. You can specify another value with the @WebService annotation's targetNamespace attribute.

Upgrading Security from from WS-Security to WS-Policy

Upgrade required. In version 8.1, web service message-level security is managed using WS-Security (WSSE) policy files. In version 10.0 you should use Web Services Policy Framework (WS-Policy). Workshop for WebLogic upgrade tools do not perform this aspect of upgrade. This section describes the key differences between the version 8.1 and 10.0 models.

Resolving Issue of Unmapped Entries in web.xml

In the course of upgrading your version 8.1 applications, you might find that some of your application's security-related characteristics differ between its behavior on the domain shipped with Workshop for WebLogic and the upgraded domain to which you redeploy it. This is because the "new" 9.x domain included with Workshop for WebLogic is not backward compatible, whereas the upgraded domain to which you deploy your upgraded application is (because it has been upgraded).

Applications on new domains default to having Combined Role Mapping enabled. This causes roles with no matching entry in weblogic.xml to have no (an empty) mapping.

If you had unmapped entries in web.xml, you will have to do one of the following:

You can disable combined role mapping by setting the <combined-role-mapping> property of the realm:


For more information on the combined role mapping setting and how it impacts security, see Understanding the Combined Role Mapping Enabled Setting.

Upgrading Reliable Messaging Support — Basic Instructions

Workshop for WebLogic upgrade tools do not upgrade reliable messaging support (such as the @jws:reliable annotation) from version 8.1 to version 10.0. As noted in the version 8.1 documentation, that version's reliable messaging (RM) support was very limited and was not based on a specification that would be supported in future versions. This section provides high level suggestions for adding reliable messaging support to a web service in version 10.0.

In version 8.1, you added support for reliable messaging in part by using annotations such as @jws:reliable and @jc:reliable. For example, at the web service class level you indicated the message time to live, while at the operation level you indicated that the operation could be invoked reliably. Here's an example:

 * @jws:reliable message-time-to-live="600 seconds"
public class ReliableService implements com.bea.jws.WebService
    static final long serialVersionUID = 1L;

     * @common:operation
     * @jws:reliable enable="true"
     * @jws:protocol form-get="false" form-post="false"
    public void doSomething()
        ...method body...

Version 10.0 annotations related to reliable messaging are not automatically added to upgraded code. Instead, you can manually add version 10.0 reliable messaging support using the following high-level steps. Note that you should consider these a minimum list of changes; for a more complete picture, see Using Web Service Reliable Messaging on the edocs web site.

  1. Use Workshop for WebLogic tools to upgrade your projects from WebLogic Workshop version 8.1.
  2. Create a WS-Policy XML file that describes the web services reliable messaging support. There are also default policy files provided with WebLogic Server. For more information, see Use of WS-Policy Files for Web Service Reliable Messaging Configuration on the edocs web site. Note that you can use the policy file to specify an "expiration" value that corresponds to the "message-time-to-live" attribute of the @jws:reliable annotation.
  3. Annotate the web service class with a @weblogic.jws.Policy annotation that references the policy file. For information on this annotation, see Using the @Policy Annotation on the edocs web site.
  4. Annotate the reliable method with the @javax.jws.Oneway annotation. All "reliable" operations must be "Oneway" when not using the WebLogic Server asynchronous request-response feature. For more information, see Using the @Oneway Annotation and Invoking a Web Service Using Asynchronous Request-Response on the edocs web site.
  5. Note: For an overview of options related to asynchrony in web services, see Using Events and Callbacks to Enable Long-Running Operations.

    Here's a very simple example of how the upgraded web service might look:

    @WLHttpTransport(serviceUri = "reliable/ReliableService.jws")
    @WebService(serviceName = "ReliableService",
                targetNamespace = "")
    @javax.jws.soap.SOAPBinding(style = javax.jws.soap.SOAPBinding.Style.DOCUMENT, 
                                use = javax.jws.soap.SOAPBinding.Use.LITERAL, 
                                parameterStyle = javax.jws.soap.SOAPBinding.ParameterStyle.WRAPPED)
    @Policy(uri="ReliableServicePolicy.xml", direction=Policy.Direction.both, attachToWsdl=true)
    public class ReliableService implements
        static final long serialVersionUID = 1L;
        @SOAPBinding(style = javax.jws.soap.SOAPBinding.Style.DOCUMENT, 
                     use = javax.jws.soap.SOAPBinding.Use.LITERAL, 
                     parameterStyle = javax.jws.soap.SOAPBinding.ParameterStyle.WRAPPED)
        @WebResult(name = "doSomethingResult")
        public void doSomething()
  6. Account for the fact that the version 10.0 service control does not provide the version 8.1 onDeliveryFailure callback method. The onDeliveryFailure method was designed to provide notification that a reliable message could not be delivered. To support this functionality in a web service upgraded to version 10.0, you can use the @weblogic.jws.AsyncFailure annotation in conjunction with WebLogic Server’s asynchronous request-response feature.
  7. Note: To support failure notification, you must migrate your code to the WebLogic Server asynchronous request-response technology. For more information, see Invoking a Web Service Using Asynchronous Request-Response on the edocs web site.

    The basic outline of the client code would look something like the following.

    public class ClientService
        private ReliableServiceControl reliableServiceControl;
        public void someMethod(String parm) 
            // Invoke the service control method.
        @AsyncFailure(target="reliableServiceControl", operation="doSomething")
          public void onDoSomethingFailure(AsyncPostCallContext apc, Throwable e) 
            // Error handling here
  8. Finally, you'll want to upgrade client service controls. To do so, you'll need a WSDL file representing the fully upgraded web service. The WSDL must contain the policy information needed for reliable messaging. To get a WSDL useful for this purpose, you can use a web browser to display the web service's WSDL using a URL of the following form: <URL_of_deployed_web_service>?WSDL

    With the WSDL in hand, you can do one of the following:

Alternative to Wrapper Classes for Handling SOAP Faults

Supported but deprecated. Version 8.1 provided wrapper classes through which you could control the content of an outgoing SOAP fault, as well as APIs for retrieving content from an incoming SOAP fault. Code using this feature is supported in code upgraded to version 10.0, but the feature is deprecated.

Note that since this feature is deprecated in this release, you should plan to find another solution for future releases, and should not use this feature for new code. For example, consider using the javax.xml.rpc.soap.SOAPFaultException class provided by JAX-RPC. For more information, see Throwing Exceptions in the WebLogic Server documentation on developing web services.

Handlers Not Supported for Callbacks

In version 8.1 the @jc:handler and @jws:handler annotations included a callback attribute that specified handlers to process SOAP messages associated with callbacks; version 10.0 does not include callback-specific handler support. For the counterparts of these annotations in version 10.0, see Upgrading Annotations.

Upgrade Changes for Automatic Transaction Rollback

Supported but deprecated. In version 8.1, the runtime would roll back a container-managed transaction if a checked exception was thrown from the application or runtime. In version 10.0, this behavior is supported with the @Transactional and @WLWRollbackOnCheckedException() annotations added (by upgrade tools) to the web service source code.

General Steps for Replacing XQuery Maps

Version 9.x doesn't support XQuery maps, a version 8.1 feature through which you could use XQuery to reshape XML messages entering and leaving a web service operation. As you might imagine, the shape of the WSDL on which the web service's clients were built is defined in part by XQuery maps because the maps specify the types that map-annotated operations expect to receive or send. With the map removed, expected types are almost certainly different, changing the web service's interface, and causing client calls to fail. Note that this would also change the shape of a WSDL generated from the web service; any other files, such as service controls, generated from a version 8.1 copy of that WSDL will no longer match the web service itself.

Note: The lack of support for XQuery maps does not mean that XQuery itself is not supported. You can still execute XQuery expressions using the XMLBeans API. For more information on upgrade changes impacting this API, see Updating XQuery Use to Support Upgraded XQuery Implementation.

One workaround is to rewrite your web service's operations so that its post-upgrade WSDL matches the version 8.1 WSDL shape, but without XQuery maps. That way, clients calling your web service can rely on the interface contract already established by the version 8.1 web service.

Here are the high-level steps to accomplish this.

  1. In version 8.1 , generate a WSDL file from the version 8.1 web service.
    • In WebLogic Workshop version 8.1, in the Application tab, right-click the JWS file, then click Generate WSDL File.
  2. In version 8.1, use the generated WSDL file to generate source code for a new web service that you will import into your version 10.0 application. This should give you a web service whose operations send and receive XML messages in the same shapes as the mapped operations, but without the maps.
    1. In version 8.1, right-click the WSDL file you generated, then click Duplicate; this will prevent you from overwriting the existing JWS file.
    2. Right-click the duplicate WSDL file, then click Generate Web Service.

      You'll receive a prompt asking whether you'd like to use XMLBeans types for methods of the web service. If you select Yes, the IDE will create methods whose parameters are XMLBeans types to which parts of the incoming message can be bound (this is essentially what the XQuery map was doing). If you select No, the IDE will generate code for inner classes that can be used as parameter types.

      You might find that keeping the XMLBeans types is a more reliable way to ensure that the XML shape required by the operation remains valid after you upgrade the web service.

  3. Using code from the original mapped-operation web service, implement the original service's logic in the newly-generated mapless web service. As part of this process, test the new mapless web service with existing clients to ensure that the old functionality is still present despite the absence of maps.
  4. Use the upgrade tools to upgrade the version 8.1 application (including the mapless web service) to version 10.0. This will do nearly all of the work to update the application (update types, annotations, project structure, and so on).
  5. Test the upgraded web service with existing clients.

Replacing the Use of java.util.Map as a Web Service Operation Return Type

Version 8.1 supported returning instances of java.util.Map from web service operations. The runtime provided a WebLogic Workshop-specific serialization of the Map to and from XML. The schema for that serialization was included in the WSDL for the Web Service. In version 10.0, java.util.Map instances can no longer be returned from web service operations.

Provide an application-defined type that supports the key/value features provided by java.util.Map. That type must conform to JAX/RPC Java <-> XML serialization rules. If the application-defined type will contain subclasses of the type's key or value type, then you must use the weblogic.jws.Types annotation to specify the types that could be contained at run time. Web services (and their clients) that previously returned a java.util.Map will have to be manually updated to use this new application-defined type.

Updating XQuery Use to Support Upgraded XQuery Implementation

Impacts: Code that uses XMLBeans and XQuery, including web services, controls, page flows, Enterprise JavaBeans

The older XQuery implementation is deprecated, but supported in this version for backward compatibility. Queries based on the older implementation will be kept, but a special XmlOptions parameter will be added to specify that the old implementation should be used.

Note: The older implementation is not automatically updated in JSP files. You must manually add the Path._forceXqrl2002ForXpathXQuery option to XQuery code in these files.

The following example shows how upgraded code would look with the XmlOptions parameter specifying the older XQuery engine.

import org.apache.xmlbeans.XmlOptions;

String queryExpression = 
    "for $e in $this/xq:employees/xq:employee " +
    "let $s := $e/xq:address/xq:state " +
    "where $s = 'WA' " +
    "return $e";
    XmlCursor resultCursor = empCursor.execQuery(m_namespaceDeclaration + queryExpression, 
        (new XmlOptions()).put(Path._forceXqrl2002ForXpathXQuery));
    resultXML = resultCursor.getObject();
}catch(Exception e){

Also, you should begin to upgrade XQuery strings so that they conform with the standard supported in version 10.0. For more information on both the old and the new standards, see the links in the following table:

Version 9.0 and 9.1 WebLogic Server Web Services Might Need to Be Recompiled for Deployment in Version 10.0

If you intend to deploy WebLogic Server web services compiled on version 9.0 or 9.1, you might need to be recompile them before deploying on version 10.0. Recompilation is necessary if the web service code contains any of the following annotations.


Keeping Files in Sync in the Absence of IDE Support

The version 8.1 IDE included a set of features through which the IDE kept related files in sync. For example, after generating a ServiceControl from a WSDL, changes to the WSDL would cause the IDE to automatically re-generate the ServiceControl to match. This functionality is not supported in the version 10.0 IDE.

For the following cases, after changes to the "source" WSDL file, the generated file must be manually re-generated using the context menu and the appropriate "Generate..." action:

Version 8.1 Clients are Generally Supported for Interop with Version 10.0 Web Services

However, there will be cases in which version 8.1 clients are only supported for communication with version 10.0 that were upgraded from version 8.1. For example, a version 10.0 web service that has operations annotated with @Oneway results in a WSDL that is not supported in version 8.1.

Related Topics

Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.0


Skip navigation bar   Back to Top