Web Services
Resource 1.2
(WS-Resource)
OASIS Standard, 1 April 2006
Document identifier: wsrf-ws_resource-1.2-spec-os
Location:
http://docs.oasis-open.org/wsrf/wsrf-ws_resource-1.2-spec-os.pdf
Editors:
Steve Graham, IBM <sggraham@us.ibm.com>
Anish Karmarkar, Oracle <Anish.Karmarkar@oracle.com>
Jeff Mischkinsky, Oracle <jeff.mischkinsky@oracle.com>
Ian Robinson, IBM <ian_robinson@uk.ibm.com>
Igor Sedukhin, Computer Associates <Igor.Sedukhin@ca.com>
Abstract:
This specification defines a WS-Resource, which describes the relationship between a Web service and a resource in the WS-Resource Framework. This document also defines the pattern by which resources are accessed through Web services, and the means by which WS-Resources are referenced.
Status:
This document is an OASIS Standard.
Committee members should
send comments on this specification to the wsrf@lists.oasis-open.org list. Others
may submit comments to the TC via the web form found on the TC's web page at http://www.oasis-open.org/committees/wsrf.
Click the button for "Send A Comment" at the top of the page.
Submitted comments (for this work as well as other works of that TC) are publicly
archived and can be viewed at:
http://lists.oasis-open.org/archives/wsrf-comment/
.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the WSRF TC web page (http://www.oasis-open.org/committees/wsrf/).
Table of Contents
2.2.1 Example SOAP encoding of a message to a WS-Resource
This specification defines a WS-Resource, which describes the relationship between a Web service and a resource in the WS-Resource Framework. This document also defines the pattern by which resources are accessed through Web services, and the means by which WS-Resources are referenced.
The goal of WS-Resource is to standardize the terminology and concepts needed to express the relationship between Web services and resources.
In meeting this goal, the specification MUST address the following specific requirements:
· Define the term “resource.”
· Define the term “WS-Resource”, describing the relationship between Web services and resources.
· Define the means by which a resource can be distinguished in a message exchange between a requestor and a Web service.
· Define the means by which a WS-Resource is referenced.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].
When describing abstract data models, this specification uses the notational convention used by the [XML Infoset]. Specifically, abstract property names always appear in square brackets (e.g., [some property]).
This specification uses a notational convention, refered to as “Pseudo-schemas” in a fashion similar to the WSDL 2.0 Part 1 specification. A Pseudo-schema uses a BNF-style convention to describe attributes and elements:
· `?' denotes optionality (i.e. zero or one occurrences),
· `*' denotes zero or more occurrences,
· `+' one or more occurrences,
· `[' and `]' are used to form groups,
· `|' represents choice.
Attributes are conventionally assigned values which correspond to their types, as defined in the normative schema.
<!-- sample pseudo-schema -->
<element
required_attribute_of_type_QName="xs:QName"
optional_attribute_of_type_string="xs:string"? >
<required_element />
<optional_element />?
<one_or_more_of_these_elements />+
[ <choice_1 /> | <choice_2 /> ]*
</element>
Where there is disagreement between the separate XML schema and WSDL files describing the messages defined by this specification and the normative descriptive text (excluding any pseudo-schema) in this document, the normative descriptive text will take precedence over the separate files. The separate files take precedence over any pseudo-schema and over any schema and WSDL included in the appendices.
The following namespaces are used in this document:
Prefix |
Namespace |
s11 |
http://schemas.xmlsoap.org/soap/envelope/ |
xs |
http://www.w3.org/2001/XMLSchema |
wsa |
http://www.w3.org/2005/08/addressing |
wsdl |
http://schemas.xmlsoap.org/wsdl |
wsrf-r |
http://docs.oasis-open.org/wsrf/r-2 |
wsrf-rw |
http://docs.oasis-open.org/wsrf/rw-2 |
wsrf-bf |
http://docs.oasis-open.org/wsrf/bf-2 |
All faults defined by this specification MUST use the following wsa:Action URI:
http://docs.oasis-open.org/wsrf/fault
The following terms are important in defining the relationship between a Web service and one or more resources.
A resource is a logical entity that has the following characteristics:
A WS-Resource is the composition of a resource and a Web service through which the resource can be accessed. A WS-Resource is further defined as follows:
For a given WS-Resource there may be many references. The way two references are compared for equality is implementation-specific and not defined by this specification.
The following diagram illustrates an example set of components that comprise a small collection of WS-Resources:
In the example above, there is one Web service that has a URL address of “http://www.example.com/service”. This Web service provides access to three resources, identified as “A”, “B” and “C”. WS-Resource-C is the composition of the Web service and the resource identified by “C” and a reference to WS-Resource-C might appear as follows:
<wsa:EndpointReference>
<wsa:Address>
http://www.example.com/service?res=C
</wsa:Address>
...
</wsa:EndpointReference>
A message to the WS-Resource, so referenced, that uses a SOAP 1.1 binding would look as follows:
<s11:Envelope…>
<s11:Header>
<wsa:To>http://www.example.com/service?res=C</wsa:To>
...
</s11:Header>
<s11:Body>
...
</s11:Body>
</s11:Envelope>
A WS-Resource may respond to any message with the following fault message:
wsrf-rw:ResourceUnknownFault
The resource identified in the message is not known to the Web service. The fault may contain additional resource- or application-specific information in it.
wsrf-rw:ResourceUnavailableFault
The resource identified in the message is unavailable. This fault SHOULD indicate a transient condition. A requester might respond to this fault by resending the message.
[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
[WS-Addressing] WS-Addressing 1.0, http://www.w3.org/TR/ws-addr-core/
[WSDL 1.1] Web Services Description Language (WSDL) 1.1, http://www.w3.org/TR/wsdl
[WS-ResourceLifetime] Web Services Resource Lifetime 1.2 (WS-ResourceLifetime), http://docs.oasis-open.org/wsrf/wsrf-ws_resource_lifetime-1.2-spec-os.pdf
[WS-ResourceProperties] Web Services Resource Properties 1.2 (WS-ResourceProperties), http://docs.oasis-open.org/wsrf/wsrf-ws_resource_properties-1.2-spec-os.pdf
[XML-Infoset] XML Information Set (Second Edition), http://www.w3.org/TR/xml-infoset/
[WSA-SOAP] WS-Addressing 1.0 – SOAP Binding, http://www.w3.org/TR/ws-addr-soap/
[WS-I Basic Profile 1.1] http://www.ws-i.org/Profiles/BasicProfile-1.1.html
The following individuals were members of the committee during the development of this specification:
Mario Antonioletti (EPCC, The University of Edinburgh), Akhil Arora (Sun Microsystems), Tim Banks (IBM), Jeff Bohren (OpenNetwork), Fred Carter (AmberPoint), Martin Chapman (Oracle), Glen Daniels (Sonic Software), David De Roure (University of Southampton), Thomas Freund (IBM), John Fuller (Individual), Stephen Graham (IBM), Anish Karmarkar (Oracle), Hideharu Kato (Hitachi), David Levine (IBM), Paul Lipton (Computer Associates), Mark Little (Arjuna Technologies Limited), Lily Liu (WebMethods, Inc.), Tom Maguire (IBM), Susan Malaika (IBM), Mark Mc Keown (University of Manchester), David Martin (IBM), Samuel Meder (Argonne National Laboratory), Jeff Mischkinsky (Oracle), Roger Menday (Forschungszentrum Jlich GmbH), Bryan Murray (Hewlett-Packard), Mark Peel (Novell), Alain Regnier (Ricoh Company, Ltd.), Ian Robinson (IBM), Tom Rutt (Fujitsu), Mitsunori Satomi (Hitachi), Igor Sedukhin (Computer Associates), Hitoshi Sekine (Ricoh Company, Ltd.), Frank Siebenlist (Argonne National Laboratory), Alex Sim (Lawrence Berkeley National Laboratory), David Snelling (Fujitsu), Latha Srinivasan (Hewlett-Packard), Rich Thompson (IBM), Jem Treadwell (Hewlett-Packard), Steve Tuecke (Argonne National Laboratory), William Vambenepe (Hewlett-Packard), Katy Warr (IBM), Alan Weissberger (NEC Corporation), Pete Wenzel (SeeBeyond Technology Corporation), Kirk Wilson (Computer Associates) and Umit Yalcinalp (SAP).
The XML types and elements used in this specification are included here for convenience. The authoritative version of this schema document is available at: http://docs.oasis-open.org/wsrf/r-2.xsd
<?xml version="1.0" encoding="UTF-8"?>
<!--
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.
Copyright (C) OASIS Open (2005). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-->
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsrf-r="http://docs.oasis-open.org/wsrf/r-2"
xmlns:wsrf-bf="http://docs.oasis-open.org/wsrf/bf-2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
elementFormDefault="qualified" attributeFormDefault="unqualified"
targetNamespace="http://docs.oasis-open.org/wsrf/r-2"
>
<xsd:import
namespace=
"http://docs.oasis-open.org/wsrf/bf-2"
schemaLocation="http://docs.oasis-open.org/wsrf/bf-2.xsd"
/>
<!-- ====================== WS-Resource fault types ============= -->
<xsd:complexType name="ResourceUnknownFaultType">
<xsd:complexContent>
<xsd:extension base="wsrf-bf:BaseFaultType"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="ResourceUnknownFault"
type="wsrf-r:ResourceUnknownFaultType"/>
<xsd:complexType name="ResourceUnavailableFaultType">
<xsd:complexContent>
<xsd:extension base="wsrf-bf:BaseFaultType"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="ResourceUnavailableFault"
type="wsrf-r:ResourceUnavailableFaultType"/>
</xsd:schema>
The WSDL 1.1 for the Web service methods described in this specification is compliant with [WS-I Basic Profile 1.1] and is included here for convenience. The authoritative version of this WSDL is available at: http://docs.oasis-open.org/wsrf/rw-2.wsdl
<?xml version="1.0" encoding="utf-8"?>
<!--
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.
Copyright (C) OASIS Open (2005). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-->
<wsdl:definitions name="WS-Resource"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsrf-r="http://docs.oasis-open.org/wsrf/r-2"
xmlns:wsrf-rw="http://docs.oasis-open.org/wsrf/rw-2"
targetNamespace="http://docs.oasis-open.org/wsrf/rw-2"
>
<!-- ===================== Types Definitions ====================== -->
<wsdl:types>
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://docs.oasis-open.org/wsrf/rw-2"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:import
namespace="http://docs.oasis-open.org/wsrf/r-2"
schemaLocation="http://docs.oasis-open.org/wsrf/r-2.xsd"
/>
</xsd:schema>
</wsdl:types>
<!-- ================= WS-Resource faults ========================= -->
<wsdl:message name="ResourceUnknownFault">
<part name="ResourceUnknownFault"
element="wsrf-r:ResourceUnknownFault" />
</wsdl:message>
<wsdl:message name="ResourceUnavailableFault">
<part name="ResourceUnavailableFault"
element="wsrf-r:ResourceUnavailableFault" />
</wsdl:message>
</wsdl:definitions>
Rev |
Date |
By Whom |
What |
wd-01 |
2004-08-27 |
Steve Graham |
Initial version created based on 08/23 and 08/24 meeting amongst the authors. |
wd-02 |
2004-09-02 |
sgg |
Modifications per feedback on 09/01 telecon, and email from Anish and Igor. |
wd-01.a-f |
Various |
sgg |
Reflected various progress |
wd-01g |
2004-09-29 |
sgg |
Reflected final agreements |
wd-02a |
2004-10-07 |
ir |
Editorial and TC issues |
Wd-02.b |
2004-11-22 |
sgg |
Resolved WSRF75 and WSRF76 |
Wd-02 |
2004-12-09 |
ir |
Editorial |
wd-03.a |
2005-02-17 |
ir |
Issues 50, 62, 77, 81, 86, 93, 96 |
Wd-03.b |
2005-03-08 |
Jem Treadwell |
Fixed minor typos. |
Wd-03.c |
2005-04-19 |
ir |
Added reference to WS-I in 5.1. |
Wd-04 |
2005-05-10 |
ir |
Issues: 91, 92, 99, 101 |
wd-05 |
2005-05-16 |
ir |
Issue WSRF 100 |
wd-06 |
2005-05-18 |
ir |
Issues WSRF109, 113, 114, 116 |
pr-01 |
2005-06-10 |
ir |
Change status to PR |
wd-07 |
2005-09-06 |
ir |
127 |
wd-08 |
2005-09-15 |
ir |
Issues 141, 152, 148, 147 |
wd-09 |
2005-09-15 |
ir |
TC review comments |
pr-02.a |
2005-11-05 |
ir |
156 - PR-02 comments |
pr-02.b |
2005-11-21 |
ir |
Editorial corrections |
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.
Copyright (C) OASIS Open (2005). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.