A Preview of WS-I Basic Profile 1.1
by Anish Karmarkar
|
Pages: 1, 2
Here is an equivalent example, which results in the same input and output wire messages, that uses document/literal as the style instead of rpc/literal (please note that the namespace prefix types is bound to the namespace URI http://example.com/some-namespace):
<wsdl:types>
<schema targetNamespace="http://example.com/some-namespace"
xmlns="http://www.w3.org/2000/10/XMLSchema"
elementFormDefault="unqualified">
<element name="my-operation">
<complexType>
<sequence>
<element name="photo-reference" type="xsd:anyURI"/>
</sequence>
</complexType>
</element>
<element name="my-operationResponse">
<complexType>
<sequence>
<element name="result" type="xsd:string"/>
<sequence>
</complexType>
</element>
</schema>
</wsdl:types>
<wsdl:message name="msg-in-doc">
<wsdl:part name="photo-reference-wrapper"
element="types:my-operation"/>
<wsdl:part name="photo-attachment"
type="xsd:base64Binary"/>
</wsdl:message>
<wsdl:message name="msg-out-doc">
<wsdl:part name="result-wrapper"
element="types:my-operationResponse"/>
</wsdl:message>
<wsdl:portType name="my-portType-doc">
<wsdl:operation name="my-operation-doc">
<wsdl:input message="tns:msg-in-doc"/>
<wsdl:output message="tns:msg-out-doc"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="my-binding-doc" type="tns:my-portType-doc">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="my-operation-doc">
<soap:operation soapAction="http://example.com/soapaction"/>
<wsdl:input>
<mime:multipartRelated>
<mime:part>
<soap:body parts="photo-reference-wrapper"
use="literal"/>
</mime:part>
<mime:part>
<mime:content part="photo-attachment"
type="application/octetstream"/>
</mime:part>
</mime:multipartRelated>
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>Referencing Attachments
These examples allow a web service to describe attachments, but the description says nothing about how attachments are referenced from the SOAP Envelope, which is a very common use case. Consider the case where the binary data is just too large to be inlined in the SOAP Envelope. SwA allows one to ship the data as an attachment, but this data will have to be referred to from the SOAP Envelope. Such a design would allow the higher application layers to not care whether the data is inlined or sent as an attachment. (For example in Java one could use the javax.activation.DataHandler to do this).
Basic Profile 1.1 solves the problem of describing the referrer-reference relationship by defining a type swaRef, in the (temporary) namespace http://ws-i.org/profiles/basic/1.1/xsd, which is a restriction of xsd:anyURI:
<xsd:schema targetNamespace="http://ws-i.org/profiles/basic/1.1/xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xsd:simpleType name="swaRef">
<xsd:restriction base="xs:anyURI" />
</xsd:simpleType>
</xsd:schema>Basic Profile 1.1 requires that a value of this type must resolve within the MIME package; that is, the URI that is the value of this type in the instance document must dereference to a MIME part within the same MIME package.
This makes the relationship between the referrer and the reference statically available to tools, which can then generate code artifacts that allow rich semantics (for example, generating stream oriented interfaces to access the attached data). Applications are allowed to use other mechanisms to express such a referrer-reference relationship. swaRef provides a uniform mechanism to identify references that point to attachments and therefore facilitate interoperability.
In the rpc/literal example above, the type of part photo-reference of the input message can now be changed to type swaRef. Similarly, for the document/literal example above, the type of the element photo-reference in the wsdl:types section can now be changed to type swaRef. The fact that the element photo-reference in the SOAP Envelope points to a MIME part within the same MIME package is now statically available in the WSDL description. The rpc/literal example above can be modified to use this new type as follows (please note that the namespace prefix bp11 is bound to the namespace URI http://ws-i.org/profiles/basic/1.1/xsd):
<wsdl:message name="msg-in">
<wsdl:part name="photo-reference" type="bp11:swaRef"/>
<wsdl:part name="photo-attachment" type="xsd:base64Binary"/>
</wsdl:message>
<wsdl:message name="msg-out">
<wsdl:part name="result" type="xsd:string"/>
</wsdl:message>
<wsdl:portType name="my-portType">
<wsdl:operation name="my-operation">
<wsdl:input message="tns:msg-in"/>
<wsdl:output message="tns:msg-out"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="my-binding" type="tns:my-portType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="my-operation">
<soap:operation soapAction="http://example.com/soapaction"/>
<wsdl:input>
<mime:multipartRelated>
<mime:part>
<soap:body parts="photo-reference"
use="literal"
namespace="http://example.com/some-namespace"/>
</mime:part>
<mime:part>
<mime:content part="photo-attachment"
type="application/octetstream"/>
</mime:part>
</mime:multipartRelated>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"
namespace="http://example.com/some-namespace"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>A WSDL processor processing this WSDL fragment now knows that the URI within the SOAP Body is a reference to a MIME part in the same MIME package and can generate appropriate APIs to access the binary data that is sent as a separate MIME part. In the previous case, when swaRef was not used, the WSDL processor had no way of knowing whether the URI value in the SOAP message will resolve locally or be resolvable at all.
Summary
Interoperable attachments is one of the features that is frequently demanded by developers and users of web services. The Basic Profile Working Group addresses this need by including SwA in Basic Profile 1.1, resolving ambiguities, and by filling in the gaps of existing specifications. Furthermore, Basic Profile 1.1 also enables language binding tools to generate appropriate APIs to take full advantage of attachments.
Acknowledgments
The author would like to thank Eric Rajkovic and Umit Yalcinalp for reviewing the initial version of this document and providing much appreciated feedback.
References
WS-I Final Specification "BasicProfile Version 1.0a", Keith Ballinger, David Ehnebuske, Martin Gudgin, Mark Nottingham, Prasad Yendluri, 8 August 2003.
WS-I "Working Group Charter: Web Services Basic Profile", Tom Glover, Christopher Ferris, Christopher Kurt, Keith Ballinger, 21 January 2003.
IETF "Content-ID and Message-ID Uniform Resource Locators", E. Levinson, March 1997.
Sun "JavaBeans Activation Framework Specification Version 1.0a", Bart Calder, Bill Shannon, 27 May 1999.
IETF "MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)", J. Palme, A. Hopmann, N. Shelness, March 1999.
W3C Working Draft "SOAP Message Transmission Optimization Mechanism", Noah Mendelsohn, Mark Nottingham, Hervé Ruellan, 21 July 2003.
"Proposed Infoset Addendum to SOAP Messages with Attachments", Adam Bosworth, Don Box, Martin Gudgin, Mark Jones, Franz-Josef Fritz, Amy Lewis, Jean-Jacques Moreau, Mark Nottingham, David Orchard, Hervé Ruellan, Jeffrey Schlimmer, Volker Wiechers, TBD.
"XML, SOAP and Binary Data", Adam Bosworth, Don Box, Martin Gudgin, Mark Nottingham, David Orchard, Jeffrey Schlimmer, 26 February 2003.
W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Frystyk Nielsen, Satish Thatte, Dave Winer, 8 May 2000.
W3C Recommendation "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 24 June 2003.
W3C Recommendation "SOAP Version 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 24 June 2003.
W3C Working Draft "SOAP 1.2 Attachment Feature", Henrik Frystyk Nielsen, Hervé Ruellan, 24 September 2002.
W3C Note "SOAP Messages with Attachments", John J. Bartin, Satish Thatte, Henrik Frystyk Nielsen, 11 December 2000.
OASIS UDDI Committee Specification "UDDI Version 2.04 API Specification", Tom Bellwood (Editor), 19 July 2002.
OASIS UDDI Committee Specification "UDDI Version 2.03 Data Structure Reference", Claus von Riegen (Editor), 19 July 2002.
Web Services Interoperability Organization.
W3C Note "Web Services Description Language (WSDL) 1.1", Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, 15 March 2001.
W3C XML Protocol Working Group.
Share your questions or comments about the WS-I Basic Profile in our forum.
(* You must be a member of XML.com to use this feature.)
Comment on this Article
