IMS General Web Services Attachments Profile Version 1.0 Final Specification

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

Executive Summary

The General Web Service Base Profile provides a basic structure for the definition of Web Services used to realize IMS 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 IMS GWS Attachments Profile extends the IMS 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

1. Introduction

1.1 Scope and Context

The IMS 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 IMS GWS Base Profile addresses the most common problems experienced implementing web service specifications. The IMS GWS Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The IMS GWS Attachments Profile extends the IMS 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 IMS 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 IMS 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 IMS MESSAGE according to the relevant IMS specification and the WSDL binding guidelines [GWS, 05b];
2. INITIATOR identifies ATTACHMENT (or ATTACHMENTs) to be sent with the IMS MESSAGE;
3. The Web Services Messaging Adapter within the INITIATOR:-
   • Encapsulates the IMS MESSAGE in the body of the SOAP message
   • Attaches ATTACHMENT (or ATTACHMENTs) using MTOM
   • Passes the IMS MESSAGE and ATTACHMENT (or ATTACHMENTs) to SOURCE;
4. SOURCE transmits the IMS MESSAGE through the transport;
5. IMS MESSAGE is transferred to the DESTINATION;
6. DESTINATION gets the IMS 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 IMS 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 IMS 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="IMS 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 IMS 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 IMS 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 IMS 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 IMS 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 IMS 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
IMS Auto-generation Binding Tool 1, 2
IMS 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