Representation header final proposal

Hi, in fulfillment of my action item, here's the final proposal for a
header satisfying UC2 [1], as discussed at the last telcon.

I believe a header specification for SOAP should be in infoset terms -
it doesn't need to be in XQuery data model terms because it's not
connected to MTOM/XOP, it only benefits from being combined with the
two.

It's not as long as it looks, btw. 8-)

                   Jacek Kopecky

                   Systinet Corporation
                   http://www.systinet.com/


[1] http://www.w3.org/TR/2003/WD-soap12-os-ucr-20031112/#use-cases

-----------------------------------------------------------------------------

Bundling resource representations in SOAP messages
==================================================

The Representation EII (with the namespace name of @@@) is designed to
allow applications to "attach" a representation of a Web resource to a
SOAP message for cases where the receiver has limited ability to get the
representation itself, for example because of access restrictions or
because the overhead would be unacceptable.

The basic Representation header structure is indicated by the following
pseudo-syntax:

<rep:Representation resource="uri" ... xmlns:rep="@@@">
  <rep:Data ...>base64-encoded representation data</rep:Data>
  ...
</rep:Representation>

The ellipses (three dots) mean extensibility by AIIs or EIIs from a
namespace different than @@@.

The meaning of the header, when present in a SOAP message, is to make
available the contained representation of the resource identified by the
value of the 'resource' AII to the processing SOAP node, which MAY use
this representation when dereferencing the URI of the resource instead
of making a network request to the given resource.

An example SOAP Envelope using the Representation header:


<soap:Envelope xmlns:soap='http://www.w3.org/2002/12/soap-envelope' 
               xmlns:rep='@@@' 
               xmlns:xmime='@@@2' >
  <soap:Header>
    <rep:Representation resource='http://example.org/me.png'>
      <rep:Data xmime:media-type='image/png' >
        /aWKKapGGyQ=
      </rep:Data>
    </rep:Representation>
  </soap:Header>
  <soap:Body>
    <x:MyData xmlns:x='http://example.org/mystuff' >
      <x:name>John Q. Public</x:name>
      <x:img src='http://example.org/me.png' />
    </x:MyData>
  </soap:Body>
</soap:Envelope>


Specifying media type of the representation
-------------------------------------------

When the receiving SOAP node is deciding whether the given
representation is suitable for it or not, it may require to know the
media type of it. To indicate the media type of the representation the
sending SOAP node MAY use the attribute xmime:media-type (as specified
in ...) on the ns:Data EII. This is demonstrated by the example above.

Extensibility of Representation header
--------------------------------------

As seen above, the Representation header extensibility can be used to
indicate the media type of the representation. Other uses may include:

      * soap:mustUnderstand AII on the Representation EII to make sure
        that the receiver knows the representation is available to it
      * soap:role AII on the Representation EII to indicate the SOAP
        node for which the representation is intended
      * an EII child of the Representation EII that contains information
        about request and response HTTP headers so that the
        representation can be used by a full-fledged HTTP caching
        implementation at the receiving SOAP node (as specified in ...?)
        For example:

        <rep:Representation resource='http://example.org/me.png'
                            xmlns:ca="http://example.com/http/cache">
          <ca:caching-context>
            <ca:request>
              <ca:header name="Accept">
                image/svg+xml, image/png
              </ca:header>
            </ca:request>
            <ca:response>
              <ca:header name="Vary">Accept</ca:header>
              <ca:header name="Content-Type">image/png</ca:header>
              ...
            </ca:response>
          </ca:caching-context>
          <rep:Data xmime:media-type='image/png' >
            /aWKKapGGyQ=
          </rep:Data>
        </rep:Representation>
        

-----------------------------------------------------------------------------

Received on Friday, 16 January 2004 08:02:23 UTC