Copyright © 2004 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is theW3CLastCallWorkinga Candidate Recommendation of the DraftSOAPResourceRepresentationHeaderdocument.W3C.
This document has been produced by the
XML Protocol Working Group It(WG),which(WG)
as part of the W3C
Web Services Activity.
isDiscussionPublication as a Candidate Recommendation does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document oftakesplaceonthepublicxml-dist-app@w3.orgmailinglist(publicarchive)undertheemailcommunicationas other than work in progress.
rules
This document is based upon the
XMLSOAP Resource Representation Header
Last Call Working ProtocolGroupCharter.Draft published on Commentsthisdocumentarewelcome.Sendthembefore8 June 292004.
Changes between these two versions are described in a diff document.2004
The public is invited to send comments to the public mailing list
xmlp-comments@w3.org(publicxmlp-comments@w3.org
(Archive).
archive)
NotethatallThe WG is soliciting implementation reports on this draft until at least
15 September 2004. All issues against this document are documented in the outstandingWorkingGroupLastWG's
Candidate Recommendation Issues List. CallWhen implementations of this
document's important features are demonstrated to be interoperable between
2 or more different implementations, and the IffeedbackWG responds formally to all
issues against this ondocumentisdocument, then the WG plans to submit it for
consideration as a W3C positive,Proposed Recommendation. Records of the
interoperation of this document's features are recorded on the WG's
Implementation Summary of Optimizations webpage.
Candidate
This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
1 Introduction
1.1 Notational Conventions
1.2 Relation to other specifications
1.2.1 Relationship to the SOAP Processing model
2 SOAP Feature Name
3 SOAP Module Name
4 Representation Header Block 2.1
4.1 Introduction
4.2 Representation header block Constructs 2.2
4.2.1 rep:Representation element 2.2.1
4.2.2 resource attribute 2.2.2
4.2.3 reinsert attribute 2.2.3
4.2.4 rep:Data element 2.2.4
4.3 Extensibility of the Representation header block 2.3
4.3.1 SOAP header block Attributes 2.3.1
4.3.2 Specifying the media type 2.3.2
4.3.3 Extension example: HTTP 2.3.3resolver extensionheaders
A References
B Acknowledgements (Non-Normative)
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 [RFC 2119].
This specification uses a number of namespace prefixes throughout; they are listed in [Prefixes and Namespaces used in this specification.]. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).
Prefix | Namespace |
---|---|
Notes | |
env | "http://www.w3.org/2003/05/soap-envelope" |
A normative XML Schema [XML Schema Part 1], [XML Schema Part 2] document for the "http://www.w3.org/2003/05/soap-envelope" namespace can be found at http://www.w3.org/2003/05/soap-envelope. | |
rep | |
A normative XML Schema [XML Schema Part 1], [XML Schema Part 2] document for the
| |
xs | "http://www.w3.org/2001/XMLSchema" |
The namespace of XML Schema data types (see [XML Schema Part 2]). | |
xmlmime | "http://www.w3.org/2004/06/xmlmime" |
The namespace for representing MIME media-types in XML (see [Assigning Media Types to Binary Data in XML]). |
All parts of this specification are normative, with the exception of examples and sections explicitly marked as "Non-Normative".
This document along with [XOP] and [MTOM]
has been produced in conjunction with the development of
requirements, embodied in the requirements document [SOAP Optimized Serialization Use Cases and Requirements].
TBD
This document defines a SOAP Feature, and a SOAP Module that realizes the SOAP Feature, as specified by SOAP 1.2 [SOAP Part 1] 3.1 SOAP Features and [SOAP Part 1] 3.3 SOAP Modules.
Note: The Resource Representation header block is designed to optimize well when used with the SOAP Message Transmission Optimization Mechanism [MTOM].
Note: The Resource Representation header block is designed, but not required, to be used in conjunction with the Assigning Media Types to Binary Data in XML specification [Assigning Media Types to Binary Data in XML].
The Resource Representation header block defined by this document embodies the SOAP feature [SOAP Part 1] 3.1 SOAP Features identified by the URI:
"http://www.w3.org/2004/08/representation"
The above SOAP feature URI can be used to identify the semantics and serialization of the Resource Representation header block.
The SOAP Module [SOAP Part 1]
3.3 SOAP Modules that realizes the SOAP feature makesnochangesdefined
in 2 SOAP Feature Name is identified by the URI:
to
"http://www.w3.org/2004/08/representation"
The above SOAP processingmodel.Module URI can be used to identify the semantics and
serialization of the Resource Representation header block.
2
The Representation header block is designed to allow applications to
carry a representation of a Web resource in a SOAP message. Applications
of this header include cases where the receiver has limited ability
to get the representation using other means, for example because of
access restrictions or because the overhead would be unacceptable. The
Representation header block is also representationuseful when multiple references to the
same requiredextractedresource are required but duplication of contentextractedthe resource
is undesirable. See UC2 and UC6 [SOAP Optimized Serialization Use Cases and Requirements] for details.
content
The meaning of the Representation header block, when present in a
SOAP message, is to make available the contained representation of
the resource it carries to the processing SOAP node. The SOAP node
MAY use this representation when dereferencing the URI of the
resource instead of making a network request to obtain a representation of
the resource.
Note that implementations MAY need to process a Representation header
block before processing other header blocks that require
dereferencing of a URI whose representation is carried in the
Representation header block.
given
Multiple occurences of the Representation header block MAY be present
in the same SOAP Message to carry Severalrepresentation of representationsmultiple Web
severalresources or resourceseveralmultiple representations of the same Web resource.
representation
Several occurences of the Representation header block having the same
value for the role
and resource
attribute information item
(see 4.2.2 resource attribute) MAY be present in the same SOAP
Message. Such Representation header blocks SHOULD NOT have the same
metadata (such as media-type). If such Representation header blocks
have the same metadata then any one of them may be used.
2.2.2
An example SOAP Envelope using the Representation header block is given below.
rep:Representation
element
The Representation
element information item
has:
One or more attribute information items amongst its [attributes] property as follows:
A mandatory resource
attribute information
item (see 4.2.2 resource attribute).
2.2.2
An optional reinsert
attribute information
item (see 4.2.3 reinsert attribute).
2.2.3
AnyZero or more namespace qualified attribute information
items otherwhose [namespace name] is not
"http://www.w3.org/2004/08/representation".
.
One or more element information items in its [children] property in order as follows:
A mandatory Data
element information
item (see 4.2.4 rep:Data element).
2.2.4
AnyZero or more element information otheritemwithitems
whose [namespace name] adifferentthanis not
"http://www.w3.org/2004/08/representation".
"http://www.w3.org/2004/02/representation".
The rep:Representation
element information
item contains a representation of a Web resource. The
value of the resource
element information
item is the URI identifying the Web resource. The value of
the rep:Data
element information item is a
base64-encoded representation of the Web resource.
reinsert
attribute
The reinsert
attribute information item
has:
The type of the reinsert
attribute information
item is xs:boolean
. When this attribute is
specified on the Representation header block with a value of
"true", it indicates that a SOAP forwarding
intermediary node processing the
header block must reinsert the header block. This means that when
used in conjunction with the relay
attribute, defined
in [SOAP Part 1]
5.2.4 SOAP Relay Attribute, with a value of
"true", the Representation header
block will always be relayed by a SOAP forwarding intermediary.
When this attribute is specified on the Representation header block
with a value of "false", the behavior of the SOAP
node processing the header block is the same as that when the
attribute is not specified, and normal SOAP processing rules
apply. The presence of this attribute has no effect on the
processing of a Representation header by a SOAP endpoint.
Attributes defined in [SOAP Part 1] 5. SOAP Message Construct for SOAP header blocks MAY be used with the Representation header block.
Adding a env:mustUnderstand
attribute information
item with a value of "true" in the
[attributes] property of the rep:Representation
element information item ensures that the SOAP receiver
is aware that the Web resource representation is available to it.
A env:role
attribute information item in
the [attributes] property of the rep:Representation
element information item indicates the SOAP node for
which the Web resource representation is intended.
An xmlmime:contentType
attribute information item
(See [Assigning Media Types to Binary Data in XML]) MAY be used to convey the
media type of the representation conveyed by a header. Media type
information can be useful in determining whether a given representation
is suitable for processing and if it is, how best to interpret the
representation provided. If used, the xmime:contentType
attribute information item MUST appear within the
[attribute] property of the rep:Data
element information item. An example of this usage is shown
in Example show.
Example
This specification is the work of the W3C XML Protocol Working Group.
This document has its genesis as a separate section in the SOAP Message Transmission Optimization Mechanism (MTOM) document. The editors of the MTOM document, specifically Mark Nottingham and Hervé Ruellan are gratefully acknowledged.
The people who have contributed to discussions on xml-dist-app@w3.org are also gratefully acknowledged.