Java WS Core/Final WSRF Migration Guide
From Globus
Contents |
Final WSRF/WSN/WSA specification migration guide
Java WS Core Framework has been updated to use the final version of the WSRF/WSN and WS Addressing specifications. This document provides an overview of the changes and provides a link to the specifications. Note that features that are new in the final specification have not been implemented, only the features from previous specification have been ported.
Updating higher level services
The following is a suggested approach to updating the higher level services.
- WSDL changes
The specification WSDL names have changed and the namespaces have also changed. The section WSDL Files and Namespace Changes provides a mapping from old WSDL file names and namespaces to the new equivalent. All operations in the old specification are in the new specification, so no other WSDL change should be needed.
If your service uses compact and schema directories, ensure that the new WSDLs are correctly written and deployed in schema.
- Stub generation
The old targets for stub generation can be used as it is. Ensure that modified WSDLs have been deployed to GLOBUS_LOCATION before you run the targets.
- Service, client and test code changes
Some class and package names have changed. There is minimal change in the core infrastructure API, but the addressing package has been moved from org.apache to org.globus.
The section Package and class name changes provides a table with some mappings of old to new class names. Note this does not cover all cases, but most commonly used code.
For changes to features and sample code, refer to section on Code change details. The section discussion changes per feature and should provide details on how to edit your code.
Also, Constant changes provides information on some constants that have changed.
You should not have to change anything in your Ant build files or deployment infrastructure.
For samples, you can look at counter service.
Code change details
- WS Addressing
The Apache WS Addressing project is being archived. So the code base has been moved to the Globus repository and has been checked into wsrf/java/lib-src/ws-addressing. The library now has org.globus package names and guarantees support only for the final version of the WS Addressing specification.
One of the key changes in the specification is that Reference Parameters are used now rather than Reference Properties. Java WS Core adds and expects EPR key information in Reference Parameters element now.
- Faults
Unlike the old specification, fault cause consists of a single BaseFaultType, rather than an array of BaseFaultType. The FaultHelper utility has been modified to handle this. Now when a fault cause is added, the helper class walks through the chain of fault causes to find one without a fault cause set and then sets the new cause. Higher level services can continue to use the same API as before and faults should get serialized and deserialized correctly.
If in your testing, you look for a specific error code in a Fault Cause, it is not an array anymore. You will need to walk though the chain of fault causes. An example of such a test is testTargetedXPathQueryInvalidRP()in org.globus.wsrf.impl.properties.QueryResourcePropertiesTests.java.
- Lifetime
The new specificaiton allows SetTerminationTime to have either a xsd:dateTime or xsd:duration. Java WS Core currently does not support duration and only uses the xsd:dateTime value set in the request. A bug in Axis ends up with SetTerminationTime data binding having a contructor that takes two parameters.
- Properties
None of the new methods in the final specification have been implemented. Minor change in schema, which is taken care of in the providers and Simple* implementations.
- Subscribing to notifications
- A new data type Filter has been defined, which is used to provide subscription information, including the Topics to subscribe to.
- Currently we only support TopicExpressionType and hence FilterType is expected to have just one element.
- SubscribeSubscriptionPolicy: the only piece we used before was useNotify. As per latest specification, that is default. If useRaw is set in subscription policy a UnsupportedPolicy fault will be thrown, any other policy set will cause a UnrecogonizedPolocy fault.
- Example subscription request
Subscribe request = new Subscribe();
request.setConsumerReference(consumerEPR);
TopicExpressionType topicExpression = new TopicExpressionType();
topicExpression.setDialect(WSNConstants.SIMPLE_TOPIC_DIALECT);
topicExpression.setValue(Counter.VALUE);
MessageElement element =
(MessageElement)ObjectSerializer
.toSOAPElement(topicExpression, WSNConstants.TOPIC_EXPRESSION);
FilterType filter = new FilterType();
filter.set_any(new MessageElement[] { element });
request.setFilter(filter);
- Unsubscribing notifications
Destroy was used in the old code to remove notification subscription, Unsubscribe should be used now.
SubscriptionManager subscriptionPort =
subscriptionManagerLocator.getSubscriptionManagerPort(
subscriptionEPR);
...
subscriptionPort.unsubscribe(new Unsubscribe());
- Consuming notifications
- Notify message has changed and a new utility has been added to take care of deserialization of the message.
import org.globus.wsrf.encoding.DeserializationException;
import org.globus.wsrf.utils.NotificationUtil;
import org.oasis.wsrf.properties.ResourcePropertyValueChangeNotificationType;
// Notification callback
public void deliver(List topicPath, EndpointReferenceType producer,
Object message) {
ResourcePropertyValueChangeNotificationType changeMessage
= null;
try {
changeMessage = NotificationUtil.getRPValueChangeNotification(message);
} catch (DeserializationException e) {
// handle exception
}
- ResourcePropertyValueChangeNotificationType API has getNewValues() and getOldValues() rather than getNewValue() and getOldValue().
- Subscription Manager Service
This is not relevant, unless you are looking to write a new subcription manager and not use the one in core.
The recent specification defines two port types for subscrition manager: one with pause/resume and another without. To maintain previous functionality the default subscription manager service provided in core uses the pausable subscription manager port type.
GetRP and Destroy are required operations. SetTerminationTime is not required and the required resource propertiesa re consumer reference, filter type, subscription policy and creation time.
The BaseSubscriptionProvider and PausableSubscriptionProvider cover all the required functionality.
(Refer to Subscribing to Notification section above for more details on what is supported)
- Resources that support Subscription
The interface org.globus.wsrf.Subscription has been split into two. A new interface, PausableSubcription has been introduced in the same package and that contains the method for pause/resume functionality. By default, subscription support in core uses the PausableSubcription interface only.
If pause/renew capability is required, resources need to implement PausableSubscription rather than Subscription. If you are looking to maintain old functionality, change to PausableSubscription.
WSDL files and namespace changes
- Old WSDL and namespace mapping
All WSRF/WSN and WSA namespaces have changed. The file names have also changed, but they have been updated in the same directory. This table shows the mapping from old filenames and namespaces to the new ones.
- New additional schema and WSDLs
A WS Resource specificaiton had been added. ResourceUnknown and ResourceUnAvailableFaultType are defined in this namespace, rather than multiple definitions in lifetime and resource in the old specification.
| File name | Namespace |
|---|---|
| wsrf/compact/wsrf/resource/r-2.xsd | http://docs.oasis-open.org/wsrf/r-2 |
| wsrf/compact/wsrf/resource/rw-2.wsdl | http://docs.oasis-open.org/wsrf/rw-2 |
Package names and class name changes
This section describes package name changes and equivalent classes.
| No. | Old Name | New Name |
| 1 | org.oasis.wsrf.lifetime.ResourceUnknownFaultType org.oasis.wsn.ResourceUnknownFaultType org.oasis.wsrf.properties.ResourceUnknownFaultType | org.oasis.wsrf.resource.ResourceUnknownFaultType |
| All these faults have been moved to a single common namespace and hence one package. | ||
| 2 | org.oasis.wsn.TopicPathDialectUnknownFaultType | org.oasis.wsn.TopicExpressionDialectUnknownFaultType |
| Equivalent as per new specification | ||
| 3 | org.apache.axis.message.addressing.Address | org.globus.axis.message.addressing.Address |
| Moved over Apache addressing code to Globus repository and namespace | ||
| 4 | org.apache.axis.message.addressing.EndpointReference | org.globus.axis.message.addressing.EndpointReference |
| Moved over Apache addressing code to Globus repository and namespace | ||
| 5 | org.apache.axis.message.addressing.EndpointReferenceType | org.globus.axis.message.addressing.EndpointReferenceType |
| Moved over Apache addressing code to Globus repository and namespace | ||
| 6 | org.apache.axis.message.addressing.ReferencePropertiesType | org.globus.axis.message.addressing.ReferenceParametersType |
| Moved over Apache addressing code to Globus repository and namespace. Reference parameters are now used to store resource key information. | ||
| 7 | org.globus.axis.message.addressing.AttributedURI | org.globus.axis.message.addressing.AttributedURIType |
| API has changed here. There is no direct to set port/scheme and such. Use getValue() and change the URI that is returned. | ||
| 8 | org.globus.wsrf.impl.notification.PauseSubscriptionProvider | org.globus.wsrf.impl.notification.PausableSubscriptionProvider |
| Refer to notes on Subscription Manager <link me> | ||
Constant changes
| Old Constant | New Constnat |
|---|---|
| WSNConstants.TOPIC | WSNConstants.TOPIC_SET |
| WSNConstants.TOPIC_EXPRESSION_DIALECTS | WSNConstants.TOPIC_EXPRESSION_DIALECT |
Open issues
- Bugs
- Axis does not handle choice elements correctly. The SetTerminationTime data binding allows for a contructor with both xsd:duration and xsd:dateTime while it should be a choice.
- Fault specification changed to use xsd:anyType. Specification WSDL causes some deserialization issues.
- Some generated files are copied over (was present in trunk), potential work around for some Axis issues.
- New specification issues
- Duration not supported in WS Lifetime.
- Subscriptions need not be WS Resource, so potentially a separate interface for Subscription and one that is a WS Subscription.
- Do we need a subscription manager that implements the basic subscription manager interface, without pause/resume ?
- UnableToModifyRPFault, thrown during SetRP operations, has a RPChangeFailureType. This is used to indicate if the property was restored to prior state, but the Java WS Core interface currently don't store/process such information. So it is always assumed that it was not restored.
- Tests
- Is there an updated specification for Widget service ? Is this home grown or a standard ?
- To dos
- Clean WS Addressing such that only final specification handling is available.
- Stub deletion in common file removed. Couldn't see why it was used and things work without that. Unsure if it affects any higher level service.
- Sweeper for subscription removal, there is a comment in PersistenceSubscription remove()
