Apache Incubator Project Site > Apache Incubator Projects
Apollo
 

Composing a WSRF WSDL File

Introduction

This tutorial describes how to create a Web Services Description Language (WSDL) file that describes a WSRF WS-Resource. A WSRF WSDL template is provided to expedite the WSDL creation process.

Using the WSRF WSDL Template

To use the template, first make a copy of the template file. For example, on a Windows system, run a command like:

copy _TEMPLATE_.wsdl nameOfYourService.wsdl
Warning
Do not modify the original template file.

Defining the WSRF PortType

A WSRF WSDL should contain only one portType, which is an aggregation of custom resource-specific operations and operations from the following specification-defined portTypes:

WS-ResourceProperties (WSRF-RP) PortTypes

PortType Operations Properties
GetResourceProperty GetResourceProperty
GetMultipleResourceProperties GetMultipleResourceProperties
SetResourceProperties SetResourceProperties
QueryResourceProperties QueryResourceProperties
Note
The GetResourceProperty portType is REQUIRED. The WS-Resource specification states that all WS-Resources MUST implement this portType.

WS-ResourceLifetime (WSRF-RL) PortTypes

PortType Operations Properties
ImmediateResourceTermination Destroy
ScheduledResourceTermination SetTerminationTime CurrentTime,
TerminationTime
Note
In addition to operations, the ScheduledResourceTermination portType also includes two properties. This means that if a WS-Resource implements this portType, it must expose these properties.

The PortType element must have a {http://docs.oasis-open.org/wsrf/2004/11/wsrf-WS-ResourceProperties-1.2-draft-05.xsd}ResourceProperties attribute whose value is the QName of the resource properties document element defined in the types/schema section of the WSDL file.

If you've copied the WSDL template file as described above, your WSDL file already contains a WSRF portType. You simply have to uncomment the blocks corresponding to whichever optional portTypes you want your WS-Resource to support. You should also add any custom operations you want your WS-Resource to expose. The following section describes how to add custom operations.

Adding Custom Operations

You may optionally add custom operations to the WSRF portType. To do so, you will have to define message types, messages, and operations, as you would for any WSDL. It is recommended that, when defining your custom operations, you adhere to the rules defined by section 5 of the WS-I Basic Profile. This will ensure maximum interoperability for your WS-Resource.

Defining Resource Properties

Resource properties are defined in the types/schema section of the WSDL file. In addition to defining custom resource-specific properties, you may also need to add properties that are required by certain specification-defined portTypes. For example, the WSRF-RL ScheduledResourceTermination portType requires two properties (see above). Chapter 4 of the WSRF-RP specification explains how to define resource properties.

If you've copied the WSDL template file as described above, your WSDL file already contains a resource properties document definition. If your WS-Resource implements the WSRF-RL ScheduledResourceTermination portType, simply uncomment the xsd element references, which correspond to the two ScheduledResourceTermination properties. If would like your WS-Resource to allow resource properties with arbitrary names (not generally recommended), simply uncommwent the xsd any element.

An example WSRF WSDL

FileSystem.wsdl is an example of a WSRF WSDL that exposes all of the optional portTypes defined by WSRF-RP and WSRF-RL. It also defines two custom operations, Mount and Unmount, and seven custom resource properties.