Home arrow Web Services arrow Page 3 - Notifications and Resources in the WS-Resource Framework
WEB SERVICES

Notifications and Resources in the WS-Resource Framework


This article concludes our discussion of the WS-Resource Framework, a set of proposed standards that formalizes the relationship between Web services and state. In this part, we finish covering notifications and go into greater detail about resources. It is excerpted from chapter 8 of the book Building Web Services with Java: Making sense of XML, SOAP, WSDL, and UDDI, written by Steve Graham et al. (Sams; ISBN: 0672326418).

Author Info:
By: Sams Publishing
Rating: 5 stars5 stars5 stars5 stars5 stars / 4
July 20, 2006
TABLE OF CONTENTS:
  1. · Notifications and Resources in the WS-Resource Framework
  2. · Notification Consumers
  3. · Resource Lifetime
  4. · Initializing Termination Time
  5. · Notification of WS-Resource Termination
  6. · Other WS-Resource Framework Specifications

print this article
SEARCH DEVARTICLES

Notifications and Resources in the WS-Resource Framework - Resource Lifetime
(Page 3 of 6 )

We discussed previously how resources are created: Some sort of operation (like the doSubmission operation) on a Web service creates a new WS-Resource and returns a WS-Resource–qualified endpoint reference to the requestor. We call this sort of operation a WS-Resource factory. However, we haven't discussed the other aspect of a resource's lifetime: its termination.

WS-ResourceLifetime is a part of the WS-Resource Framework family of specifications that standardizes how WS-Resources are terminated. There are two mechanisms for terminating a resource: immediate and scheduled termination. Designers are free to use either or both of these mechanisms to specify how their resources can be destroyed. You encode this decision into the portType definition of the Web service responsible for the WS-Resource in a style similar to how WS-ResourceProperties operations were mixed into the operation: by copying the WSDL operation definitions.

SkatesTown decided to allow both forms of resource termination, immediate and scheduled, to act on PurchaseOrder WS-Resources. In certain cases, customers want to be able to explicitly and immediately destroy a PurchaseOrder resource. In other cases, customers place an order and then occasionally renew interest in the PurchaseOrder resource; or, if business needs change, they abandon the PurchaseOrder and have it automatically terminate after a period of inactivity. In fact, as you'll see toward the end of this section, SkatesTown also implemented the part of WS-ResourceLifetime that allows its customers to subscribe for notification messages when their PurchaseOrder WS-Resources are destroyed.

Immediate Termination

Immediate termination of a WS-Resource is straightforward. If the Web service associated with the WS-Resource supports the immediate termination form of resource termination, then the requestor can terminate the resource at any time by sending a destroy request message to the Web service. Of course, the exact resource to destroy is identified using the implied resource pattern. After the destroy request is received, the Web service must destroy the WS-Resource and respond with a normal destroy response or a fault message if it can't be destroyed.

If a normal response is received, the requestor knows the WS-Resource has been destroyed; the WS-Resource can no longer be used as context for another Web service message. The implementation is free to reclaim whatever system resources were used to support the WS-Resource. This is a synchronous style of termination, and it should be used only if WS-Resource destruction can be accomplished and assured relatively quickly. If it's complicated or time-consuming to destroy a WS-Resource, you should use the scheduled termination mechanism instead (see the next section).

In order for a Web service to support immediate termination, you must copy and paste the WSDL operation definition for the destroy operation from the portType defined in the WS-ResourceLifetime specification. The POPortType supports immediate termination of PurchaseOrder resources. Here is the part of the POPortType WSDL that defines this operation:

...
xmlns:wsrl=
"http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceLifetime" ... <!-- ====
extends wsrl:ImmediateResourceTermination =========
--> <wsdl:operation name="Destroy"> <wsdl:input message="wsrl:DestroyRequest" /> <wsdl:output message="wsrl:DestroyResponse" /> <wsdl:fault name="ResourceUnknownFault" message="wsrl:ResourceUnknownFault" /> <wsdl:fault name="ResourceNotDestroyedFault" message="wsrl:ResourceNotDestroyedFault" /> </wsdl:operation>

The wsrl: prefix is a conventional prefix to denote the WS-ResourceLifetime namespace.

That's all there is to it. Without this form of standardization, the way to terminate resources would vary between applications. Some Web services would call the operation destroy; others might call the operation terminate, kill, or exit. Providing standardization removes this impediment to interoperability.

Scheduled Termination

An alternate form of WS-Resource termination is called scheduled termination. This is a time-based mechanism to manage the lifetime of a WS-Resource. In a scheduled or time-based approach to resource termination, the WS-Resource is created with an initial termination time—a time in the future that marks when the WS-Resource will be terminated. Entities in the system, like user applications, that want to keep working with the WS-Resource will periodically attempt to reset the termination time to extend the lifetime of the WS-Resource. If the termination time elapses, because no other entity was interested in (or capable of) extending the lifetime of the WS-Resource, the WS-Resource is destroyed.

Scheduled termination is a little more complicated than immediate termination. In order for a WS-Resource's lifetime to be managed in this time-based way, its Web service must implement two resource property elements (CurrentTime and TerminationTime)and one operation (SetTerminationTime).

The wsrl:CurrentTime resource property element allows requestors to query (using WS-ResourceProperties operations like GetResourceProperty) the current time according to the Web service managing a particular WS-Resource. This resource property helps requestors understand how much time remains before a WS-Resource is scheduled to be terminated. Note that the wsrl:CurrentTime resource property is read-only; it can't be set by the WS-ResourceProperties' SetResourceProperties operation.

Times in WS-ResourceLifetime follow the dateTime type defined by XML Schema. XML Schema provides an optional component of the dateTime type to specify time zone. In WS-ResourceLifetime, the absence of this time zone component means that the time is to be interpreted in universal time (UTC) format.

The wsrl:TerminationTime resource property element allows the requestor to query when the WS-Resource is scheduled to be destroyed. This is the resource property that is updated when requestors attempt to reset the termination time of the WS-Resource. When the termination time has expired, the WS-Resource may be destroyed by its hosting environment. The timing and nature of this destruction are implementation dependent; however, the requestor shouldn't count on the WS-Resource being available after its termination time has elapsed.

Some resources have a value of xsi:nil for their termination time. This value indicates that the WS-Resource has indefinite lifetime; it won't be destroyed using a time-based mechanism. When a WS-Resource is set to an indefinite lifetime, it can be destroyed only using the immediate termination operation.

The wsrl:TerminationTime resource property element is also read-only, like wsrl:CurrentTime. In order to reset the termination time of a WS-Resource, a requestor needs to use the SetTerminationTime operation. Although the designers of WS-ResourceLifetime could have used the SetResourceProperties operation to change the value of the TerminationTime resource property, the semantics of the SetTerminationTime operation are slightly more sophisticated than a simple update.

Here is the section of the PurchaseOrder WS-Resource's resource properties document definition that contains the necessary scheduled termination resource property element definitions:

...
<xsd:element name="poResourceProperties">
<xsd:complexType>
<xsd:sequence>
...
<!-- ==== Resource Properties for
ScheduledResourceTermination ==== --> <xsd:element ref="wsrl:CurrentTime"
minOccurs="1" maxOccurs="1"/> <xsd:element ref="wsrl:TerminationTime"
minOccurs="1" maxOccurs="1"/> ...

If a requestor wishes to change the termination time of a WS-Resource, it uses the SetTerminationTime operation to give the WS-Resource a new termination time. If the implementation of the WS-Resource is willing to accept the new termination time, then the request causes the wsrl:TerminationTime resource property to have a new value.

Consider the following series of exchanges from our PurchaseOrder WS-Resource example. The Skateboard Warehouse created a PurchaseOrder WS-Resource. At any time, their applications can examine the current value of the termination time of the PurchaseOrder by issuing a GetResourceProperty operation (from WS-ResourceProperties) to get the current value of the wsrl:TerminationTime resource property. In fact, it's often handy to retrieve both the termination time and the current time, as shown in the following GetMultipleResourceProperties SOAP request:

<soap:Envelope
...
<soap:Header>
...
<!-- the reference property to id the PO -->
<poRP:POResourceID>43871</poRP:POResourceID> 
</soap:Header>
<soap:Body>
<wsrp:GetMultipleResourceProperties>
 <wsrp:ResourceProperty>wsrl:TerminationTime</wsrp:
ResourceProperty>w
<wsrp:ResourceProperty>wsrl:CurrentTime</wsrp:
ResourceProperty>w
</wsrp:GetMultipleResourceProperties> </soap:Body> </soap:Envelope>

By asking for both the termination time and the current time, the application has a better sense of how much time remains before the termination time elapses. The application can then estimate how much longer it will need the PurchaseOrder and calculate a new termination time. The application can then send a SetTerminationTime request to update the termination time of the PurchaseOrder:

<soap:Envelope
...
<soap:Header>
...
<!-- the reference property to id the PO -->
<poRP:POResourceID>43871</poRP:POResourceID>
</soap:Header>
<soap:Body>
<wsrl:SetTerminationTime>
<wsrl:RequestedTerminationTime>
2004-03-02T12:00:00
</wsrl:RequestedTerminationTime>
</wsrl:SetTerminationTime>
</soap:Body>
</soap:Envelope>

This new termination time must be in the future relative to the WS-Resource's current time. If the requestor requests a termination time in the past relative to the WS-Resource's current time, then the requestor is saying that it wants the WS-Resource destroyed immediately. This is subtly different from immediate destruction; whereas immediate destruction is a synchronous operation, using the SetTerminationTime operation and passing in a termination time in the past is an asynchronous means to achieve immediate destruction of the WS-Resource. The actual process of destroying the WS-Resource and reclaiming system resources used to support the WS-Resource happens at any time, independently of when the SetTerminationTime operation responds to the requestor. The implementation could even fail to destroy the WS-Resource.

The requestor can also try to give the WS-Resource an indefinite lifetime by using xsi:nil as the parameter of the SetTerminationTime operation. For example, if The Skateboard Warehouse wishes to make its PurchaseOrder WS-Resource permanent, then it sends the following request message:

<soap:Envelope
...
<soap:Header>
...
<!-- the reference property to id the PO -->
<poRP:POResourceID>43871</poRP:POResourceID> 
</soap:Header>
<soap:Body>
<wsrl:SetTerminationTime>
<wsrl:RequestedTerminationTime xsi:nil="true"/>
</wsrl:SetTerminationTime>
</soap:Body>
</soap:Envelope>

Of course, the Web service managing the WS-Resource may not accept the new termination time suggested by the requestor in the SetTerminationTime request. For example, the implementation may be unwilling to allocate the system resources required to support the WS-Resource for as long as requested. Many implementations may be unlikely to accept the attempt to give the WS-Resource an indefinite lifetime. If an implementation rejects the termination time request, it might give information in the fault response to indicate how long it's willing to extend the termination time.

Just as with the immediate termination, you indicate that a WS-Resource can be managed using scheduled termination by inserting the definition for the SetTerminationTime operation into the WSDL definition of the Web service managing that WS-Resource. For example, the POPortType was extended to include the SetTerminationTime by copying and pasting the WSDL operation definition for SetTerminationTime:

...
<wsdl:portType name="POPortType"
...
<!-- ==== extends wsrl:
ScheduledResourceTermination ========= --> <wsdl:operation name="SetTerminationTime"> <wsdl:input message="wsrl:
SetTerminationTimeRequest" /> <wsdl:output message="wsrl:
SetTerminationTimeResponse" /> <wsdl:fault name="ResourceUnknownFault" message="wsrl:ResourceUnknownFault" /> <wsdl:fault name=
"UnableToSetTerminationTimeFault" message="wsrl:
UnableToSetTerminationTimeFault" /> <wsdl:fault name=
"TerminationTimeChangeRejectedFault" message="wsrl:
TerminationTimeChangeRejectedFault" /> </wsdl:operation> ...


blog comments powered by Disqus
WEB SERVICES ARTICLES

- Dealing with Loose Coupling in a Service-Ori...
- Loose Coupling in a Service-Oriented Archite...
- Safety, Idempotence, and the Resource-Orient...
- The Resource-Oriented Architecture in Action
- Features of the Resource-Oriented Architectu...
- The Resource-Oriented Architecture
- Getting Started with Flex
- Automated Billing and Faxing for the Web
- An Introduction to Web Services
- The Foundations of Web Services: From Novice...
- Web Services Reengineering: Finishing Touches
- Fault Handling with Web Services
- Flow and Web Services
- Process Lifecycles and Web Services
- Business Processes and Web Services

Watch our Tech Videos 
Dev Articles Forums 
 RSS  Articles
 RSS  Forums
 RSS  All Feeds
Write For Us 
Weekly Newsletter
 
Developer Updates  
Free Website Content 
Contact Us 
Site Map 
Privacy Policy 
Support 

Developer Shed Affiliates

 




© 2003-2017 by Developer Shed. All rights reserved. DS Cluster - Follow our Sitemap
Popular Web Development Topics
All Web Development Tutorials