1EdTech General Web Services Attachments Profile Version 1.0 Final Specification

Copyright © 2005 1EdTech Consortium, Inc. All Rights Reserved.
The 1EdTech Logo is a registered trademark of 1EdTech/GLC
Document Name: 1EdTech General Web Services Attachments Profile
Revision: 19 December 2005

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

1EdTech 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 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright ) 2005 1EdTech Consortium. All Rights Reserved.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/license.html.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Executive Summary

The General Web Service Base Profile provides a basic structure for the definition of Web Services used to realize 1EdTech service-oriented specifications. It consists of a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications that promote interoperability. The General Web Services Base Profile addresses the most common problems experienced when implementing web service specifications. The General Web Services Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The General Web Services Base Profile promotes interoperability across web specifications implementations on different software and vendor platforms. The Base Profile focuses on a core set of web service specifications and the most common problems experienced implementing the identified web service specifications. It is not a goal of the General Web Services Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The General Web Services Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services.

The 1EdTech GWS Attachments Profile extends the 1EdTech GWS Base Profile to allow the exchange of non-XML information in the SOAP messages. The Attachments Profile defines the usage of the Message Transmission Optimization Mechanism (MTOM) to attach the non-XML content to the SOAP messages. MTOM uses the XML-binary Optimized Packaging (XOP) mechanism to improve the encoding efficiency possible with SOAP with Attachments.

Table of Contents

Executive Summary

1. Introduction
1.1 Scope and Context
1.2 Structure of this Document
1.3 Nomenclature
1.4 References

2. Attachments Framework
2.1 Message Transmission Optimization Mechanism (MTOM)
2.2 Attachment Processing Workflow

3. Attachments Profile Rules

4. WSDL Binding Implications

5. Relationship to the Other GWS Profiles

6. Extending the Attachments Profile
6.1 Proprietary Extensions
6.2 Further Work in V2.0

7. Conformance to the Attachments Profile

Appendix A - Glossary of Terms

About This Document
List of Contributors

Revision History

Index

1. Introduction

1.1 Scope and Context

The 1EdTech General Web Services (GWS) Base Profile (GWSBP) [GWS, 05a] provides a basic structure for the definition of Web Services. It consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The 1EdTech GWS Base Profile addresses the most common problems experienced implementing web service specifications. The 1EdTech GWS Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The 1EdTech GWS Attachments Profile extends the 1EdTech GWS Base Profile to allow the exchange of non-XML information in the SOAP messages. The Attachments Profile defines the usage of the Message Transmission Optimization Mechanism (MTOM) to attach the non-XML content to the SOAP messages. MTOM uses the XML-binary Optimized Packaging (XOP) mechanism to improve the encoding efficiency possible with SOAP with Attachments.

1.2 Structure of this Document

The structure of this document is:

1.3 Nomenclature

1.4 References

2. Attachments Framework

2.1 Message Transmission Optimization Mechanism (MTOM)

The 1EdTech GWS Attachments Framework is based upon the MTOM standard under development by W3C [MTOM, 05]. MTOM combines the composition capability of Base 64 encoding with the transport efficiency of SOAP with Attachments (SWA). Non-XML data is processed just as it is with SWA - the data is simply streamed as binary data in one of the MIME message parts. MTOM is composed of three distinct specifications:

1. SOAP Message Transmission Optimization Mechanism [MTOM, 05] - this describes an abstract feature for optimizing the transmission and/or wire format of a SOAP message by selectively encoding portions of the message, while still presenting an XML Infoset to the SOAP application. Use of the Abstract SOAP Transmission Optimization Feature is a hop-by-hop contract between a SOAP node and the next SOAP node in the SOAP message path, providing no mandatory convention for optimization of SOAP transmission through intermediaries;
2. XML-binary Optimized Packaging [XOP, 05] - this specifies the method for serializing XML Infosets with non-XML content into MIME packages. XOP provides an alternate serialization that is fully compatible with a MIME package, including an XML document as the root portion of the package. XOP streams the non-XML attachment as one of the MIME message parts. The MIME attachment is processed and temporarily treated as base-64 encoded text immediately prior to serialization of the message. For example, a WS-Security layer creating a digital signature would use the non-XML data to calculate the signature by streaming it through a base-64-encoding layer. The base-64-encoded data is temporary, used only for creating the signature (it is never actually transferred, stored or serialized anywhere). During deserialization the processing layers that access the attachment would do so through the base-64-encoding layer (again, this is a temporary representation that occurs just before serialization);
3. The Resource Representation SOAP Header Block specification [RRSHB, 05] - this defines a SOAP header block that can carry resource representations within SOAP messages. The Representation Header Block is designed to be used when the receiver has limited ability to retrieve the resource (due to access restrictions or unreasonable overhead processing due to the size of the resource to be retrieved). The RRSHB can also be used when multiple references to the same resource are required but duplication of the resource is undesirable. The example below illustrates a sample application of the RRSHB. The referenced Content Package is attached as a MIME part and the (simulated) base-64 encoded value was generated during Infoset processing (as mentioned above).

MTOM was selected in preference to SWA for two reasons:

1. SWA defines a way for binding attachments to a SOAP envelope using the multipart/related MIME type - this is the same attachment/encapsulation mechanism used for e-mail. MIME is inefficient because it uses text strings to delineate boundaries between parts. Consumers must scan the entire message to find the string value used to delineate a boundary;
2. MIME cannot be represented as an XML Infoset - this effectively breaks the Web Services model since attachments cannot be secured using WS-Security.

MTOM provides a compromise between the MIME model and the Web Services model, combining an efficient encoding mechanism (saving 25% over a traditional binary model) and an infoset representation (the overall package can be processed like a regular SOAP message). MTOM messages are valid SWA messages, lowering the effort of implementing MTOM for existing SWA implementations. MTOM attachments are streamed as binary data within a MIME message part, making it simple to interoperate with other SWA implementations.

2.2 Attachment Processing Workflow

The key terms used in the description of the work-flow are defined in Table 2.1.

Note that INITIATOR and RESPONDENT as intended throughout the rest of the document, are at a different level of abstraction compared to SOURCE and DESTINATION, the former belong to the application layer, while the latter belong to the messaging infrastructure layer and provide services to INITIATORS and RESPONDENTS (see Figure 2.1).

The following is a step-by-step breakdown of a typical workflow for exchanging 1EdTech MESSAGES and ATTACHMENTS. This workflow represents a common sequence of tasks. As a result, this workflow is intended to outline the pertinent tasks and is not prescriptive as to the sequence of fine-grained steps:

1. INITIATOR constructs 1EdTech MESSAGE according to the relevant 1EdTech specification and the WSDL binding guidelines [GWS, 05b];
2. INITIATOR identifies ATTACHMENT (or ATTACHMENTs) to be sent with the 1EdTech MESSAGE;
3. The Web Services Messaging Adapter within the INITIATOR:-
   • Encapsulates the 1EdTech MESSAGE in the body of the SOAP message
   • Attaches ATTACHMENT (or ATTACHMENTs) using MTOM
   • Passes the 1EdTech MESSAGE and ATTACHMENT (or ATTACHMENTs) to SOURCE;
4. SOURCE transmits the 1EdTech MESSAGE through the transport;
5. 1EdTech MESSAGE is transferred to the DESTINATION;
6. DESTINATION gets the 1EdTech MESSAGE from the transport;
7. The Web Services Messaging Adapter within the RESPONDENT:-
   • Decodes and detaches all ATTACHMENTs attached to the message
   • Passes a receipt/response message to the INITIATOR
   • RESPONDENT extracts, validates and processes the 1EdTech MESSAGE and ATTACHMENT (or ATTACHMENTs).

3. Attachments Profile Rules

Table 3.1 summarizes the set of rules used for the Attachments Profile. Within Table 3.1 the following conventions are used:

• 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 RFC2119;
• Normative statements in the Profile are presented in the following manner: RATPnnnnStatement text here, where "nnnn" is replaced by the statement number. Each statement contains exactly one requirement level keyword, e.g., "MUST", and one conformance target keyword, e.g., "MESSAGE".

<ns1:data xmlmime:contentType="image/jpeg">
   ...
</ns1>

<ns1:data xmlmime:contentType="image/jpeg">
   <xop:Include href=cid:thismessage:/resource1.jpg/>
</ns1>

Content-ID: <thismessage:/resource1.jpeg>

Content-Type: image/jpeg

Content-Transfer-Encoding: binary

4. WSDL Binding Implications

The usage of MTOM requires the following information to supplied as part of the specification process:

• Each parameter (input or output) that is used to reference an attached data object must be identified. More than one attachment can be sent or received during each message exchange;
• The MIME-type of the attachment must be supplied;
• The URL for where the document that is to be attached can be located;
• The value for the <Include href="..."> element for the XOP processor is derived as a combination of the parameter name and the MIME-type. This value is a URI for the material in the MIME parts and not an external URL.

From the perspective of the WSDL 1.1 the attachment information is presented in the XSD definition part of the file. The transformation files in the 1EdTech Auto-generation Toolkit (I-BAT) [I-BAT, 05] use the information supplied in the UML description as described in Table 4.1. In Table 4.1 each attribute has an example value and for each set of values there follows the corresponding WSDL file.

<wsdl11:definitions name = "ExampleGroupSyncServices" 
   targetNamespace = "http://www.example/services/wsdl/sync/wsdlfilev1p0" 
   xmlns:tns = "http://ww.example/services/wsdl/sync/wsdlfilev1p0"
   xmlns:soap11 ="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:wsdl11 ="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xs = "http://www.w3.org/2001/XMLSchema" 
   xmlns:xsi = "http://www.w3.org/2000/10/XMLSchema-instance">

<wsdl11:service name = "EgServiceNameSyncService">
   <wsdl11:port name = "CoreOperationsNameSyncSoapPort" binding = "...">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl11:port>
</wsdl11:service>

<wsdl11:binding name="CoreOperationsNameSyncSoapBinding" 
          type="tns: CoreOperationsNameSyncPortType">
   <soap11:binding transport="http://schema.xmlsoap.org/soap/http" style="document"/>
   <wsdl11:operation name="createObject">
      <soap11:operation soapAction="http://www.example/soap/service/createObject" 
         style="document"/>
      ...
   </wsdl11:operation>
</wsdl11:binding>
<wsdl11:service name = "EgServiceNameSyncService">
   <wsdl11:port name = "CoreOperationsNameSyncSoapPort" 
            binding = "tns:CoreOperationsNameSyncSoapBinding">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl11:port>
</wsdl11:service>

<wsdl11:types>
   <xs:schema xmlns="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://www.example/services/wsdl/sync/wsdlfilev1p0"
      xmlns:xsd=http://www.w3.org/2001/XMLSchema
      xmlns:xsi=http://www.w3.org/2000/10/XMLSchema-instance
      xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime"
      version="1EdTech 1.0"
      elementFormDefault="qualified"
      attributeFormDefault="unqualified">

      <xs:import namespace='http://www.w3.org/2004/06/xmlmime' />

      <xs:element name='myData' >
         <xs:complexType>
              <xs:simpleContent>
               <xs:extension base='xs:base64Binary' >
                    <xs:attribute ref="xmlmime:contentType" />
               </xs:extension>
              </xs:simpleContent>
         </xs:complexType>
        </xs:element>

   </xs:schema>
</wsdl11:types>

5. Relationship to the Other GWS Profiles

The relationship of the Attachments Profile to the other 1EdTech GWS profiles is shown in Figure 5.1.

The Attachments Profile assumes that the Base Profile is already being used [GWS, 05a]. This is the only dependency with other 1EdTech GWS profiles.

When the Security Profile is being used there are implications for how some of the attachment related information is encoded. These implications are defined in the profiles rules in Section 3.

6. Extending the Attachments Profile

6.1 Proprietary Extensions

Extensions of the Attachments Profile are NOT recommended. This is because the use of MTOM with WSDL v1.1 is unstable in terms of tool support and completion of the W3C standard. The MTOM is a candidate recommendation and not a full standard.

6.2 Further Work in V2.0

In 1EdTech GWS v2.0 limited further work will be undertaken to ensure the compatibility of supporting MTOM with WSDL v1.1. The rest of the work will focus on the usage of MTOM with SOAP v1.2 and WSDL v2.0.

7. Conformance to the Attachments Profile

Any claim of conformance for an implementation against the Attachments Profile must show that the implementation complies with the set of profile rules listed in Section 3.

Apart from the WS-I Conformance Claims mechanism, the W3C is investigating the usage of WS-Policy. Therefore, no definitive recommendation is made on the usage of the WS-I approach. More information on the WS-I Conformance Claim mechanism is given in the 1EdTech GWS WSDL Binding Guidelines document [GWS, 05b]. However, if some form of conformance statement is required then the WS-I approach may be used but no firm commitment is made to supporting this technique in later releases of the 1EdTech GWS specification.

Appendix A - Glossary of Terms

Throughout the General Web Services documents a variety of key terms, concepts and descriptions have been introduced. These terms, concepts and descriptions and defined below but where appropriate the normative definition from the IAF Glossary is referenced [AbsGloss, 03].

About This Document

List of Contributors

The following individuals contributed to the development of this document:

Revision History

Index

A
Abstract Framework 1, 2, 3

B
Base Profile 1, 2, 3, 4

C
Conformance 1, 2
Context 1

G
General Web Services Base Profile 1

I
1EdTech Auto-generation Binding Tool 1, 2
1EdTech General Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Attachments Profile 1, 2, 3, 4, 5
Base Profile 1, 2, 3, 4, 5
 

M
Message Transmission Optimization Mechanism 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Messaging
Synchronous 1
MIME 1, 2, 3, 4, 5, 6
 

P
Protocols
HTTP 1
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
TCP 1
 

R
Remote Procedure Call 1
Resource Representation SOAP Header Block 1, 2, 3, 4, 5

S
Security 1, 2
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
SOAP message attachments
MTOM 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
SWA 1, 2, 3, 4
SOAP Versions
1.1 1
SOAP with Attachments 1, 2, 3, 4, 5, 6
Synchronous 1
 

T
TCP 1
Transmission Control Protocol 1

U
Unified Modelling Language 1, 2
UML 1, 2
 

W
W3C 1, 2, 3, 4, 5, 6
Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
WSDL 1, 2, 3, 4, 5, 6, 7
WS-Security 1, 2
Web Services Interoperability Organization 1, 2
WSDL 1, 2, 3, 4, 5, 6, 7
WSDL Versions
1.1 1
WS-Security 1, 2
 

X
XML 1, 2, 3, 4, 5
XML Schema 1
XML Schema Definition 1
XML-binary Optimized Packaging 1, 2, 3, 4, 5, 6, 7, 8
XSD 1, 2
XSLT 1