Please refer to the errata for this document, which may include some normative corrections.
This document is also available in these non-normative formats: PDF, PostScript, XML, and plain text.
See also translations.
Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document is a companion to the WSDL 2.0 specification (Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language [WSDL 2.0 Core], Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts [WSDL 2.0 Adjuncts]). It is intended for readers who wish to have an easier, less technical introduction to the main features of the language.
This primer is only intended to be a starting point toward use of WSDL 2.0, and hence does not describe every feature of the language. Users are expected to consult the WSDL 2.0 specification if they wish to make use of more sophisticated features or techniques.
Finally, this primer is non-normative. Any specific questions of what WSDL 2.0 requires or forbids should be referred to the WSDL 2.0 specification.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the W3C Recommendation of Web Services Description Language (WSDL) Version 2.0 Part 0: Primer for review by W3C Members and other interested parties. It has been produced by the Web Services Description Working Group, which is part of the W3C Web Services Activity.
Please send comments about this document to the public public-ws-desc-comments@w3.org mailing list (public archive).
The Working Group released a test suite along with an implementation report. A diff-marked version against the previous version of this document is available.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document is governed by the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1. Introduction
1.1 Prerequisites
1.2 Structure of
this Primer
1.3 Use of URIs and
IRIs
1.4 Notational
Conventions
2. WSDL 2.0 Basics
2.1 Getting
Started: The GreatH Hotel Example
2.1.1 Example Scenario: The GreatH Hotel
Reservation Service
2.1.2 Defining a WSDL 2.0 Target Namespace
2.1.2.1
Explanation of
Example
2.1.3 Defining Message Types
2.1.3.1
Explanation of
Example
2.1.4 Defining an Interface
2.1.4.1
Explanation of
Example
2.1.5 Defining a Binding
2.1.5.1
Explanation of
Example
2.1.6 Defining a Service
2.1.6.1
Explanation of
Example
2.1.7 Documenting the Service
2.1.7.1
Explanation of
Example
2.2 WSDL
2.0 Infoset, Schema and Component Model
2.2.1 WSDL 2.0 Infoset
2.2.2 WSDL 2.0 Schema
2.2.2.1
WSDL 2.0 Element Ordering
2.2.3 WSDL 2.0 Component Model
2.2.3.1
WSDL 2.0 Import and Include
2.3 More on Message
Types
2.3.1 Inlining XML Schema
2.3.2 Importing XML Schema
2.3.3 Summary of Import and Include
Mechanisms
2.4 More on
Interfaces
2.4.1 Interface Syntax
2.4.2 Interface Inheritance
2.4.3 Interface Faults
2.4.4 Interface Operations
2.4.4.1
Operation Attributes
2.4.4.2
Operation Message References
2.4.4.2.1
The messageLabel Attribute
2.4.4.2.2
The element Attribute
2.4.4.2.3
Multiple infault or outfault Elements
2.4.4.3
Understanding Message Exchange
Patterns (MEPs)
2.5 More on
Bindings
2.5.1 Syntax Summary for Bindings
2.5.2 Reusable Bindings
2.5.3 Binding Faults
2.5.4 Binding Operations
2.5.5 The SOAP Binding Extension
2.5.5.1
Explanation of
Example
2.5.6 The HTTP Binding Extension
2.5.6.1
Explanation of Example
2.5.7 HTTP GET Versus POST: Which to Use?
3. Advanced Topics I: Importing
Mechanisms
3.1 Importing WSDL
3.2 Importing Schemas
3.2.1 Schemas in Imported Documents
3.2.2 Multiple Inline Schemas in One Document
3.2.3 The schemaLocation Attribute
3.2.3.1
Using the id Attribute to Identify Inline
Schemas
4. Advanced Topics II: Extensibility
and Predefined Extensions
4.1 Extensibility
4.1.1 Optional Versus Required
Extensions
4.2 Defining New
MEPs
4.2.1 Confirmed Challenge
4.3 RPC Style
5. Advanced Topics III:
Miscellaneous
5.1 Enabling Easy Message Dispatch
5.2 Web Service
Versioning
5.2.1 Compatible Evolution
5.2.2 Big Bang
5.2.3 Evolving a Service
5.2.4 Combined Approaches
5.2.5 Examples of Versioning and Extending a
Service
5.2.5.1
Additional Optional Elements Added in
Content
5.2.5.2
Additional Optional Elements Added to a
Header
5.2.5.3
Additional Mandatory Elements in Content
5.2.5.4
Additional Optional Operation Added to
Interface
5.2.5.5
Additional Mandatory Operation Added to
Interface
5.2.5.6
Indicating Incompatibility by Changing the
Endpoint URI
5.2.5.7
Indicating Incompatibility by Changing the
SOAP Action
5.2.5.8
Indicating Incompatibility by Changing the
Element Content
5.3 Describing Web Service Messages That
Refer to Other Web Services
5.3.1 The Reservation Details Web Service
5.3.2 The Reservation List Web Service
5.3.3 Reservation Details Web Service Using
HTTP Transfer
5.3.4 Reservation List Web Service Using HTTP
GET
5.4 Multiple Interfaces
for the Same Service
5.5 Mapping to
RDF and Semantic Web
5.5.1 RDF Representation of WSDL 2.0
5.6 Notes on
URIs
5.6.1 XML Namespaces and Schema
Locations
5.6.2 Relative URIs
5.6.3 Generating Temporary URIs
6. References
6.1 Normative References
6.2 Informative References
A. Acknowledgements
(Non-Normative)
This primer assumes that the reader has the following prerequisite knowledge:
familiarity with XML (Extensible Markup Language (XML) 1.0 [XML 1.0], XML Information Set [XML Information Set]) and XML Namespaces (Namespaces in XML [XML Namespaces]);
some familiarity with XML Schema (XML Schema Part 1: Structures [XML Schema Structures] XML Schema Part 2: Datatypes [XML Schema Datatypes]);
familiarity with basic Web services concepts such as Web service, client, and the purpose and function of a Web service description. (For an explanation of basic Web services concepts, see Web Services Architecture [WS Architecture] Section 1.4 and Web Services Glossary [WS Glossary] glossary. However, note the Web Services Architecture document uses the slightly more precise terms "requester agent" and "provider agent" instead of the terms "client" and "Web service" used in this primer.)
Section 2 starts with a hypothetical use case involving a hotel reservation service. It proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:
The types
element describes the kinds of messages
that the service will send and receive.
The interface
element describes what
abstract functionality the Web service provides.
The binding
element describes how to
access the service.
The service
element describes where to
access the service.
After presenting the example, it moves on to introduce the WSDL 2.0 infoset, schema, and component model. Then it provides more detailed coverage on defining message types, interfaces, bindings, and services.
Section 3 explains the WSDL 2.0 importing mechanisms in great details.
Section 4 talks about WSDL 2.0 extensibility and various predefined extensions.
Section 5 covers various topics that may fall outside the scope of WSDL 2.0, but shall provide useful background and best practice guidances that may be useful when authoring a WSDL 2.0 document or implementing the WSDL 2.0 specification.
The core specification of WSDL 2.0 supports Internationalized Resource Identifiers or IRIs [IETF RFC 3987]. IRIs are a superset of URIs with added support for internationalization. The URI syntax [IETF RFC 3986] only allows the use of a small set of characters, including upper and lower case letters of the English alphabet, European numerals and a few symbols. IRIs allow the use of characters from a wider range of language scripts.
For simplicity, examples throughout this primer only use URIs. If you are interested in learning more about the use of IRIs, you might care to read the paper prepared by the W3C Internationalization Activity.
This document uses several XML namespaces, some of which are defined by standards, and some are application-specific. Namespace names of the general form "http://greath.example.com/..." represent application or context-dependent URIs [IETF RFC 3986].Note also that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set]).
Following the convention for XML syntax summary in [WSDL 2.0 Core], this primer uses an informal syntax to describe the XML grammar of a WSDL 2.0 document:
The syntax appears as an XML instance, but the values indicate the data types instead of values.
Characters are appended to elements and attributes as follows: "?" (0 or 1), "*" (0 or more), "+" (1 or more).
Elements names ending in "…" indicate that elements/attributes irrelevant to the context are being omitted.
This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and later add more requirements to illustrate how more advanced WSDL 2.0 features may be used.
Hotel GreatH (a fictional hotel) is located in a remote island. It has been relying on fax and phone to provide room reservations. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires us to build a reservation Web service with the following functionality:
CheckAvailability. To check availability, the client
must specify a check-in date, a check-out date, and room type. The
Web service will return a room rate (a floating point number in
USD) if such a room is available, or a zero room rate if not. If
any input data is invalid, the service should return an error.
Thus, the service will accept a checkAvailability
message and return a checkAvailabilityResponse
or
invalidDataFault
message.
MakeReservation. To make a reservation, a client must
provide a name, address, and credit card information, and the
service will return a confirmation number if the reservation is
successful. The service will return an error message if the credit
card number or any other data field is invalid. Thus, the service
will accept a makeReservation
message and return a
makeReservationResponse
or
invalidCreditCardFault
message.
The next several sections proceed step-by-step through the process of developing a WSDL 2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the WSDL 2.0 document that we'll be creating.
Example 2-1. WSDL 2.0 Document for the GreatH Web Service (Initial Example)
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" xmlns:wsoap= "http://www.w3.org/ns/wsdl/soap" xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsdlx= "http://www.w3.org/ns/wsdl-extensions"> <documentation> This document describes the GreatH Web service. Additional application-level requirements for use of this service -- beyond what WSDL 2.0 is able to describe -- are available at http://greath.example.com/2004/reservation-documentation.html </documentation> <types> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://greath.example.com/2004/schemas/resSvc" xmlns="http://greath.example.com/2004/schemas/resSvc"> <xs:element name="checkAvailability" type="tCheckAvailability"/> <xs:complexType name="tCheckAvailability"> <xs:sequence> <xs:element name="checkInDate" type="xs:date"/> <xs:element name="checkOutDate" type="xs:date"/> <xs:element name="roomType" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:element name="checkAvailabilityResponse" type="xs:double"/> <xs:element name="invalidDataError" type="xs:string"/> </xs:schema> </types> <interface name = "reservationInterface" > <fault name = "invalidDataFault" element = "ghns:invalidDataError"/> <operation name="opCheckAvailability" pattern="http://www.w3.org/ns/wsdl/in-out" style="http://www.w3.org/ns/wsdl/style/iri" wsdlx:safe = "true"> <input messageLabel="In" element="ghns:checkAvailability" /> <output messageLabel="Out" element="ghns:checkAvailabilityResponse" /> <outfault ref="tns:invalidDataFault" messageLabel="Out"/> </operation> </interface> <binding name="reservationSOAPBinding" interface="tns:reservationInterface" type="http://www.w3.org/ns/wsdl/soap" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"> <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/> <operation ref="tns:opCheckAvailability" wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"/> </binding> <service name="reservationService" interface="tns:reservationInterface"> <endpoint name="reservationEndpoint" binding="tns:reservationSOAPBinding" address ="http://greath.example.com/2004/reservation"/> </service> </description>
Before writing our WSDL 2.0 document, we need to decide on a WSDL 2.0 target namespace URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.)
The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSDL 2.0 target namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 processor must not depend on it being dereferenceable.
This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.
Once we have decided on a WSDL 2.0 target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.
Example 2-2. An Initial Empty WSDL 2.0 Document
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" . . . > . . . </description>
<description
Every WSDL 2.0 document has a description
element
as its top-most element. This merely acts as a container for the
rest of the WSDL 2.0 document, and is used to declare namespaces
that will be used throughout the document.
xmlns="http://www.w3.org/ns/wsdl"
This is the XML namespace for WSDL 2.0 itself. We assign it as
the default namespace for this example by not defining a prefix for
it. In other words, any unprefixed elements in this example are
expected to be WSDL 2.0 elements (such as the
description
element).
targetNamespace=
"http://greath.example.com/2004/wsdl/resSvc"
This defines the WSDL 2.0 target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rather, it is a WSDL 2.0 attribute whose purpose is analogous to an XML Schema target namespace.
xmlns:tns=
"http://greath.example.com/2004/wsdl/resSvc"
This is an actual XML namespace declaration for use in our
GreatH service description. Note that this is the same URI that was
specified above as the value of the targetNamespace
attribute. This will allow us later to use the tns:
prefix in QNames, to refer to the WSDL 2.0 target namespace of the
GreatH service. (For more on QNames see [XML
Namespaces] section 3 Qualified
Names.)
Now we can start describing the GreatH service.
We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 processors are likely to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.
WSDL 2.0 allows message types to be defined directly within the
WSDL 2.0 document, inside the types
element, which is
a child of the description
element. (Later we'll see
how we can provide the type definitions in a separate document,
using XML Schema's import
mechanism.) The following
schema defines checkAvailability
,
checkAvailabilityResponse
and
invalidDataError
message types that we'll need.
In WSDL 2.0, all normal and fault message types must be defined as single elements at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type.
Example 2-3. GreatH Message Types
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" . . . > ... <types> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://greath.example.com/2004/schemas/resSvc" xmlns="http://greath.example.com/2004/schemas/resSvc"> <xs:element name="checkAvailability" type="tCheckAvailability"/> <xs:complexType name="tCheckAvailability"> <xs:sequence> <xs:element name="checkInDate" type="xs:date"/> <xs:element name="checkOutDate" type="xs:date"/> <xs:element name="roomType" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:element name="checkAvailabilityResponse" type="xs:double"/> <xs:element name="invalidDataError" type="xs:string"/> </xs:schema> </types> . . . </description>
xmlns:ghns =
"http://greath.example.com/2004/schemas/resSvc"
We've added another namespace declaration. The ghns
namespace prefix will allow us (later, when defining an interface)
to reference the XML Schema target namespace that we define for our
message types. Thus, the URI we specify must be the same as the URI
that we define as the target namespace of our XML Schema types
(below) -- not the target namespace of the WSDL 2.0
document itself.
targetNamespace="http://greath.example.com/2004/schemas/resSvc"
This is the XML Schema target namespace that we've created for
use by the GreatH reservation service. The
checkAvailability
,
checkAvailabilityResponse
and
invalidDataError
element names will be associated with
this XML Schema target namespace.
checkAvailability
,
checkAvailabilityResponse
and
invalidDataError
These are the message types that we'll use. Note that these are defined to be XML elements, as explained above.
Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section.
WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL 2.0 document that describes it.
A WSDL 2.0 interface
defines the abstract interface
of a Web service as a set of abstract operations, each
operation representing a simple interaction between the client and
the service. Each operation specifies the types of messages that
the service can send or receive as part of that operation. Each
operation also specifies a message exchange pattern that
indicates the sequence in which the associated messages are to be
transmitted between the parties. For example, the in-out
pattern (see WSDL 2.0 Predefined Extensions
[WSDL 2.0 Adjuncts] section
2.2.3 In-Out)
indicates that if the client sends a message in to the
service, the service will either send a reply message back
out to the client (in the normal case) or it will send a
fault message back to the client (in the case of an error). We will
explain more about message exchange patterns in 2.4.4.3 Understanding Message
Exchange Patterns (MEPs)
For the GreatH service, we will (initially) define an interface
containing a single operation, opCheckAvailability
,
using the checkAvailability
and
checkAvailabilityResponse
message types that we
defined in the types
section. We'll use the in-out
pattern for this operation, because this is the most natural way to
represent a simple request-response interaction. We could have
instead (for example) defined two separate operations using the
in-only
and
out-only patterns (see WSDL 2.0 Predefined Extensions
[WSDL 2.0 Adjuncts] section
2.2.1 In-Only
and section 2.2.5
Out-Only), but that would just complicate matters for the
client, because we would then have to separately indicate to the
client developer that the two operations should be used together as
a request-response pair.
In addition to the normal input and output messages, we also
need to specify the fault message that we wish to use in the event
of an error. WSDL 2.0 permits fault messages to be declared within
the interface
element in order to facilitate reuse of
faults across operations. If a fault occurs, it terminates whatever
message sequence was indicated by the message exchange pattern of
the operation.
Let's add these to our WSDL 2.0 document.
Example 2-4. GreatH Interface Definition
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" . . . xmlns:wsdlx="http://www.w3.org/ns/wsdl-extensions"> . . . <types> ... </types> <interface name = "reservationInterface" > <fault name = "invalidDataFault" element = "ghns:invalidDataError"/> <operation name="opCheckAvailability" pattern="http://www.w3.org/ns/wsdl/in-out" style="http://www.w3.org/ns/wsdl/style/iri" wsdlx:safe = "true"> <input messageLabel="In" element="ghns:checkAvailability" /> <output messageLabel="Out" element="ghns:checkAvailabilityResponse" /> <outfault ref="tns:invalidDataFault" messageLabel="Out"/> </operation> </interface> . . . </description>
<interface name = "reservationInterface"
>
Interfaces are declared directly inside the
description
element. In this example, we are declaring
only one interface, but in general a WSDL 2.0 document may declare
more than one interface. Thus, each interface must be given a name
that is unique within the set of interfaces defined in this WSDL
2.0 target namespace. Interface names are tokens that must not
contain a space or colon (":").
<fault name =
"invalidDataFault"
The name
attribute defines a name for this fault.
The name is required so that when an operation is defined, it can
reference the desired fault by name. Fault names must be unique
within an interface.
element =
"ghns:invalidDataError"/>
The element
attribute specifies the schema type of
the fault message, as previously defined in the types
section.
<operation
name="opCheckAvailability"
The name
attribute defines a name for this
operation, so that it can be referenced later when bindings are
defined. Operation names must also be unique within an interface.
(WSDL 2.0 uses separate symbol spaces for operation and fault
names, so operation name "foo" is distinct from fault name
"foo".)
pattern="http://www.w3.org/ns/wsdl/in-out"
This line specifies that this operation will use the in-out pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does not mean that other WSDL 2.0 processors will automatically recognize or understand that pattern. As with any other extension, it can only be used among processors that do recognize and understand it.)
style="http://www.w3.org/ns/wsdl/style/iri"
This line indicates that the XML schema defining the input message of this operation follows a set of rules as specified in IRI Style that ensures the message can be serialized as an IRI.
wsdlx:safe="true" >
This line indicates that this operation will not obligate the client in any way, i.e., the client can safely invoke this operation without fear that it may be incurring an obligation (such as agreeing to buy something). This is further explained in 2.4.4 Interface Operations.
<input messageLabel="In"
The input
element specifies an input message. Even
though we have already specified which message exchange pattern the
operation will use, a message exchange pattern represents a
template for a message sequence, and in theory could consist of
multiple input and/or output messages. Thus we must also indicate
which potential input message in the pattern this particular input
message represents. This is the purpose of the
messageLabel
attribute. Since the in-out
pattern that we've chosen to use only has one input message, it is
trivial in this case: we simply fill in the message label "In" that
was defined in WSDL 2.0 Predefined Extensions
[WSDL 2.0 Adjuncts] section
2.2.3 In-Out
for the in-out
pattern. However, if a new pattern is defined that involve multiple
input messages, then the different input messages in the pattern
could then be distinguished by using different labels.
element="ghns:checkAvailability"
/>
This specifies the message type for this input message, as
defined previously in the types
section.
<output messageLabel="Out" . .
.
This is similar to defining an input message.
<outfault ref="tns:invalidDataFault"
messageLabel="Out"/>
This associates an output fault with this operation. Faults are
declared a little differently than normal messages. The
ref
attribute refers to the name of a previously
defined fault in this interface -- not a message schema type
directly. Since message exchange patterns could in general involve
a sequence of several messages, a fault could potentially occur at
various points within the message sequence. Because one may wish to
associate a different fault with each permitted point in the
sequence, the messageLabel
is used to indicate the
desired point for this particular fault. It does so indirectly by
specifying the message that will either trigger this fault or that
this fault will replace, depending on the pattern. (Some patterns
use a
message-triggers-fault rule; others use a
fault-replaces-message rule. See WSDL 2.0 Predefined
Extensions [WSDL 2.0
Adjuncts] section 2.1.2
Message Triggers Fault and section 2.1.1
Fault Replaces Message.)
Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.
Although we have specified what abstract messages can be exchanged with the GreatH Web service, we have not yet specified how those messages can be exchanged. This is the purpose of a binding. A binding specifies concrete message format and transmission protocol details for an interface, and must supply such details for every operation and fault in the interface.
In the general case, binding details for each operation and
fault are specified using operation
and
fault
elements inside a binding
element,
as shown in the example below. However, in some cases it is
possible to use defaulting rules to supply the information. The
WSDL 2.0 SOAP binding extension, for example, defines some
defaulting rules for operations. (See Web Services Description
Language (WSDL) Version 2.0 Part 2: Adjuncts [WSDL 2.0 Adjuncts],
Default Binding Rules.)
In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. (See 4.1 Extensibility for more on extensibility.) WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines binding extensions for SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework] and HTTP 1.1 [IETF RFC 2616] as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL 2.0 documents. However, other specifications could define new binding extensions that could also be used to define bindings. (As with any extension, other WSDL 2.0 processors would have to know about the new constructs in order to make use of them.)
For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below.
Example 2-5. GreatH Binding Definition
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" xmlns:wsoap= "http://www.w3.org/ns/wsdl/soap" xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> . . . <types> . . . </types> <interface name = "reservationInterface" > ... </interface> <binding name="reservationSOAPBinding" interface="tns:reservationInterface" type="http://www.w3.org/ns/wsdl/soap" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"> <operation ref="tns:opCheckAvailability" wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"/> <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/> </binding> . . . </description>
xmlns:wsoap=
"http://www.w3.org/ns/wsdl/soap"
We've added two more namespace declarations. This one is the
namespace for the SOAP 1.2 binding extension that is defined in
WSDL 2.0 Part 3 [SOAP 1.2 Part 1:
Messaging Framework]. Elements and attributes prefixed
with wsoap:
are constructs defined there.
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
This namespace is defined by the SOAP 1.2 specification itself.
The SOAP 1.2 specification defines certain terms within this
namespace to unambiguously identify particular concepts. Thus, we
will use the soap:
prefix when we need to refer to one
of those terms.
<binding
name="reservationSOAPBinding"
Bindings are declared directly inside the
description
element. The name
attribute
defines a name for this binding. Each name must be unique among all
bindings in this WSDL 2.0 target namespace, and will be used later
when we define a service endpoint that references this binding.
WSDL 2.0 uses separate symbol spaces for interfaces, bindings and
services, so interface "foo", binding "foo" and service "foo" are
all distinct.
interface="tns:reservationInterface"
This is the name of the interface whose message format and
transmission protocols we are specifying. As discussed in 2.5 More on Bindings, a
reusable binding can be defined by omitting the
interface
attribute. Note also the use of the
tns:
prefix, which refers to the previously defined
WSDL 2.0 target namespace for this WSDL 2.0 document. In this case
it may seem silly to have to specify the tns:
prefix,
but in 3.1 Importing
WSDL we will see how WSDL 2.0's import mechanism can
be used to combine components that are defined in different WSDL
2.0 target namespaces.
type="http://www.w3.org/ns/wsdl/soap"
This specifies what kind of concrete message format to use, in this case SOAP 1.2.
wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"
This attribute is specific to WSDL 2.0's SOAP binding extension
(thus it uses the wsoap:
prefix). It specifies the
underlying transmission protocol that should be used, in this case
HTTP.
<operation
ref="tns:opCheckAvailability"
This is not defining a new operation; rather, it is referencing
the previously defined opCheckAvailability
operation
in order to specify binding details for it. This element can be
omitted if defaulting rules are instead used to supply the
necessary information. (See the SOAP binding extension in WSDL 2.0
Part 2 [WSDL 2.0 Adjuncts]
section 4.3
Default Binding Rules .)
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response">
This attribute is also specific to WSDL 2.0's SOAP binding
extension. It specifies the SOAP message exchange pattern (MEP)
that will be used to implement the abstract WSDL 2.0 message
exchange pattern (in-out)
that was specified when the opCheckAvailability
operation was defined.
When HTTP is used as the underlying transport protocol (as in
this example) the wsoap:mep
attribute also controls
whether GET or POST will be used as the underlying HTTP method. In
this case, the use of
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"
causes GET to be used by default. See also 2.5.7 HTTP GET Versus POST: Which to
Use?.
<fault
ref="tns:invalidDataFault"
As with a binding operation, this is not declaring a new fault;
rather, it is referencing a fault (invalidDataFault
)
that was previously defined in the opCheckAvailability
interface, in order to specify binding details for it.
wsoap:code="soap:Sender"/>
This attribute is also specific to WSDL 2.0's SOAP binding
extension. This specifies the SOAP 1.2 fault code that will cause
this fault message to be sent. If desired, a list of subcodes can
also be specified using the optional wsoap:subcodes
attribute.
Now that our binding has specified how messages will be
transmitted, we are ready to specify where the service can
be accessed, by use of the service
element.
A WSDL 2.0 service specifies a single interface that the service will support, and a list of endpoint locations where that service can be accessed. Each endpoint must also reference a previously defined binding to indicate what protocols and transmission formats are to be used at that endpoint. A service is only permitted to have one interface. (See 5.4 Multiple Interfaces for the Same Service for further discussion of this limitation.)
Here is a definition for our GreatH service.
Example 2-6. GreatH Service Definition
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" xmlns:wsoap= "http://www.w3.org/ns/wsdl/soap" xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> . . . <types> . . . </types> <interface name = "reservationInterface" > . . . </interface> <binding name="reservationSOAPBinding" interface="tns:reservationInterface" . . . > . . . </binding> <service name="reservationService" interface="tns:reservationInterface"> <endpoint name="reservationEndpoint" binding="tns:reservationSOAPBinding" address ="http://greath.example.com/2004/reservation"/> </service> </description>
<service
name="reservationService"
This defines a name for this service, which must be unique among service names in the WSDL 2.0 target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See WSDL 2.0 Core Language [WSDL 2.0 Core] appendix C IRI References for WSDL 2.0 constructs.)
interface="tns:reservationInterface">
This specifies the name of the previously defined interface that these service endpoints will support.
<endpoint
name="reservationEndpoint"
This defines an endpoint for the service, and a name for this endpoint, which must be unique within this service.
binding="tns:reservationSOAPBinding"
This specifies the name of the previously defined binding to be used by this endpoint.
address
="http://greath.example.com/2004/reservation"/>
This specifies the physical address at which this service can be
accessed using the binding specified by the binding
attribute.
That's it! Well, almost.
As we have seen, a WSDL 2.0 document is inherently only a partial description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.
The documentation
element allows the WSDL 2.0
author to include some human-readable documentation inside a WSDL
2.0 document. It is also a convenient place to reference any
additional external documentation that a client developer may need
in order to use the service. It can appear in a number of places in
a WSDL 2.0 document (see 2.2.1 WSDL 2.0
Infoset), though in this example we have only
demonstrated its use at the beginning.
Example 2-7. Documenting the GreatH Service
<?xml version="1.0" encoding="utf-8" ?> <description . . . > <documentation> This document describes the GreatH Web service. Additional application-level requirements for use of this service -- beyond what WSDL 2.0 is able to describe -- are available at http://greath.example.com/2004/reservation-documentation.html </documentation> . . . </description>
<documentation>
This element is optional, but a good idea to include. It can contain arbitrary mixed content.
at
http://greath.example.com/2004/reservation-documentation.html
The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use the service.
This completes our presentation of the GreatH example. In the following sections, we will move on to look into more details of various aspects of WSDL 2.0 specification.
In computer science theory, a language consists of a (possibly infinite) set of sentences, and each sentence is a finite string of literal symbols or characters. A language specification must therefore define the set of sentences in that language, and, to be useful, it should also indicate the meaning of each sentence. Indeed, this is the purpose of the WSDL 2.0 specification.
However, instead of defining WSDL 2.0 in terms of literal
symbols or characters, to avoid dependency on any particular
character encoding, WSDL 2.0 is defined in terms of the XML
Infoset [XML Information
Set]. Specifically, a WSDL 2.0 document
consists of a description
element information item (in
the XML Infoset) that conforms to the WSDL 2.0 specification. In
other words, a sentence in the WSDL 2.0 language is a
description
element information item that obeys the
additional constraints spelled out in the WSDL 2.0
specification.
Since an XML Infoset can be created from more than one physical
document, a WSDL 2.0 document does not necessarily correspond to a
single physical document: the word "document" is used
figuratively, for convenience. Furthermore, since WSDL 2.0 provides
import
and include
mechanisms, a WSDL 2.0
document may reference other WSDL 2.0 documents to facilitate
convenient organization or reuse. In such cases, the meaning of the
including or importing document as a whole will depend (in part) on
the meaning of the included or imported document.
The XML Infoset uses terms like "element information item" and "attribute information item". Unfortunately, those terms are rather lengthy to repeat often. Thus, for convenience, this primer often uses the terms "element" and "attribute" instead, as a shorthand. It should be understood, however, that since WSDL 2.0 is based on the XML Infoset, we really mean "element information item" and "attribute information item", respectively.
The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.
Figure 2-1. WSDL 2.0 Infoset Diagram
The WSDL 2.0 specification supplies a normative WSDL 2.0 schema, defined in [XML Schema Structures], which can be used as an aid in validating WSDL 2.0 documents. We say "as an aid" here because WSDL 2.0 specification [WSDL 2.0 Core] often provides further constraints to the WSDL 2.0 schema. In addition to being valid with the normative schema, a WSDL 2.0 document must also follow all the constraints defined by the WSDL 2.0 specification.
This section gives an example of how WSDL 2.0 specification constrains the WSDL 2.0 schema about the ordering of top WSDL 2.0 elements.
Although the WSDL 2.0 schema does not indicate the required
ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1
[WSDL 2.0 Core] section
"XML
Representation of Description Component") clearly states a set
of constraints about how the child elements of the
description
element should be ordered. Thus, the order
of the WSDL 2.0 elements matters, even though the WSDL 2.0 schema
does not capture this constraint.
The following is a pseudo-content model of
description
.
<description> <documentation />? [ <import /> | <include /> ]* <types />? [ <interface /> | <binding /> | <service /> ]* </description>
In other words, the children elements of the
description
element should be ordered as follows:
An optional documentation
comes first, if
present.
then comes zero or more elements from among the following, in any order:
include
import
extensions
An optional types
follows
Zero or more elements from among the following, in any order:
interface
binding
service
extensions.
Note the term "extension" is used above as a convenient way to refer to namespace-qualified extension elements. The namespace name of such extension elements must not be"http://www.w3.org/ns/wsdl".
The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a component model as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. The following diagram gives an overview of the WSDL 2.0 components and their containment hierarchy.
Figure 2-2. WSDL 2.0 Components Containment hierarchy
In general, the WSDL 2.0 component model parallels the structure
of the required XML Infoset illustrated above. For example, the
Description, Interface, Binding,
Service and Endpoint components
correspond to the description
, interface
,
binding
, service
, and
endpoint
element information items, respectively.
Since WSDL 2.0 relies heavily on the component model to convey the
meaning of the constructs in the WSDL 2.0 language, you can think
of the Description component as representing the meaning of the
description
element information item, and hence, it
represents the meaning of the WSDL 2.0 document as a whole.
Furthermore, each of these components has properties
whose values are (usually) derived from the element and attribute
information item children of those element information items. For
example, the Service component corresponds to the
service
element information item, so the Service
component has an {endpoints} property whose value is a set of
Endpoint components corresponding to the endpoint
element information item children of that service
element information item. (Whew!)
The WSDL 2.0 component model is particularly helpful in defining
the meaning of import
and include
elements. The include
element allows you to assemble
the contents of a given WSDL 2.0 namespace from several WSDL 2.0
documents that define components for that namespace. The components
defined by a given WSDL 2.0 document consist of those whose
definitions are contained in the document and those that are
defined by any WSDL 2.0 documents that are included in it via the
include
element. The effect of the
include
element is cumulative so that if document A
includes document B and document B includes document C, then the
components defined by document A consist of those whose definitions
are contained in documents A, B, and C.
In contrast, the import
element does not define any
components. Instead, the import
element declares that
the components whose definitions are contained in a WSDL 2.0
document for a given WSDL 2.0 namespace refer to components that
belong to a different WSDL 2.0 namespace. If a WSDL 2.0 document
contains definitions of components that refer to other namespaces,
then those namespaces must be declared via an import
element. The import
element also has an optional
location
attribute that is a hint to the processor
where the definitions of the imported namespace can be found.
However, the processor may find the definitions by other means, for
example, by using a catalog.
After processing any include
elements and locating
the components that belong to any imported namespaces, the WSDL 2.0
component model for a WSDL 2.0 document will contain a set of
components that belong to the document's WSDL 2.0 namespace and any
imported namespaces. These components will refer to each other,
usually via QName references. A WSDL 2.0 document is invalid if any
component reference cannot be resolved, whether or not the
referenced component belongs to the same or a different
namespace.
We will cover a lot more about how to use WSDL 2.0 import and include in 3.1 Importing WSDL
Message types may be defined in various schema languages. In
this primer, we will only focus on the use of XML Schema
[XML Schema Structures]
since it's natively supported by WSDL 2.0. Message types defined in
other languages may be introduced into a WSDL 2.0
description
via extensions, see the W3C notes
[Alternative Schema Languages
Support] for more details.
The following is the XML syntax for the wsdl:types
element:
<description> <types> <documentation />* [ <xs:import namespace="xs:anyURI" schemaLocation="xs:anyURI"? /> | <xs:schema targetNamespace="xs:anyURI" /> | other extension elements ]* </types> </description>
There are two ways to make XML Schema message definitions
visible, or in other words, available for reference by QName (see
WSDL 2.0 Part 1 [WSDL 2.0
Core] "QName
Resolution") in a WSDL 2.0 document: inlining or importing.
Inlining is to put the schema definitions directly within an
xs:schema
element under types
. Importing
is to have the schema defined in a separate document and then bring
it into the WSDL definition by using xs:import
directly under types
.
In the following sections, we will provide examples for the different mechanisms.
We have already seen an example of using inlined schema
definitions in section 2.1.3
Defining Message Types. When XML Schema is inlined
directly in a WSDL 2.0 document, it uses the existing top-level
xs:schema
element defined by XML Schema to do so, as
though a schema file had been copied and pasted into the
types
element. The schema components defined in the
inlined schema are then available to the containing WSDL 2.0
description
for reference by QName. For instance, in
Example 2-1, the input message of
the interface operation "opCheckAvailability" is defined by the
"ghns:checkAvailability" element in the inlined schema.
XML Schema components can be defined in separate schema files
and be made available to a WSDL2.0 description
by
using xs:import
directly under types
.
There are many cases where one would prefer having schema
definitions in separate schema files. One reason is the reusability
of the schema definitions. Inlined schema definitions are only
available to the containing WSDL 2.0 description
.
Although WSDL 2.0 provides a wsdl:import
mechanism for
importing other WSDL files, schema definitions inlined in an
imported WSDL document are NOT automatically made available to the
importing WSDL 2.0 document, even though other WSDL 2.0 components
(such as Interfaces, Bindings, etc.) do become available.
Therefore, if one wishes to share schema definitions across several
WSDL 2.0 description
s, these schema definitions should
instead be placed in separate XML Schema documents and imported
into each WSDL 2.0 description
using
xs:import
directly under types
.
Let's see an example. Assuming the message types in Example 2-3 are defined in a separate
schema file named
"http://greath.example.com/2004/schemas/resSvc.xsd" with a target
namespace "http://greath.example.com/2004/schemas/resSvc", the
schema definition can then be brought into the WSDL 2.0
description
using xs:import
. Note that
only components in the imported namespace
"http://greath.example.com/2004/schemas/resSvc" are available for
reference in the WSDL 2.0 document.
Example 2-8.
xs:import
ed Message Definitions that Are Visible to
the Containing WSDL 2.0 Description
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" . . . > . . . <types> <xs:import namespace="http://greath.example.com/2004/schemas/resSvc" schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/> </types> . . . </description>
It's important to note that xs:import
used directly
under wsdl:types
has been given a different visibility
than xs:import
used inside an inlined schema. An
inlined schema may use native XML schema xs:import
to
bring in external schema definitions that are in different
namespaces; However, though this is the schema importing mechanism
recommended for WSDL 1.1 in
WS-I Basic Profile, according to XML Schema specification, such
enclosed message definitions are only visible to the importing
schema (in this case, the inlined schema). They are not visible to
the containing WSDL 2.0 description
.
If we change Example 2-8 to
use XML Schema's native xs:import
element in an
inlined schema, the schema components defined in the namespace
http://greath.example.com/2004/schemas/resSvc are not available to
our example WSDL 2.0 definition any more.
Example 2-9.
xs:import
ed Message Definitions in Inlined Schema Are
Not Visible to the Containing WSDL 2.0 Description
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" . . . > . . . <types> <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvcWrapper"> <xs:import namespace="http://greath.example.com/2004/schemas/resSvc" schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/> </xs:schema> </types> . . . </description>
Of course, an inlined XML schema may also use XML Schema's
native xs:include
element to refer to schemas defined
in separate files when the included schema has no namespace or has
the same namespace as the including schema. In this case, according
to XML Schema, the included schema components become a part of the
including schema as though they had been copied and pasted into the
including schema. Hence, the included schema components are also
available to the containing WSDL 2.0 description
for
reference by QName.
The following example has the same effect as Example 2-3:
Example 2-10.
xs:included
Message Definitions in Inlined Schema Are
Visible to the Containing WSDL 2.0 Description
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc" . . . > . . . <types> <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvc"> <xs:include schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/> </xs:schema> </types> . . . </description>
So far we have briefly covered both WSDL import and include and
schema import and include. The following table summarizes the
similarities and differences between the WSDL 2.0 and XML Schema
include
and import
mechanisms. We will
talk a lot more about importing mechanisms in 3.1 Importing WSDL
and 3.2 Importing
Schemas
Mechanism | Object | Meaning | Visibility of Schema Components |
---|---|---|---|
wsdl:import | WSDL 2.0 Namespace | Declare that WSDL 2.0 components refer to WSDL 2.0 components from a DIFFERENT targetNamespace. | XML Schema Components in the imported
Description component are NOT visible to the containing
description . |
wsdl:include | WSDL 2.0 Document | Merge Interface, Binding and Service components from another WSDL 2.0 document that has the SAME targetNamespace. | XML Schema components in the included
Description component's {element
declarations} and {type
definitions} properties are visible to the containing
description . |
wsdl:types/ xs:import | XML Schema Namespace | Declare that XML Schema components refer to XML Schema components from a DIFFERENT targetNamespace. | XML Schema components in the imported
namespace are visible to the containing
description . |
wsdl:types/ xs:schema/xs:import | XML Schema Namespace | Declare that XML Schema components refer to XML Schema components from a DIFFERENT targetNamespace. | XML Schema components in the imported
namespace are NOT visible to the containing
description . |
wsdl:types/ xs:schema/xs:include | XML Schema Document | Merge XML Schema components from another XML Schema document that has the SAME or NO targetNamespace. | XML Schema components in the included
document are visible to the containing
description . |
We previously mentioned that a WSDL 2.0 interface is basically a
set of operations. However, there are some additional capabilities
that we have not yet covered. First, let's review the syntax for
the interface
element.
Below is the XML syntax summary of the interface
element, simplified by omitting optional
<documentation>
elements:
<description targetNamespace="xs:anyURI" > . . . <interface name="xs:NCName" extends="list of xs:QName"? styleDefault="list of xs:anyURI"? > <fault name="xs:NCName" element="xs:QName"? > </fault>* <operation name="xs:NCName" pattern="xs:anyURI" style="list of xs:anyURI"? wsdlx:safe="xs:boolean"? > <input messageLabel="xs:NCName"? element="union of xs:QName, xs:Token"? > </input>* <output messageLabel="xs:NCName"? element="union of xs:QName, xs:Token"? > </output>* <infault ref="xs:QName" messageLabel="xs:NCName"? > </infault>* <outfault ref="xs:QName" messageLabel="xs:NCName"? > </outfault>* </operation>* </interface>* . . . </description>
The interface
element has two optional attributes:
styleDefault
and extends
. The
styleDefault
attribute can be used to define a default
value for the style
attributes of all operations under
this interface (see WSDL 2.0 Part 1 "styleDefault
attribute information item"). The extends
attribute is for inheritance, and is explained next.
The optional extends
attribute allows an interface
to extend or inherit from one or more other interfaces. In such
cases the interface contains the operations of the interfaces it
extends, along with any operations it defines directly. Two things
about extending interfaces deserve some attention.
First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends must NOT themselves extend that interface either directly or indirectly.
Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 [WSDL 2.0 Core] " Equivalence of Components ") then they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendants.) In the second case, if two operations have the same name in the same WSDL 2.0 target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely.
Finally, since faults can also be defined as children of the
interface
element (as described in the following
sections), the same name-collision rules apply to those
constructs.
Let's say the GreatH hotel wants to maintain a standard message
log operation for all received messages. It wants this operation to
be reusable across the whole reservation system, so each service
will send out, for potential use of a logging service, the content
of each message it receives together with a timestamp and the
originator of the message. One way to meet such requirement is to
define the log operation in an interface which can be inherited by
other interfaces. Assuming a messageLog
element is
already defined in the ghns namespace with the required content,
the inheritance use case is illustrated in the following example.
As a result of the inheritance, the
reservationInterface
now contains two operations:
opCheckAvailability
and opLogMessage
Example 2-11. Interface Inheritance
<description ...> ... <interface name = "messageLogInterface" > <operation name="opLogMessage" pattern="http://www.w3.org/ns/wsdl/out-only"> <output messageLabel="out" element="ghns:messageLog" /> </operation> </interface> <interface name="reservationInterface" extends="tns:messageLogInterface" > <operation name="opCheckAvailability" pattern="http://www.w3.org/ns/wsdl/in-out" style="http://www.w3.org/ns/wsdl/style/iri" wsdlx:safe = "true"> <input messageLabel="In" element="ghns:checkAvailability" /> <output messageLabel="Out" element="ghns:checkAvailabilityResponse" /> <outfault ref="tns:invalidDataFault" messageLabel="Out"/> </operation> </interface> ... </description>
Now let's have a look at the element children of
interface
, beginning with fault
.
The fault
element is used to declare faults that
may occur during execution of operations of an interface. They are
declared directly under interface
, and referenced from
operations where they apply, in order to permit reuse across
multiple operations.
Faults are very similar to messages and can be viewed as a special kind of message. Both faults and messages may carry a payload that is normally described by an element declaration. However, WSDL 2.0 treats faults and messages slightly differently. The messages of an operation directly refer to their element declaration, however the faults of an operation indirectly refer to their element declaration via a fault element that is defined on the interface.
The reason for defining faults at the interface level is to allow their reuse across multiple operations. This design is especially beneficial when bindings are defined, since in binding extensions like SOAP there is additional information that is associated with faults. In the case of SOAP, faults have codes and subcodes in addition to a payload. By defining faults at the interface level, common codes and subcodes can be associated with them, thereby ensuring consistency across all operations that use the faults
The fault
element has a required name
attribute that must be unique within the parent
interface
element, and permits it to be referenced
from operation declarations. The optional element
attribute can be used to indicate a schema for the content or
payload of the fault message. Its value should be the QName of a
global element defined in the types
section. Please
note that when other type systems are used to define the schema for
a fault message, additional attributes may need to be defined via
WSDL 2.0's attribute extension mechanism to allow the schema to be
associated with the fault.
As shown earlier, the operation
element is used to
indicate an operation supported by the containing interface. It
associates message schemas with a message exchange pattern (MEP),
in order to abstractly describe a simple interaction with a Web
service.
An operation
has two required attributes and one
optional attribute:
A required name
attribute, as seen already, which
must be unique within the interface.
A required pattern
attribute whose value must be an
absolute URI that identifies the desired MEP for the
operation
. MEPs are further explained in 2.4.4.3 Understanding Message
Exchange Patterns (MEPs).
An optional style
attribute whose value is a list
of absolute URIs. Each URI identifies a certain set of rules that
were followed in defining this operation
. It is an
error if a particular style is indicated, but the associated rules
are not followed. [WSDL 2.0
Adjuncts] defines a set of styles, including
RPC Style. The RPC style is selected when the style
is assigned the value http://www.w3.org/ns/wsdl/rpc. It places
restrictions for Remote Procedure Call-types of interactions.
IRI Style. The IRI style is selected when the style
is assigned the value http://www.w3.org/ns/wsdl/style/iri. It
places restrictions on message definitions so they may be
serialized into something like HTTP URL encoded.
The Multipart style. The Multipart style is selected when the
style
is assigned the value
http://www.w3.org/ns/wsdl/style/multipart. In the HTTP binding, for
XForms clients, a message must be defined following the Multipart
style and serialized as "Multipart/form-data".
You can find more details of these WSDL 2.0 predefined styles.
Section 4.3 RPC Style
provides an example of using the RPC style
.
[WSDL 2.0 Adjuncts] provides
examples for the IRI style and Multipart style.
Note that [WSDL 2.0
Adjuncts] provides a predefined extension for indicating
operation safety. The wsdlx:safe
global attribute
whose value is a boolean can be used with an operation to indicate
whether the operation is asserted to be "safe" (as defined in
Section 3.5 of the Web Architecture [Web
Architecture]) for clients to invoke. In essence, a safe
operation is any operation that does not give the client any new
obligations. For example, an operation that permits the client to
check prices on products typically would not obligate the client to
buy those products, and thus would be safe, whereas an operation
for purchasing products would obligate the client to pay for the
products that were ordered, and thus would not be safe.
An operation should be marked safe (by using the
wsdlx:safe
and by setting its value to "true") if it
meets the criteria for a safe interaction defined in Section 3.5 of
the Web Architecture [Web
Architecture], because this permits the infrastructure
to perform efficiency optimizations, such as pre-fetch, re-fetch
and caching.
The default value of this attribute is false. If it is false or is not set, then no assertion is made about the safety of the operation; thus the operation may or may not be safe.
An operation
will also have input
,
output
,infault
, and/or
outfault
element children that specify the ordinary
and fault message types to be used by that operation. The MEP
specified by the pattern
attribute determines which of
these elements should be included, since each MEP has placeholders
for the message types involved in its pattern.
Since operations were already discussed in 2.1.4 Defining an Interface, this section will merely comment on additional capabilities that were not previously explained.
The messageLabel
attribute of the
input
and output
elements is optional. It
is not necessary to explicitly set the messageLabel
when the MEP in use is one of the eight MEPs predefined in WSDL 2.0
Part 2 [WSDL 2.0 Adjuncts]
and it has only one message with a given direction.
The element
attribute of the input
and
output
elements is used to specify the message content
schema (aka payload schema) when the content model is defined using
XML Schema. As we have seen already, it can specify the QName of an
element schema that was defined in the types
section.
However, alternatively it can specify one of the following
tokens:
#any
The message content is any single element.
#none
There is no message content, i.e., the message payload is empty.
#other
The message content is described by a non-XML type system. Extension attributes specify the type.
The element
attribute is also optional. If it is
not specified, then the message content is described by a non-XML
type system.
Note that there are situations that the information conveyed in
the element
attribute is not sufficient for a service
implementation to uniquely identify an incoming message and
dispatch it to an appropriate operation. In such situations,
additional means may be required to aid identifying an incoming
message. See 5.1 Enabling
Easy Message Dispatch for more detail.
WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types when an operation is defined, which includes specifying which MEP to use for that operation. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.
It's worth pointing out that WSDL 2.0 MEPs do not exhaustively describe the set of messages that may be exchanged between a service and other nodes. By some prior agreement, another node and/or the service may send other messages (to each other or to other nodes) that are not described by the MEP. For instance, even though an MEP may define a single message sent from a service to one other node, a service defined by that MEP may multicast that message to other nodes. To maximize reuse, WSDL 2.0 message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is relevant to both the Web service and the client that engages that service.
A total of eight MEPs are defined in [WSDL 2.0 Adjuncts]. These MEPs should cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can ever be used by operations. More MEPs can be defined for particular application needs by interested parties. (See 2.4.4.3 Understanding Message Exchange Patterns (MEPs) )
For the eight MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. For example, the In-Only pattern ("http://www.w3.org/ns/wsdl/in-only") consists of exactly one message received by a service from some other node. No fault can be generated. As a variation of In-Only, Robust In-Only pattern ("http://www.w3.org/ns/wsdl/robust-in-only") also consists of exactly one message received by a service, but in this case faults can be triggered by the message and must be delivered to the originator of the message. If there is no path to this node, the fault must be discarded. For details about the common fault generation models used by the eight WSDL 2.0 MEPs, see [WSDL 2.0 Adjuncts].
Depending on how the first message in the MEP is initiated, the eight WSDL 2.0 MEPs may be grouped into two groups: in-bound MEPs, for which the service receives the first message in the exchange, and out-bound MEPs, for which the service sends out the first message in the exchange. (Such grouping is not provided in the WSDL 2.0 specification and is presented here only for the purpose of easy reference in this primer).
A frequently asked question about out-bound MEPs is how a
service knows where to send the message. Services using out-bound
MEPs are typically part of large scale integration systems that
rely on mapping and routing facilities. In such systems, out-bound
MEPs are useful for specifying the functionality of a service
abstractly, including its requirements for potential customers,
while endpoint address information can be provided at deployment or
runtime by the underlying integration infrastructure. For example,
the GreatH hotel reservation system may require that every time a
customer interacts with the system to check availability, data
about the customer must be logged by a CRM system. At design time,
it's unknown which particular CRM system would be used together
with the reservation system. To address this requirement, we may
change the "reservationInterface" in Example 2-1 to include an out-bound
logInquiry operation. This logInquiry
operation
advertises to potential service clients that customer data will be
made available by the reservation service at run time. When the
reservation service is deployed to GreatH's IT landscape,
appropriate configuration time and run time infrastructure will
help determine which CRM system will get the customer data and log
it appropriately. It's worth noting that in addition to being used
by a CRM system for customer management purpose, the same data may
also be used by a system performance analysis tool for different
purpose. Providing an out-bound operation in the reservation
service enables loose coupling and so improves the overall GreatH
IT landscape's flexibility and scalability.
Example 2-12. Use of outbound MEPs
<description ...> ... <interface name="reservationInterface"> ... <operation name="opCheckAvailability" ... > <operation name="opLogInquiry" pattern="http://www.w3.org/ns/wsdl/out-only"> <output messageLabel="Out" element="ghns:customerData" /> </operation> </interface> ... </description>
Although the eight MEPs defined in WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens.
For more about defining new MEPs, see 4.2 Defining New MEPs.
Bindings are used to supply protocol and encoding details that
specify how messages are to be sent or received. Each
binding
element uses a particular binding
extension to specify such information. WSDL 2.0 Part 2
[WSDL 2.0 Adjuncts] defines
several binding extensions that are typically used. However,
binding extensions that are not defined in WSDL 2.0 Part 2 can also
be used, provided that client and service toolkits support
them.
Binding information must be supplied for every operation in the interface that is used in an endpoint. However, if the desired binding extension provides suitable defaulting rules, then the information will only need to be explicitly supplied at the interface level, and the defaulting rules will implicitly propagate the information to the operations of the interface. For example, see the Default Binding Rules of SOAP binding extension in WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts].
Since bindings are specified using extensions to the WSDL 2.0 language (i.e., binding extensions are not in the WSDL 2.0 namespace), the XML for expressing a binding will consist of a mixture of elements and attributes from WSDL 2.0 namespace and from the binding extension's namespace, using WSDL 2.0's open content model.
Here is a syntax summary for binding
, simplified by
omitting optional documentation
elements. Bear in mind
that this syntax summary only shows the elements and attributes
defined within the WSDL 2.0 namespace. When an actual binding is
defined, elements and attributes from the namespace of the desired
binding extension will also be intermingled as required by that
particular binding extension.
<description targetNamespace="xs:anyURI" > . . . <binding name="xs:NCName" interface="xs:QName"? > <fault ref="xs:QName" > </fault>* <operation ref="xs:QName" > <input messageLabel="xs:NCName"? > </input>* <output messageLabel="xs:NCName"? > </output>* <infault ref="xs:QName" messageLabel="xs:NCName"? > </infault>* <outfault ref="xs:QName" messageLabel="xs:NCName"? > </outfault>* </operation>* </binding>* . . . </description>
The binding
syntax parallels the syntax of
interface
: each interface construct has a binding
counterpart. Despite this syntactic similarity, they are indeed
different constructs, since they are in different symbol spaces and
are designed for different purposes.
A binding can either be reusable (applicable to any interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in 2.1.5 Defining a Binding.
To define a reusable binding, the binding
element
simply omits the interface
attribute and omits
specifying any operation-specific and fault-specific binding
details. Endpoints can later refer to a reusable binding in the
same manner as for a non-reusable binding. Thus, a reusable binding
becomes associated with a particular interface when it is
referenced from an endpoint, because an endpoint is part of a
service, and the service specifies a particular interface that it
implements. Since a reusable binding does not specify an interface,
reusable bindings cannot specify operation-specific details.
Therefore, reusable bindings can only be defined using binding
extensions that have suitable defaulting rules, such that the
binding information only needs to be explicitly supplied at the
interface level.
A binding fault
associates a concrete message
format with an abstract fault of an interface. It describes how
faults that occur within a message exchange of an operation will be
formatted, since the fault does not occur by itself. Rather, a
fault occurs as part of a message exchange specified by an
interface operation
and its binding counterpart, the
binding operation
.
A binding fault
has one required ref
attribute which is a reference, by QName, to an
interface
fault
. It identifies the
abstract interface fault
for which binding information
is being specified. Be aware that the value of ref
attribute of all the faults
under a
binding
must be unique. That is, one cannot define
multiple bindings for the same interface fault within a given
binding
.
A binding operation
describes a concrete binding of
an interface operation to a concrete message format. An interface
operation is uniquely identified by the WSDL 2.0 target namespace
of the interface and the name of the operation within that
interface, via the required ref
attribute of binding
operation
. As with faults, for each
operation
within a binding
, the value of
the ref
attribute must be unique.
The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts]) was primarily designed to support the features of SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework]. However, for backwards compatibility, it also provides some support for SOAP 1.1 [SOAP 1.1].
An example using the WSDL 2.0 SOAP binding extension was already presented in 2.1.5 Defining a Binding, but some additional points are worth mentioning:
Because the same binding extension is used for both SOAP 1.2 and
SOAP 1.1, a wsoap:version
attribute is provided to
allow you to indicate which version of SOAP you want. If this
attribute is not specified, it defaults to SOAP 1.2.
The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or both), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a given interface defines any faults, then corresponding binding information must be explicitly provided for each such fault.
If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See 2.5.7 HTTP GET Versus POST: Which to Use?.)
Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.
Example 2-13. SOAP 1.2 and SOAP 1.1 Bindings
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" targetNamespace="http://greath.example.com/2004/wsdl/resSvc" xmlns:tns="http://greath.example.com/2004/wsdl/resSvc" xmlns:ghns="http://greath.example.com/2004/schemas/resSvc" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"> .... <!-- SOAP 1.2 Binding --> <binding name="reservationSOAPBinding" interface="tns:reservationInterface" type="http://www.w3.org/ns/wsdl/soap" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"> <operation ref="tns:opCheckAvailability" wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"/> <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/> </binding> <!-- SOAP 1.1 Binding --> <binding name="reservationSOAP11Binding" interface="tns:reservationInterface" type="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.1" wsoap:protocol="http://www.w3.org/2006/01/soap11/bindings/HTTP/"> <operation ref="tns:opCheckAvailability"/> <fault ref="tns:invalidDataFault" wsoap:code="soap11:Client"/> </binding> <service name="reservationService" interface="tns:reservationInterface"> <!-- SOAP 1.2 End Point --> <endpoint name="reservationEndpoint" binding="tns:reservationSOAPBinding" address="http://greath.example.com/2004/reservation"/> <!-- SOAP 1.1 End Point --> <endpoint name="reservationEndpoint2" binding="tns:reservationSOAP11Binding" address="http://greath.example.com/2004/reservation"/> </service> </description>
Most lines in this example is the same as previously explained in 2.1.5 Defining a Binding, so we'll only point out lines that are demonstrating something new for SOAP 1.1 binding.
<description ...
xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
This is the namespace for terms defined within the SOAP 1.1 specification [SOAP 1.1].
<binding...wsoap:version="1.1"
This line indicates that this binding uses SOAP 1.1 [WSDL 2.0 SOAP 1.1 Binding], rather than SOAP 1.2.
wsoap:protocol="http://www.w3.org/2006/01/soap11/bindings/HTTP/">
This line specifies that HTTP should be used as the underlying transmission protocol. See also 2.5.7 HTTP GET Versus POST: Which to Use?.
<operation
ref="tns:opCheckAvailability"/>
Note that wsoap:mep
is not applicable to SOAP 1.1
binding.
<fault...wsoap:code="soap11:Client"/>
This line specifies the SOAP 1.1 fault code that will be used in transmitting invalidDataFault.
In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines a binding extension for HTTP 1.1 [IETF RFC 2616] and HTTPS [IETF RFC 2818], so that these protocols can be used natively to send and receive messages, without first encoding them in SOAP.
The HTTP binding extension provides many features to control:
Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other HTTP operations are supported.)
Input, output and fault serialization
Transfer codings
Authentication requirements
Cookies
HTTP over TLS (https)
As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also provides defaulting rules to permit binding information to be specified at the interface level and used by default for each operation in the affected interface, however, defaulting rules are not provided for binding faults.
Here is an example of using the HTTP binding extension to check hotel room availability at GreatH.
Example 2-14. HTTP Binding Extension
<?xml version="1.0" encoding="utf-8" ?> <description xmlns="http://www.w3.org/ns/wsdl" . . . xmlns:whttp="http://www.w3.org/ns/wsdl/http" > . . . <binding name="reservationHTTPBinding" interface="tns:reservationInterface" type="http://www.w3.org/ns/wsdl/http" whttp:methodDefault="GET"> <operation ref="tns:opCheckAvailability" whttp:location="{checkInDate}" /> </binding> <service name="reservationService" interface="tns:reservationInterface"> <!-- HTTP 1.1 GET End Point --> <endpoint name="reservationEndpoint" binding="tns:reservationHTTPBinding" address="http://greath.example.com/2004/checkAvailability/"/> </service> . . . </description>
Most of this example is the same as previously explained in 2.1.5 Defining a Binding, so we'll only point out lines that are demonstrating something new for HTTP binding extension.
<description...xmlns:whttp="http://www.w3.org/ns/wsdl/http"
>
This defines the namespace prefix for elements and attributes defined by the WSDL 2.0 HTTP binding extension.
<binding...type="http://www.w3.org/ns/wsdl/http"
This declares the binding as being an HTTP binding.
whttp:methodDefault="GET">
The default method for operations in this interface will be HTTP GET.
whttp:location="{checkInDate}"
>
The whttp:location
attribute specifies a pattern
for serializing input message instance data into the path component
of the request URI. The default binding rules for HTTP specify that
the default input serialization for GET is
application/x-www-form-urlencoded
. Curly braces are
used to specify the name of a schema type in the input message
schema, which determines what input instance data will be inserted
into the path component of the request URI. The curly
brace-enclosed name will be replaced with instance data in
constructing the path component. Remaining input instance data (not
specified by whttp:location
) will either be serialized
into the query string portion of the URI or into the message body,
as follows: if a "/" is appended to a curly brace-enclosed type
name, then any remaining input message instance data will be
serialized into the message body. Otherwise it will be serialized
into query parameters.
Thus, in this example, each of the elements in the
tCheckAvailability
type will be serialized into the
query parameters. A sample resulting URI would therefore be
http://greath.example.com/2004/checkAvailability/5-5-5?checkOutDate=6-6-5&roomType=foo
.
Here is an alternate example that appends "/" to the type name in order to serialize the remaining instance data into the message body:
Example 2-15. Serializing a Subset of Types in the Path
. . . <operation ref="tns:opCheckAvailability" whttp:location="bycheckInDate/{checkInDate/}" > . . .
This would instead serialize to a request URI such as:
http://greath.example.com/2004/checkAvailability/bycheckInDate/5-5-5
.
The rest of the message content would go to the HTTP message
body.
When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled URIs, Addressability, and the use of HTTP GET and POST ([W3C TAG Finding: Use of HTTP GET]). From the abstract:
". . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations."
Recall that the concept of a safe operation was discussed in
2.4.4.1 Operation
Attributes. (Briefly, a safe operation is one that
does not cause the invoker to incur new obligations.) Although the
wsdlx:safe
attribute of an interface operation
indicates that the abstract operation is safe, it does not
automatically cause GET to be used at the HTTP level when the
binding is specified. The choice of GET or POST is determined at
the binding level:
If the WSDL 2.0 SOAP binding extension is used (2.5.5 The SOAP Binding Extension), with HTTP as the underlying transport protocol, then GET may be specified by setting:
wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"
on the binding
element (to indicate the use of HTTP
as the underlying protocol); and
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"
on the binding operation
element, which causes GET
to be used by default.
If the WSD