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 the work of the W3C XML Protocol Working Group (WG). The Attachment Feature document has been superceded by the SOAP Message Transmission Optimization Mechanism document which describes attachment related features along with some implementation details. The XMLP WG does not intend to do any further work on the Attachment Feature document.
Discussion of this document takes place on the public xml-dist-app@w3.org mailing list (public archive) under the email communication rules in the XML Protocol Working Group Charter .
The XML Protocol Working Group is part of the Web Services Activity.
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.
Publication as a Working Group Note 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 as other than work in progress.
1 Introduction
1.1 Notational Conventions
1.2 Conformance
2 SOAP Feature Name
3 Terminology
4 Compound SOAP Structure Model
5 Attachment Feature properties
5.1 Sending a compound SOAP structure
5.2 Receiving a compound SOAP structure
6 Implementation
7 Intermediaries
8 Internationalization Considerations
9 Security Considerations
10 IANA Considerations
11 References
11.1 Normative References
11.2 Informative References
A Contributors
B History
B.1 5 december 2002
B.2 4 november 2002
B.3 31 october 2002
B.4 31 July 2002
B.5 30 July 2002
B.6 22 July 2002
SOAP 1.2 part 1 (see [SOAP Part 1]) provides a flexible and extensible envelope for describing structured information intended for exchange between SOAP nodes. Even though SOAP 1.2 is described in terms of [XML Infoset], it is expected that [XML 1.0] will be a widely used representation for SOAP data.
The following problems can arise when using such an [XML 1.0] representation for SOAP data:
Encapsulation of binary data in the form of image files etc. cannot be done without additional encoding/decoding of the data. The overhead of encoding binary data in a form acceptable to XML (for example using base64 as defined by [RFC 2045]) is often significant both in terms of bytes added because of the encoding as well as processor overhead performing the encoding/decoding.
Encapsulation of other XML documents as well as XML fragments is cumbersome within a SOAP message--especially if the XML parts do not use the same character encoding.
Although SOAP messages inherently are self-delimiting, the message delimiter can only be detected by parsing the complete message. This can imply a significant overhead in generic message processing as well as parsing and memory allocation.
The compound message structures provided by this specification MAY be used to create SOAP bindings, or other specifications to be used by bindings, that avoid some or all such problems.
The purpose of this specification is not to define an actual representation of SOAP attachments but rather to define an abstract SOAP 1.2 feature which can be used as the basis for defining SOAP bindings that support the transmission of messages with attachments. The feature describes characteristics common to all such implementations.
The key words "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].
This Attachment Feature is identified by the URI
(see [SOAP Part 1] SOAP Protocol Binding Framework)
:
"http://www.w3.org/2002/06/soap/features/attachment" .
Property Name | Property Description |
---|---|
SOAPMessage
| An abstract structure that represents the primary SOAP message part of the compound SOAP structure. |
SecondaryPartBag
| An abstract structure that represents the compound SOAP structure's secondary part(s). This structure is a bag that contains representations of each of the compound SOAP structure's secondary part(s). A secondary part representation can be a URI referencing this secondary part, an abstract structure representing the secondary part itself, or both. |
http://www.w3.org/2002/06/soap/features/attachment/SOAPMessage
http://www.w3.org/2002/06/soap/features/attachment/SecondaryPartBag
For example, the Request-Response Message Exchange Pattern in the [SOAP Part 2] specification defines a reqres:OutboundMessage property that represents the current outbound message in the message exchange. If the Request-Response Message Exchange Pattern is used in conjunction with this feature, then the reqres:OutboundMessage property is initialized to represent the compound SOAP Structure (see diagram below).
Property Name | Property Value |
---|---|
SOAPMessage
| A representation of the primary SOAP message part of the outbound message. |
SecondaryPartBag
| A representation of all the secondary parts of the outbound message. |
Property Name | Property Value |
---|---|
SOAPMessage
| A representation of the primary SOAP message part of the inbound message. |
SecondaryPartBag
| A representation of all the secondary parts of the inbound message. |
A binding that supports the transmission of compound SOAP structures MUST provide the following:
A mechanism by which each part is identified using one (or more) URI(s)
(see [SOAP Part 1] Use of URIs in SOAP)
. The URI scheme used MAY but need not be the same for all parts. The URI scheme used for multiple identifiers of a single part MAY but need not be the same.
Note: the ability to identify a single part with multiple URIs is provided because, in general, the Web architecture allows such multiple names for a single resource. It is anticipated that most bindings will name each part with a single URI, and through the use of base URIs, provide for absolute and/or relative URI references to that URI.
The compound SOAP structure model is independent of the underlying protocol used for transmitting the primary SOAP message part and any of the secondary parts. That is, there is no requirement that all parts of a compound SOAP structure representation be transmitted within the same unit of the underlying protocol. Note that in some cases, the underlying protocol may also provide the functionality of the encapsulation mechanism.
As an example of possible representations that a binding might implement, consider a compound SOAP structure consisting of a primary SOAP message part containing an insurance claim for a damaged car and a secondary part containing a JPEG image of the car. Such a compound structure can be represented in several ways including but not limited to the following:
The primary SOAP message part and the JPEG image may be encapsulated in a single DIME message and transmitted using an underlying protocol such as TCP or HTTP ([RFC 2616]) (see [WS-Attachments]).
The primary SOAP message part and the JPEG image may be encapsulated in a single MIME Multipart/Related message ([RFC 2387]) and transmitted using an underlying protocol such as HTTP ([RFC 2616]) (see [SOAP with attachments]).
The primary SOAP message part may be exchanged using the HTTP protocol binding without any further encapsulation
,
and the JPEG image
retrieved at the application's discretion
using a separate HTTP GET request.
A binding that supports this feature MUST provide a means by which receivers can distinguish the primary SOAP part from the secondary parts. A SOAP receiver that supports this feature MUST process the primary SOAP message part according to the rules for processing SOAP messages (see [SOAP Part 1]).
Compound SOAP structures MAY be nested by having a secondary part of a compound SOAP structure contain another compound SOAP structure. In this case, the primary SOAP message part is the primary SOAP message part of the outermost compound SOAP structure and as for any other secondary part, the semantics of the primary SOAP message part provides the processing context for the nested compound SOAP structure(s).
While a binding that supports this feature MAY provide mechanisms for verifying the integrity and enumerating the parts of a compound SOAP structure, this is not a requirement of this feature.
A SOAP intermediary MUST be able to access any secondary part.
This specification does not introduce internationalization considerations beyond what is introduced by [SOAP Part 1], and URIs ([RFC 2396]). This specification refers to the specific considerations described by those specifications.
Security considerations for media types in general are discussed in [RFC 2048] and in the context of the "application/postscript" and the "message/external-body" media type in [RFC 2046].
To address concerns about integrity and confidentiality, secondary parts can be digitally signed and encrypted. Typically, a compound SOAP structure that contains signed or encrypted secondary parts would include security information about the secondary parts in a security header of the primary SOAP message part. This specification does not provide a means to protect a message by encrypting and/or digitally signing a body, a header, a secondary part, or any combination of them (or parts of them). Other specifications (see for example [WS-Security]) can provide such means.
This specification does not describe any components that require registration by IANA.
Added direct reference to Request-Response MEP in section 5 Attachment Feature properties
Solved 391 by incorporating proposal.
Solved 277 by updating section 5 Attachment Feature properties. Properties are now named using URIs instead of QNames. This also solves 386.
Solved 388 by incorporating proposal.
Further modified last sentence of first para of 1 Introduction.
In last paragraph of 3 Terminology changed 'also' to 'informally'.
Changed last sentence of Note in 6 Implementation to be reversed.
Changed att:SOAPMessage value definition in 5.2 Receiving a compound SOAP structure to be in sync with value definition in 5.1 Sending a compound SOAP structure.
Changed last paragraph of 9 Security Considerations by replacing 'attachment' by 'secondary part', and by some rewording.
Added some text in fifth paragraph of 1 Introduction to say that this spec can be used directly in SOAP bindings or indirectly through another specification.
Added 'part' 2 times in the last sentence of first paragraph of abstract.
Changed Last paragraph of 1 Introduction as per Noah's suggestion.
Changed 'may' to 'can' in 2 SOAP Feature Name.
Changed third paragraph of 4 Compound SOAP Structure Model as per Noah's suggestion (added 'semantic').
Changed fourth paragraph of 4 Compound SOAP Structure Model as per Noah's suggestion (added 'envelope').
Changed 6 Implementation as per Noah's suggestion.
Added text in abstract to say that attachment is an informal term for part.
Removed sentence "a priori with any MEP" from 5 Attachment Feature properties.
Added warning in 5 Attachment Feature properties about potential properties conflicts. Added a figure.
Removed note from 5.1 Sending a compound SOAP structure.
Removed note from 5.1 Sending a compound SOAP structure.
Changed NEED NOT to lowercase in 6 Implementation.
Added example mentioning MIME multipart in 6 Implementation.
Clarified last sentence of last paragraph in 9 Security Considerations to read as an example.