 | Level: Intermediate Dan Jemiolo (danjemiolo@us.ibm.com), Advisory Software Engineer, IBM
24 Apr 2007 The WS-ResourceProperties specification defines a standard for declaring strongly-typed properties as part of a Web service interface, but it does not say anything about permissions, validation, and other important topics. Fortunately, the WS-ResourceFramework authors have provided a new specification, WS-ResourceMetadata, that can help you deal with these issues in a standard way. The Apache Muse project provides implementations of both of these specs and lets you associate metadata with your resource properties with just a small XML file. This article describes how to use metadata to secure and validate your properties and how to test different metadata settings.
How do you deal with issues like permissions, validations, and the other important topics that surround declaring strongly-typed properties as part of a Web service interface? There's a new specification in town (from the authors of such hits as WS-ResourceFramework) -- WS-ResourceMetadata (WSRM), which is designed to help you associate metadata with your resource properties with just a small XML file. And, the Apache Muse project has an excellent implementation of both WSRM and WSRF that I'll use to show you how to use metadata to secure and validate your properties and how to test metadata settings.
Before you start, you should be familiar with building Web service endpoints with Apache Muse and understand the basics of WS-ResourceProperties (WSRP). You should also have experience creating WSRP documents and using the Muse framework to manipulate them. If you'd like to get more background on WSRP and Muse before you begin, use the articles and tutorials in Resources.
Creating a WSRP document
In order to demonstrate how metadata can be applied to a WSRP document, you first need a WSRP document. The XML fragment in Listing 1 shows a WSRP document with four resource properties -- one from the WSDM Identity capability (muws1:ResourceId) and three from the WSDM Description capability (muws2:Caption, muws2:Description, and muws2:Version). These properties have varying semantics and provide a good test bed for your use of metadata. The last element in the fragment, <wsdl:portType/>, is a reminder on how a WSRP document is associated with your Web service's interface; this is important after you've created your metadata and want to link it to the WSRP document.
Listing 1. A WSRP document with four resource properties
<wsdl:types>
...
<xsd:schema targetNamespace="http://example.com/test/metadata">
<xsd:element name="MyResourceProperties">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="muws1:ResourceId"/>
<xsd:element ref="muws2:Caption" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="muws2:Description" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="muws2:Version"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
...
<wsdl:portType name="MyPortType"
wsrf-rp:ResourceProperties="tns:MyResourceProperties">
...
</wsdl:portType>
|
According to the WSDM specification, the muws1:ResourceId property is unique to each resource instance and does not change across the life of a resource. The muws2:Caption and muws2:Description properties may change during the lifetime of a resource, and remote clients can even make the change themselves using WSRP's SetResourceProperties operation. Finally, the muws2:Version property is also mutable, but it cannot be modified by remote clients -- it is only to be modified by the resource itself when its configuration has been changed.
Despite all of this, neither the WSDL nor the WSRP document give any indication that these properties have restrictions, nor do they offer any help to a client trying to determine why he cannot perform certain tasks using valid WSRP messages. You will need to augment your descriptors with metadata that will not only enforce your properties' semantics, but do so in a way that is clear to your users.
Creating a WS-ResourceMetadata document
WS-ResourceFramework contains a specification called WS-ResourceMetadata that describes what kind of metadata can be applied to a WSRP document and the format for a resource metadata document (RMD). Let's explore the two most important aspects of an RMD:
Adding permissions to the WSRP document
The first step in creating an RMD is to create an XML file that meets the basic requirements of the WS-ResourceMetadata schema; this means that you must have a <MetadataDescriptor/> element enclosing zero or more <Property/> elements. The XML fragment in Listing 2 contains the beginnings of an RMD that you can use to test out the scenarios described in this article.
Listing 2. It's a start of an RMD for testing purposes
<?xml version="1.0"?>
<Definitions xmlns="http://docs.oasis-open.org/wsrf/rmd-1"
xmlns:muws1="http://docs.oasis-open.org/wsdm/muws1-2.xsd"
xmlns:muws2="http://docs.oasis-open.org/wsdm/muws2-2.xsd"
xmlns:myns="http://example.com/test/metadata">
<MetadataDescriptor name="MyMetadata"
interface="myns:MyPortType"
wsdlLocation="http://example.com/test/metadata MyResource.wsdl">
<Property name="muws1:ResourceId"
modifiability="read-only"
mutability="constant"/>
<Property name="muws2:Caption"
modifiability="read-write"
mutability="mutable"/>
<Property name="muws2:Description"
modifiability="read-write"
mutability="mutable"/>
<Property name="muws2:Version"
modifiability="read-only"
mutability="mutable"/>
</MetadataDescriptor>
</Definitions>
|
There are a couple of things to take away from this RMD:
- There is one
<Property/> element for each resource property defined in the WSRP document.
- Each property definition has two attributes: modifiability and mutability. Modifiability describes whether a remote client can change the property values (read-only versus read-write), while mutability describes whether the resource itself will ever change the property values (constant versus mutable). As shown with
muws2:Version, a property can be mutable but read-only at the same time -- it's a matter of who is making the modifications!
- The
<MetadataDescriptor/> element contains a number of attributes that are required by the RMD spec and which link it back to the WSDL where the WSRP document is defined. You will create a similar link from the WSDL to the RMD later in this article.
Adding validation to the WSRP document
Another great feature provided by the RMD is the ability to define valid values so that clients can reason about the nature of a property (if it is an enumeration) and prevent errors associated with small errors in property values (such as 1.40 versus 1.4.0). Valid values can be specified using either the <ValidValueRange/> element or the <ValidValues/> element; the former lets you set a range of values using simple types (integers, lexicographical strings, and so on), while the latter lets you explicitly state all of the valid values for a property.
To demonstrate the use of RMD validation, I will add valid values to the muws2:Version property so that clients will be able to tell what versions of the resource may be available and thus, what kind of behavior may be supported. In Listing 3, I use <ValidValueRange/> to limit the version numbers to those between 1.4 and 1.5 using the lowerBound and upperBound attributes; note that because I use attributes to describe the values, I can only use simple types when describing a value range:
Listing 3. Limiting the version numbers
<Property name="muws2:Version"
modifiability="read-only"
mutability="mutable">
<ValidValueRange lowerBound="1.4" upperBound="1.5"/>
</Property>
|
The value range is convenient, but it is not entirely accurate in this example; the fact that I give a range from 1.4 to 1.5 prevents me from specifying more detailed version numbers (like 1.4.2, which is not a valid floating-point number) and from excluding versions that don't exist but are technically in the range (for example, 1.4.9). In Listing 4, I use <ValidValues/> to define the exact version numbers that may appear in a resource's WSRP document.
Listing 4. Defining the exact version numbers
<Property name="muws2:Version"
modifiability="read-only"
mutability="mutable">
<ValidValues>
<muws2:Version>1.4.0</muws2:Version>
<muws2:Version>1.4.1</muws2:Version>
<muws2:Version>1.4.2</muws2:Version>
<muws2:Version>1.5.0</muws2:Version>
<muws2:Version>1.5.1</muws2:Version>
</ValidValues>
</Property>
|
Notice that when I specify valid values explicitly using <ValidValues/>, I must include a schema-compliant instance of the resource property; that means that, at the very least, I'll need an XML element with the name of the property to encapsulate the value. You can see this in Listing 4; each version number is part of a <muws2:Version/> element.
Adding the RMD to a Muse-based application
Now that you have your RMD file, you need to associate it with your Web service's interface so that Muse is aware of it. To link the WSRP document to the RMD, you should first save your RMD in the same directory as your WSDL. For projects generated by the Muse WSDL2Java tool, this will be under your project directory in /WEB-INF/classes/wsdl. For the sake of example, I will refer to the RMD file as MyMetadata.rmd. You should now edit your WSDL by adding the following attributes (in bold):
Listing 5. Editing your WSDL
<?xml version="1.0">
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:rmd="http://docs.oasis-open.org/wsrf/rmd-1"
... >
...
<wsdl:portType name="MyPortType"
wsrf-rp:ResourceProperties="tns:MyResourceproperties"
rmd:DescriptorLocation="MyMetadata.rmd"
rmd:Descriptor="MyMetadata" >
...
</wsdl:portType>
...
</wsdl:definitions>
|
The first attribute specifies the name of the RMD file while the second specifies the name of the <MetadataDescriptor/> that contains the resource's metadata. When your Muse-based application starts up and your resources are created, Muse's WSRP implementation uses these attributes to find your RMD file, parse it, and put in place the constructs to enforce it. If a client tries to perform a WSRP operation that goes against the permissions outlined in the RMD, Muse prevents it and logs an error message that details the type of error (permissions versus validation) and what valid operations or values are available.
In conclusion
With one simple document, you can configure Apache Muse to block changes that are from improper places (such as a WSRP Update on muws2:Version) or have improper semantics all together (such as any kind of change to muws1:ResourceId); the Muse run time will also watch for invalid values and prevent changes that would break compliance with the resource's WSRP document. All of this will be done automatically, without any Java™ coding on your part, which makes trying out new metadata configurations as easy as changing an XML file and restarting the Muse-based application.
Resources Learn
Get products and technologies
- Download Apache Muse 2.1.0 to
build and test and the code that is illustrated in this article.
Discuss
About the author | 
| | Dan Jemiolo is an Advisory Software Engineer on IBM's Autonomic Computing team in Research Triangle Park, NC. He led the design and development of Apache Muse 2.0 and continues to work on the project today. Dan also participates in the WS-RF TC as editor of the WS-ResourceMetadata specification and is involved in IBM's strategy for increasing adoption of Web services standards. He came to IBM just over two years ago after earning his Master of Science degree in Computer Science from Rensselaer Polytechnic Institute. |
Rate this page
| |
