|
|
|
|
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 9.2.
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.
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 9.2. When upgraded, this would result in something like the following:
@Conversation(value = Conversation.Phase.START)
@WebMethod()
@WebResult(name = "startShoppingResult")
public void startShopping(int customerId)
{
...
}
// Other stateful operations, including a FINISH operation.
@Conversation(value = Conversation.Phase.NONE)
@WebMethod()
@WebResult(name = "noPhaseResult")
public String butWithOneClick(int customerId)
{
...
}
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 9.2 a conversational web service must have both a START and FINISH operation in order to compile.
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 9.2, 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:
@WebMethod()
@Conversation(Conversation.Phase.START)
public void startConversation()
{
....
}
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.
Version 8.1 included a SOAP 1.2 implementation that was based on a working draft of the SOAP 1.2 specification. The version 9.2 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 9.2) version of the web service. In version 9.2, you can generate a WSDL by right-clicking the web service file in Package Explorer view, then clicking Generate WSDL.
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 9.2 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:
@jws:protocol http-xml="true" — Indicated that the operation or web service supported receiving XML messages over HTTP, without SOAP headers.@jws:protocol jms-xml="true" — Indicated that the operation or web service supported receiving XML messages over the Java Message Service (JMS), without SOAP headers.These attributes and values have no counterparts in version 9.2. If you upgrade to version 9.2, upgrade tools will simply ignore a protocol setting that isn't supported.
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 9.2 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:
@jws:protocol form-get="true" — Indicated that the operation or web service supported receiving HTTP GET requests.@jws:protocol form-post="true" — Indicated that the operation or web service supported receiving HTTP POST requests.These attributes have no counterparts in version 9.2 and there are no suggested workarounds. If you upgrade to version 9.2, upgrade tools will simply ignore a protocol setting that isn't supported.
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 = "http://www.openuri.org/")
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.
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 9 .2 from that WSDL. You can then copy and paste the implementation code from the version 8.1 service to the version 9.2 service.
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 9.2 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.
Even though it was supported for WSDLs associated with version 8.1 service controls, in version 9.2 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.
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 9.2. You can ensure correct handling of xs:anyType by applying the following annotation to the web service at the class level:
@WildcardBindings(
@WildcardBinding(className="org.apache.xmlbeans.XmlObject",
binding=WildcardParticle.ANYTYPE)
)
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 9.2 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:
http://www.w3.org/1999/XMLSchema
http://www.w3.org/1999/XMLSchema-instance
... to these:
http://www.w3.org/2001/XMLSchema
http://www.w3.org/2001/XMLSchema-instance
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.
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.
Due to a difference in the way versions 8.1 and 9.2 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 9.2, 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 "http://www.openuri.org/". 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 9.2, 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 9.2, 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.
Upgrade required. In version 8.1, web service message-level security is managed using WS-Security (WSSE) policy files. In version 9.2 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 9.2 models.
 |
 |
 |
|||||||||||||||||||||||||||||||||||||||
|
|
|
|||||||||||||||||||||||||||||||||||||||
 |
|
 |
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:
security-configuration>
<name>workshop</name>
<realm>
...
<sec:combined-role-mapping-enabled>false</sec:combined-role-mapping-enabled>
<sec:name>myrealm</sec:name>
</realm>
<default-realm>myrealm</default-realm>
</security-configuration>
For more information on the combined role mapping setting and how it impacts security, see Understanding the Combined Role Mapping Enabled Setting.
Workshop for WebLogic upgrade tools do not upgrade reliable messaging support (such as the @jws:reliable annotation) from version 8.1 to version 9.2. 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 9.2.
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 9.2 annotations related to reliable messaging are not automatically added to upgraded code. Instead, you can manually add version 9.2 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.
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:
@Transactional(true)
@UseWLW81BindingTypes()
@WLHttpTransport(serviceUri = "reliable/ReliableService.jws")
@WLWRollbackOnCheckedException()
@WebService(serviceName = "ReliableService",
targetNamespace = "http://www.openuri.org/")
@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 java.io.Serializable
{
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)
@WebMethod()
@Oneway()
@WebResult(name = "doSomethingResult")
public void doSomething()
{
...
}
...
}
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.
@WebService
public class ClientService
{
@Control()
private ReliableServiceControl reliableServiceControl;
@WebMethod()
public void someMethod(String parm)
{
// Invoke the service control method.
reliableServiceControl.doSomething(parm);
}
@AsyncFailure(target="reliableServiceControl", operation="doSomething")
public void onDoSomethingFailure(AsyncPostCallContext apc, Throwable e)
{
// Error handling here
}
}
With the WSDL in hand, you can do one of the following:
<s0:Policy s1:Id="ReliableServicePolicy.xml">
<wsrm:RMAssertion xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm">
<wsrm:InactivityTimeout Milliseconds="600000"/>
<wsrm:AcknowledgementInterval Milliseconds="200"/>
<wsrm:BaseRetransmissionInterval Milliseconds="3000"/>
<wsrm:ExponentialBackoff/>
<beapolicy:Expires Expires="P1D" xmlns:beapolicy="http://www.bea.com/wsrm/policy"/>
</wsrm:RMAssertion>
</s0:Policy>
<wsp:UsingPolicy n1:Required="true" xmlns:n1="http://schemas.xmlsoap.org/wsdl/"/>
For the annotation's uri attribute, specify the value in the <Policy> element's Id attribute. For the annotation's direction attribute value, specify ServiceControl.Direction.both. Here's an example:
@ServiceControl.Policy(uri="ReliableServicePolicy.xml", direction=ServiceControl.Direction.both) public interface ReliableServiceControl extends com.bea.control.ServiceControl
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 9.2, 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.
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 9.2 does not include callback-specific handler support. For the counterparts of these annotations in version 9.2, see Upgrading Annotations.
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 9.2, this behavior is supported with the @Transactional and @WLWRollbackOnCheckedException() annotations added (by upgrade tools) to the web service source code.
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.
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.
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 9.2, 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.
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.impl.store.Path;
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";
try{
XmlCursor resultCursor = empCursor.execQuery(m_namespaceDeclaration + queryExpression,
(new XmlOptions()).put(Path._forceXqrl2002ForXpathXQuery));
resultXML = resultCursor.getObject();
resultCursor.dispose();
}catch(Exception e){
System.out.println(e.getLocalizedMessage());
}
Also, you should begin to upgrade XQuery strings so that they conform with the standard supported in version 9.2. For more information on both the old and the new standards, see the links in the following table:
|
|
|
||||||
|
|
|
||||||
|
|
|
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 9.2. Recompilation is necessary if the web service code contains any of the following annotations.
weblogic.jws.Conversation
weblogic.jws.Context
weblogic.jws.Callback
weblogic.jws.ServiceClient
org.apache.beehive.controls.api.bean.Control
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 9.2 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:
However, there will be cases in which version 8.1 clients are only supported for communication with version 9.2 that were upgraded from version 8.1. For example, a version 9.2 web service that has operations annotated with @Oneway results in a WSDL that is not supported in version 8.1.
Changes During Upgrade from WebLogic Workshop 8.1 to Version 9.2
 |