Inclusion Mechanism

Copyright ©  W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.

Status of this Document

This document is an editors' copy that has no official standing.

This document is a first try at describing an abstract feature for helping the handling of attachments included in a SOAP message and a concrete implementation of this feature as an HTTP binding.

Short Table of Contents

1. Introduction
2. Abstract Inclusion Feature
3. HTTP Inclusion Feature

Table of Contents

1. Introduction
2. Abstract Inclusion Feature
    2.1 Introduction
    2.2 Abstract Inclusion Feature Name
    2.3 Abstract Inclusion Feature Properties
    2.4 Abstract Inclusion Feature Processing
        2.4.1 Sending a message
        2.4.2 Receiving a message
        2.4.3 Transmitting a message
3. HTTP Inclusion Feature
    3.1 Introeiisduction
    3.2 HTTP Inclusion Feature Name
    3.3 Implementation
        3.3.1 Sending a SOAP message
        3.3.2 Receiving a SOAP message

Appendix

1. Introduction

The first part of this document (2. Abstract Inclusion Feature) describes an abstract feature for optimizing the transmission and/or wire format of a SOAP message by selectively re-encoding portions of the message, while still presenting and XML Infoset to the SOAP application.

This abstract feature is intended to be implemented by SOAP bindings. In a second part (3. HTTP Inclusion Feature), this document describes such an implementation for an HTTP binding.

Editorial note: HR 
What is the name of this "thing"? Inclusion Mechanism, Attachment mechanism, transmission optimisation, serialization mechanism...

2. Abstract Inclusion Feature

2.1 Introduction

The Abstract Inclusion Feature enables SOAP applications to optimize the transmission and/or wire format of a SOAP message by selectively re-encoding portions of the message, whilst still presenting an XML Infoset to the SOAP application.

2.2 Abstract Inclusion Feature Name

This Abstract Inclusion Feature is identified by the URI:

  • "http://www.w3.org/2003/06/soap/features/abstract-inclusion".

2.3 Abstract Inclusion Feature Properties

The Abstract Inclusion Feature defines a set of properties described in Table 1.

Table 1: Property definition for the Abstract Inclusion Feature
Property Name Property Description
aif:InclusionList A List containing zero or more (pointers to) element information items within the SOAP envelope candidate for being transmitted in an optimized way. The manner in which such identification is represented in the node is at the discretion of the implementation.

Note: Among the possible choices for identifying element information items in the "aif:InclusionList" are XPaths relative to the Envelope element, or pointers to the internal implementation of the elements in question. Indeed the list may be implicit in the content of the envelope itself. For example, any information item with contents that happen to be the canonical form of some base64 binary value can be implicitly included in the list if desired.

Editorial note: HR 
Does "enabling" an Abstract Feature makes sense for a SOAP node? If this is not the case, another property should be created for reflecting the fact that the Abstract Inclusion Feature is enabled or not.
Editorial note: HR per Noah's remark 
Do we allow the optimization of only base64 binary content or do we allow to generalize the "aif:InclusionList" as a list of (type, elementID) pairs? This would allow for binary transmission of integers, floats, and so on.

2.4 Abstract Inclusion Feature Processing

2.4.1 Sending a message

To send a SOAP message using the Abstract Inclusion Feature, an application MUST enable the Abstract Inclusion Feature. In addition it SHOULD define the value of the "aif:InclusionList" property.

When sending a SOAP message with the Abstract Inclusion Feature enabled, a SOAP node using a binding implementing the Abstract Inclusion Feature MUST apply the following rules:

  • The SOAP node binding SHOULD optimize the transmission of all the SOAP message eii listed in the value of the "aif:InclusionList" property.

  • The SOAP node binding MAY optimize the transmission of other SOAP message eii not listed in the value of the "aif:InclusionList" property. In particular, if the "aif:InclusionList" property is not defined or if it has an empty value, the SOAP node binding MAY optimize the transmission of any SOAP message eii.

Editorial note: HR 
Do we allow the optimization of the Envelope, Header, Body eii, or of a full Header Block?
Editorial note: HR 
If the binding used does not implement the Abstract Inclusion Feature there are several options which can be followed: fault; send the message ignoring the request for using the Abstract Inclusion Feature; send the message including the request for using the Abstract Inclusion Feature (allows an intermediary implementing it to use its implementation).

2.4.2 Receiving a message

When receiving a SOAP message using an implementation of the Abstract Inclusion Feature, a SOAP node SHOULD fault if it does not support the implementation used or the Abstract Inclusion Feature.

When receiving a SOAP message using an implementation of the Abstract Inclusion Feature, a SOAP node binding MUST apply the following rules:

  • The SOAP node binding MUST reconstruct the original SOAP message infoset.

  • The SOAP node binding MUST enable the Abstract Inclusion Feature.

  • The SOAP node binding SHOULD/MAY set the value of the "aif:InclusionList" property to reflec the SOAP message parts whose transmission was optimized in the incomming message.

2.4.3 Transmitting a message

A SOAP intermediary transmitting a SOAP message MUST follow the rules related to the usage of an implementation of the Abstract Inclusion Feature when receiving the message (see 2.4.2 Receiving a message).

A SOAP intermediary transmitting a SOAP message MUST follow the rules related to the usage of an implementation of the Abstract Inclusion Feature when sending a message which was received with the Abstract Inclusion Feature enabled (see 2.4.1 Sending a message).

Note: the Abstract Inclusion Feature may have been enabled in the incomming message through two means:

  • Some parts of the incomming message were transmitted in an optimized way.

  • The incomming message was transmitted in an non optimized way, but contained hints that it or part of it should be transmitted in an optimized way.

In addition a SOAP intermediary transmitting a SOAP message MUST apply the following rules:

  • The SOAP intermediary MAY request that part of the stuff it adds to the SOAP message it transmits be transmitted in an optimized way.

  • The SOAP intermediary binding used for sending the SOAP message MAY optimize the transmission of parts of the SOAP message, present in the received SOAP message, which were not listed for being transmitted in an optimized way.

  • The SOAP intermediary MAY enable the usage of the Abstract Inclusion Feature in the transmitted SOAP message even if it was not enabled in the received SOAP message.

Editorial note: HR 
The second point is a consequence of the rules for sending a SOAP message.
Editorial note: HR 
Do we want to allow the third point?

3. HTTP Inclusion Feature

3.1 Introeiisduction

The HTTP Inclusion Feature is a binding level feature, implementing the Abstract Inclusion Feature in an HTTP binding.

3.2 HTTP Inclusion Feature Name

This HTTP Inclusion Feature is identified by the URI:

  • "http://www.w3.org/2003/06/soap/features/http-inclusion".

3.3 Implementation

3.3.1 Sending a SOAP message

When sending a SOAP message for which the Abstract Inclusion Feature is enabled, the HTTP Inclusion Feature optimizes the transmission of the message by transmitting in a compact form parts of the SOAP message. The SOAP message is serialized into a MIME multipart (ref) packaging, one body part, the root object, being an XML representation of the SOAP envelope, while other body parts contains the parts of the SOAP message transmitted in a compact form.

The HTTP Inclusion Feature affects the serialization of the SOAP message infoset into the HTTP body. The following rules MUST be applied for serializing a SOAP message infoset when the HTTP Inclusion Feature is used:

  1. A MIME multipart packaging MUST be created and put into the HTTP body.

  2. The HTTP Inclusion Feature creates a list of the eiis of the SOAP message whose transmission is to be optimized. This list SHOULD contain all the eiis of the SOAP message pointed to in the "aif:InclusionList" property. This list MAY contain other eiis of the SOAP message.

    3. Editorial note: HR 
    Do we handle overlapping eiis?

  3. The HTTP Inclusion Feature MUST serialize each eii in the list in a body part of the MIME multipart packaging.

    4. Editorial note: HR 
    How do we set the Content-type?

  4. The SOAP message infoset is modified before being serialized. Each eii in the list is replaced by an "xbinc:Include" eii refering to the body part of the MIME multipart packaging containing its serialization.

  5. The resulting SOAP message infoset is serialized using XML 1.0 in the root object of the MIME multipart packaging.

3.3.2 Receiving a SOAP message

An HTTP Binding receiving a message using the HTTP Inclusion Feature does several things before passing the message to the SOAP stack:

  • It extracts the SOAP message from the multipart MIME packaging.

  • It replaces each xbinc:Include eii with the data it refers to in the multipart MIME packaging after encoding this data using base64.

Editorial note: HR 
No more DoInclude header. The functionnality should be transfered to the SOAP Extensible HTTP Binding.
Editorial note: HR 
This text should be rewritten.
Editorial note: HR 
This text should be enhanced with text from the paswa document.