2. WSDL 2.0 Basics
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 WSDL2.0 WSDL 2.0
features may be used.
2.1 Example Scenario: The GreatH
Hotel Reservation Service
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 room, and the type. The Web service will provide the return
a room rate (a floating point number
in USD$) if such a room is available. 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.
We know that we will later need to build a complete system that
supports transactions and secured transmission, but initially we
will implement only minimal functionality. In fact, to simplify our
first example, we will implement only the
CheckAvailability operation.
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/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns="http://www.w3.org/2005/05/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/2005/05/wsdl/soap"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<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.xsd"
xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
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/2004/03/wsdl/in-out" >
pattern="http://www.w3.org/2005/05/wsdl/in-out"
style="http://www.w3.org/2005/05/wsdl/style/uri"
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/2004/08/wsdl/soap12"
type="http://www.w3.org/2005/05/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"/>
<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>
2.2 Getting Started: Defining a WSDL
Target Namespace
Before writing our WSDL 2.0 document, we need to decide on a
WSDL target namespace URI for it. The WSDL target
namespace is analogous to an XML Schema target namespace:
interface, binding and service names that we define in our WSDL
document will be associated with the WSDL target namespace, and
thus will be distinguishable from similar names in a different WSDL
target namespace. (This will become important if using WSDL 2.0's
import or interface inheritance mechanisms.)
The value of the WSDL target namespace MUST be an absolute URI.
Furthermore, it SHOULD be dereferenceable to a WSDL document 2.0document that describes the Web service that
the WSDL target namespace is used to describe. For example, the
GreatH owners SHOULD make the WSDL document available from this
URI. (And if a WSDL description is split into multiple documents,
then the WSDL target namespace should resolve to a master document
that includes all the WSDL documents needed for that service
description.) However, there is no absolute requirement for this
URI to be dereferenceable; thus
dereferenceable, so a WSDL 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 document from anywhere --
not necessarily an authoritative source. But by dereferencing the
WSDL target namespace URI, a user SHOULD be able to obtain an
authoritative version. Since GreatH will be the owner of the
service, the WSDL 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 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/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
. . . >
. . .
</description>
2.2.1 Explanation of
Example
<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/2004/08/wsdl"
xmlns="http://www.w3.org/2005/05/wsdl"-
This is the XML namespace for WSDL 2.0 itself. Because we have
not defined a prefix for it, any unprefixed elements or attributes
are expected to be WSDL 2.0 elements or attributes (such as the
description element).
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
"http://greath.example.com/2004/wsdl/resSvc"-
This defines the WSDL 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.wsdl"
"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, QNames, to refer to the WSDL 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.
2.3 Defining
Message Types
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 deleted
text: requires all conformant
WSDL 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 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
deleted text: <table border="1" summary="Editorial note:
dbooth"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: dbooth </b>
</td> <td align="right" valign="top" width="50%">
</td> </tr> <tr> <td colspan="2"
align="left" valign="top"> Not sure the namespace declarations
and prefixes in this schema declaration are correct. In particular,
need to check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"
</td> </tr> </table>
<?xml version="1.0" encoding="utf-8" ?>
<description
xmlns="http://www.w3.org/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns="http://www.w3.org/2005/05/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.xsd"
xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
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>
2.3.1 Explanation of
Example
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
"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 document
itself.
targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
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 , 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.
2.4
Defining an Interface
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 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 Predefined Extensions Adjuncts ] section 2.2.3 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
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 pattern
s in 5.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
<a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
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
<a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
in-only
and <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">
out-only
patterns (see WSDL 2.0 Predefined Extensions [
WSDL 2.0 Predefined Extensions Adjuncts ] section 2.2.1 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">
In-Only
and section 2.2.5 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">
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 document.
Example 2-4. GreatH Interface Definition
<?xml version="1.0" encoding="utf-8" ?>
<description
xmlns="http://www.w3.org/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns="http://www.w3.org/2005/05/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.xsd"
xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
. . .
<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/2004/03/wsdl/in-out" >
pattern="http://www.w3.org/2005/05/wsdl/in-out"
style="http://www.w3.org/2005/05/wsdl/style/uri"
safe = "true">
<input messageLabel="In"
element="ghns:checkAvailability" />
<output messageLabel="Out"
element="ghns:checkAvailabilityResponse" />
<outfault ref="tns:invalidDataFault" messageLabel="Out"/>
</operation>
</interface>
. . .
</description>
2.4.1 Explanation of
Example
<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 (each one for use with a different
service). interface. Thus,
each interface must be given a name that is unique within the set
of interfaces defined in this WSDL 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/2004/03/wsdl/in-out"
> pattern="http://www.w3.org/2005/05/wsdl/in-out"-
This line specifies that this operation will use the
<a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
in-out
pattern as described above. WSDL 2.0 uses URIs to identify message
exchange patterns in order to ensure that they the
identifiers are uambiguously
identified, 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 processors will automatically recognize or
understand that pattern. As with any other extension, it can be
used among processors that do recognize and understand
it.)
style="http://www.w3.org/2005/05/wsdl/style/uri"-
This line indicates that the XML schema
defining the input message of this operation follows a set of rules
as specified in
URI Style that ensures the message can be serialized as an
URI.
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 5.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 general it may 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 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
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 Predefined Extensions Adjuncts ] section 2.2.3 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
In-Out
for the <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
in-out
pattern. However, in theory,
if a new patterns could be pattern
is defined that involve multiple input messages,
and then the different input messages in the pattern
would could
then be distinguished by having 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
<a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">
message-triggers-fault rule ; others use a <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">
fault-replaces-message rule. See WSDL 2.0 Predefined
Extensions [ WSDL 2.0 Predefined Extensions Adjuncts ] section 2.1.2 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">
Message Triggers Fault and section 2.1.1 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">
Fault Replaces Message .)
Now that we've defined the abstract interface for the GreatH
service, we're ready to define a binding for it.
deleted text: <table border="1" summary="Editorial note:
dbooth"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: dbooth </b>
</td> <td align="right" valign="top" width="50%">
</td> </tr> <tr> <td colspan="2"
align="left" valign="top"> [This note is only relevant to the
editors.] Hmm, I just realized that in the source XML for this
primer, in some cases we've been using <el> to indicate an
element name, and in other cases we've been using <code>. At
present, the xmlspec XSLT script seems to translate them both into
<code> elements in the generated HTML, but we should probably
make them consistent, in case that changes. </td> </tr>
</table>
2.5 Defining
a Binding
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, binding extension, for example, defines some
defaulting rules for operations. (See Web Services Description
Language (WSDL) Version 2.0 Part 3:
Bindings 2: Adjuncts [
<a href="#WSDL-PART3">
WSDL 2.0 Bindings Adjuncts ], section 2.3 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">
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 7.1
Extensibility for more on
extensibility.) WSDL 2.0 Part 3 2 [
WSDL 2.0
Adjuncts ] defines
binding constructs extensions for SOAP 1.2 [ <a href= "#SOAP12-PART1"> 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
constructs extensions that could also be used to define
bindings. (As with any extension, other WSDL 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/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns="http://www.w3.org/2005/05/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/2005/05/wsdl/soap"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
. . .
<types>
. . .
</types>
<interface name = "reservationInterface" >
<fault name = "invalidDataFault"
element = "ghns:invalidDataError"/>
<operation name="opCheckAvailability"
pattern="http://www.w3.org/2004/03/wsdl/in-out" >
. . .
</operation>
...
</interface>
<binding name="reservationSOAPBinding"
interface="tns:reservationInterface"
type="http://www.w3.org/2004/08/wsdl/soap12"
type="http://www.w3.org/2005/05/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"/>
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"/>
<fault ref="tns:invalidDataFault"
wsoap:code="soap:Sender"/>
</binding>
. . .
</description>
2.5.1 Explanation of
Example
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
"http://www.w3.org/2005/05/wsdl/soap"-
We've added two more namespace declarations. This one is the
namespace for the SOAP 1.2 binding construct 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 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 5. 6. 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 target namespace for this WSDL
document. In this case it may seem silly to have to specify the
tns: prefix, but in 7.3 Import mechanism and authoring
style we will see how WSDL 2.0's import mechanism can be
used to combine components that are defined in different WSDL
target namespaces.
type="http://www.w3.org/2004/08/wsdl/soap12"
type="http://www.w3.org/2005/05/wsdl/soap"-
This specifies the type
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 not defining a new operation.
Rather, 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
deleted text: <em> WSDL 2.0 Bindings </em> Part
2 [ <a
href="#WSDL-PART3"> WSDL 2.0
Bindings Adjuncts ] section 2.3 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">
4.3
Default Binding Rules </a>.) .)
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response">-
This attribute is also specific to WSDL 2.0's SOAP binding. binding
extension. It specifies the SOAP message exchange pattern
(MEP) that will be used to implement
the abstract WSDL 2.0 message exchange pattern ( <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
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 6.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, 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. binding
extension. This specifies the SOAP 1.2 fault code that will
cause this fault message to be sent. deleted text: </p>
<table border="1" summary="Editorial note"> <tr> <td
align="left" valign="top" width="50%"> <b> Editorial note
</b> </td> <td align="right" valign="top"
width="50%"> </td> </tr> <tr> <td
colspan="2" align="left" valign="top"> Need to verify that this
explanation is correct. See
http://lists.w3.org/Archives/Public/public-ws-desc-comments/2004Dec/0003.html
</td> </tr> </table> If desired,
an a
list of subcodes can also be specified using the optional
wsoap:subcodes attribute.
2.6 Defining
a Service
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 deleted text: in
order to indicate the binding details
that what protocols and transmission
formats are to be used at that endpoint. A service is only
permitted to have one interface. (However,
WSDL 2.0 does not prohibit one from declaring multiple services
that use different interfaces but happen to use the same endpoint
address. See <a
href="#adv-multiple-docs-describing-same-service">
(See 7.4 Multiple
Logical WSDL Documents Describing
Interfaces for the Same Service
</a>.) 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/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns="http://www.w3.org/2005/05/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/2005/05/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>
2.6.1 Explanation of
Example
<service
name="reservationService"-
This defines a name for this service, which must be unique among
service names in the WSDL target namespace. The name attribute is
required in order to facilitate the use
of required. It allows URIs to
indentify be
created that identify components in WSDL 2.0 documents. description. (See WSDL 2.0 Core Language
[ WSDL 2.0 Core Language ]
appendix C
URI References for WSDL 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.
2.7 Documenting the Service
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 documention
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 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
(as can be seen in the syntax summary
presented later), (see
3.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>
deleted text:
<types>
. . .
</types>
. . .
</description>
2.7.1 Explanation
of Example
<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.
deleted text: Let's summarize the syntax we've seen.
<div class="div2">
<h3>
<a name="basics-syntax"
id="basics-syntax"> 2.8 XML
Syntax Summary </h3> 3. WSDL
2.0 Infoset, Schema and Component Model
In the core computer science theory, a language specification, WSDL 2.0 constructs are defined as
consists of a (possibly infinite) set of abstract components, along with sentences, and each sentence is a mapping finite string of
literal symbols or characters. A language specification must
therefore define the set sentences in that language, and, to
an XML infoset representation for these
components. For easier consumption, be useful, it should also indicate the
primer uses meaning of each sentence. Indeed, this is the
XML representation purpose of deleted
text: WSDL components. The following
conventions are followed for the syntax: WSDL 2.0
specification.
deleted text: <ul> <li>
The syntax appears as an
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 instance, but
Infoset [ XML Information Set ]. Specifically, a WSDL 2.0 document consists of a description element
information item (in the values
indicate XML Infoset) that conforms
to the data types instead of
values. 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.
deleted text: </li> <li>
Characters are appended
Since an XML Infoset can be created from
more than one physical document, a WSDL 2.0 document does not
necessarily correspond to elements a single
physical document: the word "document" is used figuratively, for
convenience. Furthermore, since WSDL 2.0 provides
import and attributes as follows: "?" (0 include mechanisms,
a WSDL 2.0 document may reference other WSDL 2.0 documents to
facilitate convenient organization or 1), "*" (0 reuse. In such
cases, the meaning of the including or more), "+" (1 importing
document as a whole will depend (in part) on the meaning of the
included or more).
imported document.
deleted text: </li> <li>
Elements names ending in "..."
(such 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 <element…/> or <element…>) indicate
a shorthand. It should be understood,
however, that elements/attributes
irrelevant to since WSDL 2.0 is based
on the context are being
omitted. XML Infoset, we really mean
"element information item" and "attribute information item",
respectively.
</li> </ul> <table border="1"
summary="Editorial note: dbooth"> <tr> <td align="left"
valign="top" width="50%">
The following diagram gives an overview
of the above elipses (...), as they
weren't rendering properly at one point. </td> </tr>
</table> <div class="div3"> <h4>
XML Infoset for a WSDL 2.0
document.
<div class="div3">
<h4>
<a name="basics-syntax-longer" id=
"basics-syntax-longer"> 2.8.2 Longer Syntax
Summary </h4> <table border="1" summary="Editorial note:
dbooth"> 3.2 WSDL 2.0 Schema and
Element Ordering
The WSDL 2.0 specification supplies
a normative WSDL 2.0 schema ,defined in XML Schema [ XML Schema:
Structures ] [
XML Schema:
Datatypes ], which can be
used as an aid in validating WSDL 2.0 documents.
| Editorial note:
dbooth KevinL |
20050428 |
| To
do: Update this, and delete the <documentation>,
<feature> and <property> elements, because they're
mentioned below. ToDo: update link to
wsdl2.0 schema when final uri is available |
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
Language ] "
XML Representation of Description Component ") clearly states a set of constraints about how the
children elements of the description element
should be ordered. Thus, the order of the WSDL 2.0 elements
matters, in spite of what the WSDL 2.0 schema says.
The following is a pseudo-content model
of description
.
<description targetNamespace="<em>xs:anyURI</em>" >
<description>
<documentation />?
<import namespace="<em>xs:anyURI</em>" location="<em>xs:anyURI</em>"? >
<documentation />?
</import>*
<include location="<em>xs:anyURI</em>" >
<documentation />?
</include>*
<types>
<documentation />?
</types>
<interface name="<em>xs:NCName</em>" extends="<em>list of xs:QName</em>"? styleDefault="<em>list of xs:anyURI</em>"? >
<documentation />?
<fault name="<em>xs:NCName</em>" element="<em>xs:QName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</fault>*
<operation name="<em>xs:NCName</em>" pattern="<em>xs:anyURI</em>" style="<em>list of xs:anyURI</em>"? safe="<em>xs:boolean</em>"? >
<documentation />?
<input messageLabel="<em>xs:NCName</em>"? element="<em>union of xs:QName, xs:Token</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</input>*
<output messageLabel="<em>xs:NCName</em>"? element="<em>union of xs:QName, xs:Token</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</output>*
<infault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</infault>*
<outfault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</outfault>*
<feature ... />*
<property ... />*
</operation>*
<feature uri="<em>xs:anyURI</em>" required="<em>xs:boolean</em>"? >
<documentation />?
</feature>*
<property uri="<em>xs:anyURI</em>" required="<em>xs:boolean</em>"? >
<documentation />?
<value> <em>xs:anyType</em> </value>?
<constraint> <em>xs:QName</em> </constraint>?
</property>*
</interface>*
<binding name="<em>xs:NCName</em>" interface="<em>xs:QName</em>"? type="<em>xs:anyURI</em>" >
<documentation />?
<fault ref="<em>xs:QName</em>" >
<documentation />?
<feature ... />*
<property ... />*
</fault>*
<operation ref="<em>xs:QName</em>" >
<documentation />?
<input messageLabel="<em>xs:NCName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</input>*
<output messageLabel="<em>xs:NCName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</output>*
<feature ... />*
<property ... />*
</operation>*
<feature ... />*
<property ... />*
</binding>*
<service name="<em>xs:NCName</em>" interface="<em>xs:QName</em>" >
<documentation />?
<endpoint name="<em>xs:NCName</em>" binding="<em>xs:QName</em>" address="<em>xs:anyURI</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</endpoint>*
<feature ... />*
<property ... />*
</service>*
</description>
[ <import /> | <include /> ]*
<types />?
[ <interface /> | <binding /> | <service /> ]*
</description>
In addition, other words, the children elements of the
feature description and element should be
ordered as follows:
-
An optional property documentation comes
first, if present.
-
then comes zero or more elements
are allowed inside most WSDL elements. Also,
an from among the following, in any
order:
-
Zero or more include
-
Zero or more import
-
Zero or more extensions
-
An optional documentation types element is
allowed inside follows
-
Zero or more elements from among the
following, in any WSDL element
order:
-
interface
elements
-
binding elements
-
service elements
-
Zero or more extensions.
Note the term "extension" is used
above as a container for human
readable and/or machine processable documentation.
convenient way to refer to
namespace-qualified extension elements. The content namespace
name of <code> documentation
</code> is arbitrary characters and such extension elements ("mixed" content in XML Schema). must not be"http://www.w3.org/2005/05/wsdl".
deleted text: </div> </div> <div class="div1">
<h2> <a name="more-types" id="more-types"> </a>
3. More on Message Types </h2>
<a name="more-types-schema"
id="more-types-schema"> 3.1 Defining Messages
Using XML Schema 3.3 WSDL 2.0
Component Model
As we saw previously, The WSDL 2.0 provides a
<code> types </code> element for enclosing messages
definitions in Infoset model above
illustrates the required structure of a WSDL document. There are two ways to enclose messages
definitions within 2.0 document,
using the deleted text:
<code> types </code> element:
use <code> xs:import </code> mechanism provided
by XML Schema, or embed
Infoset. However, the schemas within <code> xs:schema </code>
elements. It's perfectly reasonable WSDL 2.0 language also imposes many semantic constraints
over and above structural conformance to use both ways this XML
Infoset. In order to precisely describe these constraints, and as
an aid in one WSDL. The following
is precisely defining the meaning of
each WSDL 2.0 document, the WSDL 2.0 specification defines a
summary component model as an
additional layer of abstraction
above the XML syntax for
Infoset. Constraints and meaning are defined
in terms of this component model, and the <code> types </code> element:
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 hiearchy.
<div class="exampleInner"> <pre>
<description> <<b>types</b>>
<documentation />? <xs:import
namespace="<em>xs:anyURI</em>" schemaLocation=
"<em>xs:anyURI</em>"?/>* <xs:schema
targetNamespace="<em>xs:anyURI</em>" />*
[<em>extension elements</em>]*
</<b>types</b>> </description>
</pre>
A In
general, the WSDL description MUST
NOT refer to 2.0 component model
parallels the structure of the required XML Schema 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 given namespace
unless an 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 xs:import
service and/or element information
item, so the Service component has an {endpoints} property whose
value is a set of Endpoint components corresponding to the
xs:schema endpoint statement
for element information item children
of that namespace
service element information item. (Whew!).
The WSDL 2.0 component model is
present. In other words, using
particularly helpful in defining the
meaning of xs:import import and/or and
xs:schema include .WSDL
2.0 include
constructs allows components from another WSDL 2.0 document having
the same targetNamespace to be merged in with the components of the
current WSDL 2.0 document, and is transitive (i.e., if the included document also
includes a necessary condition for
making XML Schema WSDL 2.0 document,
then those components available
to will also be merged, and so on).
WSDL 2.0 import
allows components from another WSDL 2.0
document having a different
targetNamespace to be merged in with comonents of the
current WSDL description.
2.0 document, and is not
transitive.
4. More on Message Types
Please note The WSDL 2.0 types element
provides a mechanism for enclosing message schemas in a WSDL 2.0
document. Because WSDL 2.0 directly supports schemas written in XML
Schema [ XML Schema: Structures ], we will focus here on the use of deleted text: type
system other than XML Schema is
indicated by the extension elements to define message types. Schemas written in
the above syntax. (See <em>
other type definition languages must be
defined using a WSDL 2.0 Core
Language </em> language
extension. For examples of other schema languages, see WSDL 2.0
Part 1 [ WSDL 2.0 Core
Language ] appendix
Appendix E <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-20040803/#other-schemalang">
" Examples
of Specifications of Extension Elements for Alternative Schema
Language Support </a>.) </p>
<div class="div3"> <h4> <a
name="more-types-schema-import" id=
"more-types-schema-import"> Support. (Non-Normative) 3.1.1 Importing XML Schema </h4> <p> Let's
examine the XML Schema <code> import </code> first.
Note the schema import mechanism described here is defined in XML
Schema Language with some additional restrictions. It is different
from the WSDL import/include as explained in <a href=
"#adv-import-and-authoring"> ".
| 7.3 Import mechanism and authoring style
Editorial note: dbooth
</a>. The schema components defined
in |
2005-04-13 |
| ToDo: Update the imported
schema are available for above
reference deleted text:
by QName. Note that only components defined
in the schema itself and components included by it via <code>
xs:include </code> are available to WSDL. Specifically, components that appendix E, as the schema
imports via <code> xs:import </code> are NOT
available WG decided to
WSDL. </p> move it to a separate document. |
| Editorial note:
dbooth |
2005-04-13 |
| ToDo: Check this. An issue
was recently raised about the
sections below on import and include
mechanisms for correctness. (Be sure to check the table also.)
I'm not being transitive.
sure I got them all right. |
A There are
two ways to indicate XML Schema message definitions using
the types element can
contain zero or more element. One way
is to embed schema definitions within import xs:schema s which
may have one or two attributes elements that are children of types , as follows:
</p> <ul> <li> <p> A REQUIRED
we have already seen. The other way is to
use namespace
xs:import attribute of type <em> xs:anyURI
</em>. directly under
types .It is perfectly reasonable to use both ways in one WSDL
document.
The A
WSDL namespace
description deleted text: attribute
defines the namespace of the element declarations imported from the
referenced schema. As mandated in Section 3 of the Part 1
specification, the referenced schema MUST contain an NOT refer
to XML Schema components that are
neither imported nor embedded into that WSDL
targetNamespace description .In
other words, the use of xs:import attribute
on its and/or
xs:schema deleted
text: element and the values of these
two attributes MUST be identical. It is deleted text: an error
to import a schema that does not have
an necessary condition for
making XML Schema target namespace.
Such schemas must first be included (using <code> xs:include
</code> ) in a schema that contains components available to a deleted text: <code> targetNamespace </code> attribute; on
its <code> xs:schema </code> element, which can then be
either imported or inlined in the WSDL document. Description
component.
deleted text: </li> <li>
An OPTIONAL The following XML syntax for the
schemaLocation types attribute element
illustrates the use of deleted
text: type <em> xs:anyURI
</em>. </p> <p> The schemaLocation xs:import deleted
text: attribute, if present, provides
a hint to the WSDL processor as to where the schema may be located.
It's optional since the WSDL may have better ways to locate the
schema files, for example, caching and cataloging technologies may provide better information
than this hint. xs:schema :
</li> </ul>
<description>
<types>
<documentation />?
<xs:import namespace="xs:anyURI" schemaLocation= "xs:anyURI"?/>*
<xs:schema targetNamespace="xs:anyURI" />*
[extension elements]*
</types>
</description>
<div class="div3"> <h4>
3.1.2
4.1 Embedding XML Schema </h4>
Embedding We have already seen an XML example of using
embedded schema definitions in
section 2.3 Defining Message Types ,so we will merely add a few additional points
here.
When XML Schema is embedded directly in a
WSDL 2.0 document, it uses the existing top-level
xs:schema element defined by XML Schema [
XML Schema: Structures
]. It comparable ] to simply cutting and
pasting an existing, stand-alone do
so, as though the schema to a
location inside had been copied and
pasted into the types element. deleted text: </p>
<p> The schema components defined in the embedded
schema are then available to WSDL for
reference by QName (see @@@@). Note that
only components defined WSDL 2.0 Part
1 [ WSDL
2.0 Core Language ]
"
QName Resolution ").
Although WSDL 2.0 provides a
wsdl:import mechanism (described in the next section), an embedded XML schema
itself may
also use XML Schema's native xs:import and deleted text: components
included by it via xs:include are available elements to WSDL.
Specifically, components that refer
to schemas either in separate files or embedded in the
schema imports via same WSDL 2.0 document. However, components embedded
using xs:import have
different visibility from those embedded using
xs:include
:xs:include d components are deleted
text: NOT available to
WSDL. </p> <p> Similarly,
WSDL for reference by QName, but
xs:import ed components defined in
an embedded are not.
4.2
Importing XML Schema
There are many cases where one would
prefer importing schema definitions
from separate schema files instead of embedding them directly under
the types
element. One reason is reusability of the
schemas. Although WSDL 2.0 provides a wsdl:import mechanism, type and element declarations embedded in a
WSDL 2.0 document are NOT automatically made available to
deleted text: a WSDL description that imported (using <code>
wsdl:import </code> ) the description that embeds the
schema (see section @@@@ for more details).
For this reason, it is recommended that XML importing document, even though other WSDL 2.0
components (such as Interfaces, Bindings, etc.) do become
available. Therefore, if you wish to share schema documents
deleted text: intended to be shared across several WSDL
descriptions 2.0 documents, they should instead be placed in
separate XML Schema documents and
imported into each WSDL 2.0 document
using xs:import , rather than
embedded inside a WSDL document. directly under types .
Inside an embedded XML schema, the
The xs:import
mechanism is not transitive. Only components
defined in the imported schema itself and components the schema includes via
xs:include elements MAY be used
to refer are available to
deleted text: other XML schemas embedded in the same containing
WSDL description, provided
document. Specifically, components
that an appropriate value is specified for
their the schema imports via
schemaLocation xs:import deleted
text: attributes. The semantics of
such elements are governed solely by
the XML Schema specification [ <cite> <a
href="#XMLSchemaP1"> XML Schema: Structures </a>
</cite> ]. NOT available to
WSDL.
<table border="1" summary="Editorial
note: KevinL">
| Editorial note:
KevinL dbooth |
20040517 2005-04-13 |
| Add Example - illustrate use of xs:import and xs:include
for embedded schema Clarification - what should be the "appropriate
value" for schemalocation, especially when its's xs:include?
Check this. An issue was recently raised
about import not being transitive. |
deleted text: A <code> types </code> element can contain
zero or more <code> schema </code> s which may have the
following attributes: </p> <ul> <li> <p> A
REQUIRED <code> targetNamespace </code> attribute of
type <em> xs:anyURI </em>. </p> <p> It
defines the XML Schema target namespace of the element declarations
embedded in its owner <code> xs:schema </code> . Note
that WSDL modifies the XML Schema definition of XML Schema
<code> xs:schema </code> to make the <code>
targetNamespace </code> attribute required. </p>
</li> <li> <p> Additional OPTIONAL attributes as
specified for the <code> xs:schema </code> element by
the XML Schema specification. </p> </li> <li>
<p> Zero or more child elements as specified for <code>
xs:schema </code> by the XML Schema specification. </p>
</li> </ul> <p> Here is an example of
importing a schema. 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 imported into the WSDL as
follows:
Example 3-1. 4-1. deleted
text: Importing Message Definitions
into WSDL 2.0 </i> </p> <div
class="exampleOuter"> <p style="text-align: left"
class="exampleHead"> <i> <span> Example
3-2. </span> of Importing Message Definitions
<?xml version="1.0" encoding="utf-8" ?>
<description
xmlns="http://www.w3.org/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
. . .
<types>
<documentation>
Messages definitions of the reservation Web service of GreatH hotel.
</documentation>
<xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
xmlns="http://www.w3.org/2005/05/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>
</div>
4.3
Summary of Import and Include Mechanisms
The following table summarizes the
similarities and differences between the wsdl: and
xs: include and
import mechanisms.
Table 4-1. Summary of Import and
Include Mechanisms
| Mechanism |
Imported/Included Document Type |
Meaning |
Transitive? |
| wsdl:import |
WSDL 2.0
document |
Merge Interface,
Binding and Service components from another WSDL 2.0 document that
has a DIFFERENT targetNamespace. (Schema type and element
declarations are NOT merged.) |
No |
| wsdl:include |
WSDL 2.0
document |
Merge Interface,
Binding and Service components from another WSDL 2.0 document that
has the SAME targetNamespace. (Schema type and element declarations
are NOT merged.) |
Yes |
| xs::import |
XML Schema
document |
Merge type and
element declarations from another XML Schema document that has a
DIFFERENT targetNamespace. |
No |
| xs:import |
XML Schema
document |
Merge type and
element declarations from another XML Schema document that has the
SAME targetNamespace. |
Yes |
More advanced topics on importing schemas
are discussed in 7.10
Importing Schemas
4. 5.
More on Interfaces
We previously mentioned that a WSDL 2.0 deleted text: <code> interface deleted text: </code> is basically a set of <code> operation </code> s.
operations. However, there are some
additional capabilities that we have not yet covered. First, let's
review the syntax for the
interface . element.
4.1
5.1 Interface Syntax
deleted text: <table border="1" summary="Editorial note:
dbooth"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: dbooth </b>
</td> <td align="right" valign="top" width="50%">
</td> </tr> <tr> <td colspan="2"
align="left" valign="top"> To do: Simplify this syntax summary.
</td> </tr> </table>
Below is the XML syntax summary of the interface
element: element, simplified by omitting optional
<documentation>
elements and <feature> and <property> extension elements:
<description targetNamespace="xs:anyURI" >
<interface name="<em>xs:NCName</em>" extends="<em>list of xs:QName</em>"? styleDefault="<em>list of xs:anyURI</em>"? >
<documentation />?
<fault name="<em>xs:NCName</em>" element="<em>xs:QName</em>"? >
<documentation />?
<feature ... />*
. . .
<interface name="xs:NCName"
extends="list of xs:QName"?
styleDefault="list of xs:anyURI"? >
<property ... />*
<fault name="xs:NCName"
element="xs:QName"? >
</fault>*
<operation name="<em>xs:NCName</em>" pattern="<em>xs:anyURI</em>" style="<em>list of xs:anyURI</em>"? safe="<em>xs:boolean</em>"? >
<documentation />?
<input messageLabel="<em>xs:NCName</em>"? element="<em>union of xs:QName, xs:Token</em>"? >
<documentation />?
<feature ... />*
<operation name="xs:NCName"
pattern="xs:anyURI"
style="list of xs:anyURI"?
safe="xs:boolean"? >
<property ... />*
<input messageLabel="xs:NCName"?
element="union of xs:QName, xs:Token"? >
</input>*
<output messageLabel="<em>xs:NCName</em>"? element="<em>union of xs:QName, xs:Token</em>"? >
<documentation />?
<feature ... />*
<property ... />*
<output messageLabel="xs:NCName"?
element="union of xs:QName, xs:Token"? >
</output>*
<infault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</infault>*
<outfault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? >
<documentation />?
<feature ... />*
<property ... />*
</outfault>*
<infault ref="xs:QName" messageLabel="xs:NCName"? > </infault>*
<feature ... />*
<outfault ref="xs:QName" messageLabel="xs:NCName"? > </outfault>*
deleted text:
<property ... />*
</operation>*
deleted text:
<feature uri="<em>xs:anyURI</em>" required="<em>xs:boolean</em>"? >
<documentation />?
</feature>*
<property uri="<em>xs:anyURI</em>" required="<em>xs:boolean</em>"? >
<documentation />?
<value> <em>xs:anyType</em> </value>?
<constraint> <em>xs:QName</em> </constraint>?
</property>*
</interface>*
. . .
</description >
</description>
deleted text: One WSDL <code> description </code> element
may contain zero or more <code> interface </code>
elements as its direct children. Zero <code> interface
</code> elements are permitted since a <code>
description </code> element may only contain binding and/or
endpoint definitions to be aggegrated into a master WSDL
description via import/include mechanisms. </p> <p>
Let's have a look at the attributes of <code> interface
</code> first. It has one required <code> name
</code> attribute. Within the same WSDL target namespace
(might be in different wsdl documents, see section @@@@), each
interface must have a unique name. The
interface element has two optional attributes:
deleted text: extends </code> and <code>
styleDefault . and extends will be explained in the next section. We will explain
what a <code> style </code> later. For now, keep in
mind that the optional . The
styleDefault attribute deleted text: of
<code> interface </code> can be used to define a
default value for the style attribute attributes of all <code> operation </code> s
operations under this deleted text: <code> interface </code> , if any of the operations do not specify
a value for its (see WSDL 2.0 Part 1
"
styleDefault attribute information
item "). The
style extends .
attribute is for inheritance, and is
explained next.
<div class="div3">
<h4>
4.1.1 5.2 Interface
Inheritance </h4>
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. defines directly. Two things about extending
interfaces deserve some attention.
First, recursive extension of
interfaces an inheritance loop (or
infinite recursion) is prohibited.
The prohibited: the interfaces
that a given interface extends MUST NOT themselves extend that
interface either directly or indirectly.
Second, there may be cases where, due to
an interface extending one or more other interfaces,
we must explain what happens when
operations from two different
interface may interfaces have deleted
text: a name collision. More
precisely, within the same namespace, target
namespace and operation name. There are two or more interface cases:
either the component models of the operations end up having are
the same name. In such cases, WSDL 2.0
requires that same, or they are
different. If the component models of
those Interface Operation components MUST be equivalent (Component
Equivalence is are the same (per the
component comparison algorithm defined in WSDL 2.0 Part 1 section
2.15 [ WSDL 2.0 Core
Language ] "
Equivalence
of Components. For 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, basically component equivalence basically means that the two operations deleted text: in
question have the same set of
attributes and descendents). If
descendents.) In the collisional operations are equivalent then they are
considered to collapse into a single operation. It is an
error second case, if
they two
operations have the same name in the same WSDL target
namespace but are not equivalent. In other
words, if two interfaces have name collisional operations,
equivalent, then those two interfaces cannot both form part of the
derivation chain of a derived interface unless those operations are
exactly the same. it is an
error. For the above reason, it is considered good
practic practice to ensure that all operations within the
same target namespace are named
uniquely whenever possible.
Furthermore, uniquely.
Finally, since faults, features
and properties can also be defined as children of the
interface element (as descrbed
later), described in the following
sections), the same name-collision deleted text: resolution rules apply to those constructs.
deleted text: <table border="1" summary="Editorial note:
KevinL"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: KevinL </b>
</td> <td align="right" valign="top" width="50%">
20040910 </td> </tr> <tr> <td colspan="2"
align="left" valign="top"> Add Example - illustrate use extends
attribute </td> </tr> </table>
Now let's have Let's say the GreatH hotel wants to maintain a
look at a
standard message log operation for all received messages. It wants
this operation to be reusable across the children whole reservation
system, so each service will send out, for potential use of
<code> interface </code> . An
<code> a logging service, the
content of 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 </code> which
can contain zero or more <code> fault
</code> , zero or more <code> operation </code> ,
zero or more be inherited by other
interfaces. Assuming a feature messageLog , and
zero or more 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 property reservationInterface . now contains two
operations: feature
opCheckAvailability and
property opLogMessage will
be examined in section @@@@. We will explain
Example 5-1. Interface Inheritance
<description ...>
...
<interface name = "messageLogInterface" >
<operation name="opLogMessage"
pattern="http://www.w3.org/2005/05/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/2005/05/wsdl/in-out"
style="http://www.w3.org/2005/05/wsdl/style/uri"
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
fault </code> and
interface ,beginning with operation </code> constructs in the following
sections. fault .
<div class="div3"> <h4>
4.1.2
Reusable 5.3 Interface Faults
</h4>
The fault element can
be is used to declare faults
that may occur during execution of operations of an interface.
Declaring <code> fault </code>
s They are declared directly
under interface </code> , and referencing these faults in referenced from operations where they
apply allow one apply, in order to easily
indicate 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 some is normally described
by an element declaration. However, WSDL treats faults
can occur in 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. Within a same namespace, all
faults attribute that must be
named uniquely. unique within the WSDL document's target namespace, and
permits it to be referenced from operation declarations. The
optional element attribute can be used to indicate
a schema for the content or
playload payload of the fault message. Its value should be
the QName of the XML schema
a global element declaration which defines defined in the fault
message. types
section. Please note when other type
systems are used to define the schema
for a fault message, additional attributes may need to be
defined via WSDL's attribute extension mechanism to allow
associating such a message definition
the schema to be associated with the
fault.
deleted text: <p> Here is an example of reusing faults.
</p> <table border="1" summary="Editorial note:
dbooth"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: dbooth </b>
</td> <td align="right" valign="top" width="50%">
</td> </tr> <tr> <td colspan="2"
align="left" valign="top"> To do: Update this example
</td> </tr> </table> <div
class="exampleOuter"> <p style="text-align: left"
class="exampleHead"> <a name= "example-faults"
id="example-faults"> </a> <i> <span> Example
4-1. </span> Declaring interface faults </i> </p>
<div class="exampleInner"> <pre> <description
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation> Description: The definition of the
reservation Web service of GreatH hotel. Author: Joe Somebody Date:
05/17/2004 </documentation> <types> <xs:import
namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
schemaLocation=
"http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types> < interface name = "reservation" >
<<b>fault</b> name = "invalidCreditCardFault"
element = "ghns:invalidCreditCardError"> <documentation>
falut declaration for invalid credit card information.
</documentation> <<b>/fault</b>>
<<b>fault</b> name = "invalidDataFault" element =
"ghns:invalidDataError"> <documentation> falut declaration
for invalid data. </documentation>
<<b>/fault</b>> </interface>
</description> </pre> </div>
<table border="1" summary="Editorial
note: KevinL"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: KevinL </b>
</td> <td align="right" valign="top" width="50%">
20040520 </td> </tr> <tr> <td colspan="2"
align="left" valign="top"> Need clarification - fault must be
named uniquely across interfaces? </td> </tr>
</table> </div> <div class="div3">
<h4>
4.1.3 5.4 Interface
Operations </h4>
deleted text: Now we are ready to take a close look at the
<code> operation </code> element. As
explained shown earlier, deleted
text: message types are defined in a
type system, and the sequencing and cardinality of the messages
involved in a particular interaction are governed by the
deleted text: message exchange pattern (MEP). The
operation element is the glue
that brings all the pieces together for used to indicate an abstract interaction. The service indicates its
participation in a MEP operation
supported by deleted text:
using the MEP
in its operations. Message placeholders defined in a MEP are
associated containing interface. It
associates message schemas with specific a message
types exchange
pattern (MEP), in operations.
order to abstractly describe a simple
interaction with a Web service.
5.4.1
Operation Attributes
WSDL 2.0 defines An operation has two required and two optional attributes for an <code> operation </code>
: attributes:
-
A required name attribute
</p> <p> Operation names attribute, as seen already, which must be unique
within deleted text: an interface. Beware that <code> operations
</code> are local to an <code> interface </code>
,so two <code> interface </code> elements sharing the
same WSDL target namespace but with different name MAY contain
<code> operations </code> which share the same name.
Thus, <code> operations </code> cannot be referenced by
QName since the <code> name </code> and WSDL target
namespace are not sufficient to uniquely identify an <code>
operation </code> . In order to uniquely identify an
<code> operation </code> , one must first
identify the <code> interface
</code> by QName and then identify the <code> operation
</code> within that <code> interface </code> by a
further QName. As explained in section @@@, this fact has compound
impact when an interface extends other interfaces. It is considered
good practice to name operations uniquely within same namespace
whenever possible. interface.
-
A required pattern attribute </p> <p> it identifies the MEP a given
<code> operation </code> uses. Its whose value must be an absolute URI. URI that identifies
the desired MEP for the operation .MEPs are
further explained in 5.4.3
Understanding Message Exchange Patterns (MEPs) .
-
An optional style attribute </p> <p> it's an whose value is a list of absolute URIs. Each URI identifying
the identifies a certain set
of rules that were used to construct
the message type definitions used by the followed in defining this operation
</code> . Note that the attribute MAY
not present, but .It is an
error if it a particular style is present, then indicated,
but the associated rules
implied by that value MUST be followed or it
is an error. For example, are not
followed. [ WSDL 2.0
Adjuncts ] defines a set of rules
for constructing so called styles,
including
-
RPC Style.The RPC style
deleted text: messages (See section@@@@). If this attribute is
set to
"http://www.w3.org/2004/03/wsdl/style/rpc", then all
selected when the rules defined style is assigned
the value http://www.w3.org/2005/05/wsdl/style/rpc. It places
restrictions for Remote Procedure
Call-types of interactions.
-
URI Style. The URI style is selected
when the RPC
style is assigned the value
http://www.w3.org/2005/05/wsdl/style/uri. 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/2005/05/wsdl/style/multipart. In http binding,
for Xform clients, an message must be followed. We will have a closer look at RPC
defined following the Multipart style
in section@@@. and serialized as "Multipart/form-data".
<table border="1" summary="Editorial
note: KevinL"> <tr> <td align="left" valign="top"
width="50%">
You can find more details of these WSDL
2.0 predefined styles. Section Editorial note:
KevinL 7.7 RPC Style
</td> <td align="right"
valign="top" width="50%"> 20040910 </td> </tr>
<tr> <td colspan="2" align="left" valign="top"> Add
Example and more text - illustrate use provides an example of using the RPC style </td> </tr> </table>
.[ WSDL 2.0
Adjuncts ] provides
examples for the URI style and Multipart style.
-
An optional safety attribute </p> <p> A whose value is a boolean indicating whether the
operation is asserted to be safe
"safe" (as defined in Section 3.5 of
the Web Architecture [ Web Architecture ]) for users of the
described service 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 (by setting the
safty safety to true true) if it
meets deleted text: all the criteria for a safe interaction defined
in Section 3.5 of the Web
Architecture. 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, operation; thus the operation MAY or MAY NOT be
safe.
5.4.2 Operation Message References
An operation references a
set of ordinary and fault messages it accepts or sends via zero or
more will also have
input </code> , ,
output </code> , ,
infault </code> ,
and ,and/or
outfault element. Which of
these constructs element children
that specify the ordinary and fault message types to
use is governed be used by deleted
text: the MEP in use. As we have seen
in section@@@@, an MEP defines a set of placeholder messages
that participate in operation. The MEP specified by the pattern
and assigns them unique names
within attribute determines
which of these elements should be included, since each MEP has
placeholders for the message types
involved in its pattern. The
<code> input </code> and <code> output
</code> element are used to associate
Since operations were already discussed
in 2.4
Defining an actual mesage type
with Interface
,this section will merely comment on
additional capabilities that message
placeholder in the MEP. Such association is done via two
attributes: <code> were not
previously explained.
5.4.2.1 The messageLabel </code> and <code> element </code>
. Attribute
The messageLabel attribute deleted text: is used to
identify the role this message plays in the MEP. Its value must
match the name of the deleted
text: MEP place holder message. Note
that the messageLabel
input and output elements is
optional: it is deleted
text: optional, since it's 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.
5.4.2.2 The element Attribute
The element attribute can
be of the input and
output elements is used to identify specify
the messages message content (aka
payload) schema (a/k/a payload
schema) when the content model is defined deleted text: in XML
Schema (see section @@@@ for using other type systems). The content model is a token with
one of XML Schema. As we have seen
already, it can specify the values
<em> #any </em>, <em> #none </em>, or
<em> #element </em>. A value QName of <em> #any
</em> indicates 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. A value of <em>
#none </em>
indicates there-
There is no message content. It means that content, i.e., the message payload deleted
text: will be empty. When the
value is set to a Qname, it indicates
that the message consists of a single element described by the
referenced global element declaration reference by Qname. In
addition, the direction implied by the <b> in </b> put,
and <b> out </b> put must also match the direction of
the placeholder message identified by <code> messageLabel
</code> . empty.
We have already talked about how to
associate a message type with a reusable interface
The fault element . We
have attribute is also
covered the fault generation rules a MEP may
use. Here under <code> operation </code> , the
<code> infault </code> and <code> outfault
</code> elements can be used to associate an interface
<code> fault </code> with a specific message in the MEP
used by an <code> operation </code> . Such
association optional. If it is
done via a few attributes: the now familiar
<code> messageLabel </code> attribute, the direction
implied by the <b> in </b> fault and <b> out
</b> fault, and a required <code> ref </code>
attrbiute which points to the Qname of an interface <code>
fault </code> . When <code> infault </code>
and/or <code> outfault </code> occur multiple times
within an <code> operation </code> , they define
alternative fault message. not
specified, then @@@@.
<table border="1" summary="Editorial
note: dbooth">
| Editorial note: dbooth note |
|
| To
do: Update this example. Also: which features should it
illustrate? ToDo: Say what happens if
the element attribute is not specified, after issue LC99 is
resolved. See
http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 |
<div class="exampleOuter"> <p
style="text-align: left" class="exampleHead">
<a name= "example-operations"
id="example-operations"> <i> <span>
Example 4-2. </span> Defining Interface Operations </i>
</p> <div class="exampleInner"> <pre>
<description targetNamespace=
"http://greath.example.com/2004/wsdl/resSvc.wsdl" xmlns:ghns =
"http://greath.example.com/2004/schemas/resSvc.xsd" xmlns =
"http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation> Description: The definition of the
reservation Web service of GreatH hotel. Author: Joe Somebody Date:
05/17/2004 </documentation> <types> <xs:import
namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
schemaLocation=
"http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types> < interface name = "reservation" > <fault
name = "invalidCreditCardFault" element =
"ghns:invalidCreditCardError"/> <fault name =
"invalidDataFault" element = "ghns:invalidDataError"/>
<<b>operation</b>
name="<em>checkAvailability</em>"
pattern="<em>http://www.w3.org/2004/03/wsdl/in-out</em>"
> <input messageLabel="<em>In</em>"
element="<em>ghns:checkAvailability</em>"/ >
<output messageLabel="<em>Out</em>"
element="<em>ghns:checkAvailabilityResponse</em>"/ >
<outfault ref="<em>invalidDataFault</em>"
messageLabel="<em>Out</em>"/>
</<b>operation</b>>
<<b>operation</b>
name="<em>makeReservation</em>"
pattern="<em>http://www.w3.org/2004/03/wsdl/in-out</em>"
> <input messageLabel="<em>In</em>"
element="<em>ghns:makeReservation</em>"/ >
<output messageLabel="<em>Out</em>"
element="<em>ghns:makeReservationResponse</em>"/ >
<outfault ref="<em>invalidDataFault</em>"
messageLabel="<em>Out</em>"/> <outfault
ref="<em>invalidCreditCardFault</em>"
messageLabel="<em>Out</em>"/>
</<b>operation</b>> </interface>
</description> </pre> </div> </div>
<p> Note that in the above example, the <em>
invalidDataFault </em> is re-used by both operations. In the
<em> makeReservation </em> operation, two alternative
outgoing faults are defined which means either a
invalidDataFault 5.4.2.3 Multiple
infault or a invalidCreditCardFault
may be returned as a replacement of the outgoing message.
</p> outfault
Elements
An <code> operation </code>
can also contain zero or more <code> feature </code>
and When property infault elements.
We defer the explanation for and/or feature outfault and
occur multiple times within an
property </code> to section
@@@@. operation
,they define alternative fault
messages.
<div class="div2"> <h3>
4.2 5.4.3 Understanding Message Exchange Patterns
</h3> (MEPs)
WSDL 2.0 message exchange patterns (MEPs) are used to
defines 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
specifies is
defined, which includes specifying which MEP to use. 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 deleted
text: like interfaces and
operations, WSDL 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 pattern. MEP. For
instance, even though a pattern
an MEP may define a single message
sent from a service to one other node, the
Web Service a service defined by that
MEP may multicast that message to other nodes. To maximize
reuse, WSDL 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 8 MEPs are defined in Part 2
of the [ WSDL 2.0 specification.
Adjuncts ]. Hopefully, these MEPs will 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. </p>
<table border="1" summary="Editorial note: dbooth">
<tr> <td align="left" valign="top" width="50%">
(See Editorial note: dbooth 5.4.4 Defining New Message Exchange Patterns
(MEPs) </td> <td
align="right" valign="top" width="50%"> </td>
</tr> <tr> <td colspan="2" align="left"
valign="top"> Add info about how to define a new MEP?
</td> </tr> </table> )
For the 8 MEPs defined by WSDL 2.0, some of them are variations
of others based on how faults may be generated. Three common fault generation models are specified.
</p> <dl> <dt class="label"> Fault Replaces
Message </dt> <dd> <p> Any message after the
first in For example, the
In-Only pattern MAY be replaced with a fault message, which MUST have
identical cardinality and direction. The fault message MUST be
delivered to the same target node as the ("http://www.w3.org/2005/05/wsdl/in-only") consists of
exactly one message it replaces.
</p> </dd> <dt class="label"> Message Triggers
Fault </dt> <dd> <p> Any message, including the
first, MAY trigger received by
a service from some other node. No
fault message in response. Each recipient
MAY generate maybe generated.
As a fault message, and MUST generate
no more than variation of In-Only,
Robust In-Only pattern
("http://www.w3.org/2005/05/wsdl/robust-in-only") also consists of
exactly one deleted text:
fault for each triggering message. Each
fault message has direction
received by a service, but in this case
faults can be triggered by the deleted text: reverse of
its triggering message. The fault message and MUST be delivered to the originator of the
message which triggered it.
message. If there is no path to this
node, the fault MUST be discarded. In
For details about the third case, no common fault may be
generated in generation models used
by the MEP. </p> </dd>
<dt class="label"> No Faults </dt> <dd> <p>
No faults will be delivered. 8 WSDL
2.0 MEPs, see [ WSDL 2.0 Adjuncts ].
deleted text: </dd> </dl>
deleted text: Now let's have a look of each of the 8 MEPs.
Depends on how the first message in the MEP is initiated,
deleted text: we can probably group the 8 WSDL MEPs may be
grouped into two groups:
in-bound MEPs in which case the service receives the first message
in the exchange, and out-bound MEPs in which case the service sends
out the first message in the exchange. Such (Such Grouping
is only for the purpose of easy reference deleted text: from
discussions in deleted text:
later sections of this primer. WSDL2.0 defines four in-bound MEPS: </p>
<ul> <li> <p> <b> In-Only </b>
("http://www.w3.org/2004/03/wsdl/in-only") primer).
This patten consists of exactly one
message received by A frequently
asked question about out-bound MEPs is how a service
from some other node. No fault maybe
generated. </p> </li> <li> <p> <b>
Robust In-Only </b>
("http://www.w3.org/2004/03/wsdl/robust-in-only") </p>
<p> This pattern can be considered as a variation
knows where to send the message. Services
using out-bound MEPs are typically part of In-only. It also consists large scale integration systems that rely on mapping and
routing facilities. In such systems, out-bound MEPs are useful for
abstractly specifying the functionality of deleted text: exactly
one message received by a service, but in this case faults including its requirements for potential customers,
while endpoint address information can be triggered provided at
deployment or runtime by integration
infrastructure. For example, the message as specified in the "Message Triggers Fault"
model. </p> </li> <li> <p> <b> In-Out
</b> ("http://www.w3.org/2004/03/wsdl/in-out") </p>
<p> This patten consists of exactly two message: a message
received by a service from some other node, followed by
GreatH hotel reservation system may require
that every time a message sent
customer interacts with the system to
check availability, data about the
other node. The second message may
customer must be replaced logged by
a fault as specified in CRM system. At design time, it's unknown which
particular CRM system would be used together with the
"Fault Replace Message" model. </p>
</li> <li> <p> <b> In-Optional-Out
</b> ("http://www.w3.org/2004/03/wsdl/in-opt-out") </p>
<p> reservation system. To
address this requirement, we may change the "reservationInterface"
in Example
2-1 to include an out-bound
logInquiry operation. This patten
consists of one or two messages: a message received by a
logInquiry operation advertises to
potential service from some other
node, optionally followed clients
that customer data will be made available by a message sent 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 other node from 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 service. Each
message same data may
trigger also
be used by a fault in response as
specified system performance analysis
tool for different purpose. Providing an out-bound operation
in the "Message Triggers Faults" model.
</p> </li> </ul> <p> WSDL2.0 also defines
four out-bound MEPs which sort of mirror reservation service enables loose coupling and so
improves the in-bound MEPs with
reserved direction: overall GreatH IT
landscape's flexibility and scalability.
<ul> <li> <p>
<b> Out-Only </b>
("http://www.w3.org/2004/03/wsdl/out-only") </p> <p>
This patten consists Example 5-2. Use of exactly one message
sent to some other node from a service. No fault maybe generated.
</p> </li> <li> <p> outbound MEPs deleted text: <b>
Robust Out-Only </b>
("http://www.w3.org/2004/03/wsdl/robust-out-only")
<description ...>
...
<interface name="reservationInterface">
...
<operation name="opCheckAvailability" ... >
<operation name="opLogInquiry"
pattern="http://www.w3.org/2005/05/wsdl/out-only">
<output messageLabel="Out" element="ghns:customerData" />
</operation>
</interface>
...
</description>
5.4.4
Defining New Message Exchange Patterns (MEPs)
This pattern can be considered as a
variation of Out-only. It also consists of exactly one message sent
to some other node from a service, but in this case faults can be
triggered by Although the
message as specified 8 MEPs defined in the
"Message Triggers Fault" model. </p> </li> <li>
<p> WSDL 2.0 Part 2 [
<b> Out-in </b>
("http://www.w3.org/2004/03/wsdl/out-in") </p> <p> This
patten consists of exactly two message: a message sent
WSDL 2.0
Adjuncts ] are intended to
cover most use cases, WSDL 2.0 has designed this set to
deleted text: some other node from a service, followed by a message
received by the service from the other node. The second message
may be replaced extensible. This is why MEPs are identified by
URIs rather than a fault as specified in fixed set of tokens. Here are the "Fault Replace Message" model. general steps for defining a new MEP.
</li>
-
<b> Out-Optional-In </b>
("http://www.w3.org/2004/03/wsdl/out-opt-in") </p> <p>
This patten consists of one or two messages: a message sent to some
other node from a service, optionally followed by a message
received by Search around on
the service from Web to see if somebody else has already defined an MEP
that is close enough to what you want. If others are already using
an MEP that fits your needs, it will reduce the other node. Each message may trigger a fault in response
as specified effort required
in the "Message Triggers Faults"
model. step 4 to get other people to
adopt yours.
- </ul>
-
While the in-bound MEPs are easier to
understand, there have been questions concerning
Write an HTML document that clearly
defines the usefulness of out-bound
MEPs, especially how MEP, and publish
it at a service can specify the
endpoint information stable URL --
see purl.org , for example
-- that will represent the target
node full, formal name of the
initial out-bound message. In their typical
use cases, MEP, such as
in large scale intergration projects where
endpoint information http://example.com/2005/ws/in-multi-out. (This is
most likely specified at deployment or
runtime by mapping and routing facilities, or/and in languages that
facilitate services composition where only abstract interfaces are
concerned, Out-bound MEPs are useful in the abstract level for
fully specifying the functionality a
fictitious example: "example.com" is a standard fictitious domain
name. You, of course, must use an
appropriate real domain and URL.)
-
Write and publish a service, including its requirements corresponding specification for deleted text: its
potential customers, so application integrator can gain a
deleted text: better understanding of how multiple services may be
used together, whereas binding extension that implements your MEP.
-
Publicize your new MEP and
endpoint information may be provided by
integration infrastructure in application deployment
binding extension, and runtime. get others to
support them in their WSDL toolkits.
<table border="1" summary="Editorial
note: KevinL"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: KevinL </b>
</td> <td align="right" valign="top" width="50%">
20040910 </td> </tr> <tr> <td colspan="2"
align="left" valign="top"> Add more use cases
Note that the above procedure does NOT
cause your MEP to become automatically recognized and
example - illustrate use of outbound meps?
</td> </tr> </table> usable by WSDL toolkits. It simply provides a
well-defined convention for naming and reusing them.
5. 6. More on
Bindings
A <code> binding </code> can
be defined for different levels of reusability. It can be
Bindings are used to describe binding information in a re-usable manner for
any interface or specifically for a given interface. Furthermore,
binding information MAY supply
protocol and encoding details that specify how messages are
to be specified on a per-operation
basis if needed. If a sent or
received. Each binding specifies any operation-specific binding details or any
fault binding details, then it MUST specify an interface the
element uses a particular binding
information applies to, so as
extension to indicate which interface the operations come
from.Conversely, a <code> specify such information. WSDL 2.0 Part 2 [
WSDL 2.0
Adjuncts ] defines
several binding </code>
extensions that omits any operation-specific binding details and any
fault are typically used.
However, binding details MAY omit
specifying an interface. <code> bindings </code>
extensions that do are not
specify an interface MAY defined in WSDL 2.0 Part 2 can also be
used to specify operation-independent
binding details for Service components with different interfaces.
That is, such <code> bindings </code> are reusable
across one or more interfaces. used,
provided that client and service toolkits support them.
A <code> Binding information must be supplied for every operation
in an interface that is used in an endpoint. However, if the
desired binding </code>
tied extension provides suitable
defaulting rules, then the information will only need to
a particular be explicitly supplied at the interface
MUST define bindings for all
level, and the deleted text: operations
of that interface. The bindings may occur via defaulting
rules which allow one will implicitly propagate the information to
specify default bindings for all
the operations (for of the interface.
For example, see the SOAP binding extension in deleted
text: <em> WSDL 2.0
Bindings </em> Part 2 [ <a href=
"#WSDL-PART3"> WSDL 2.0
Bindings Adjuncts ] section 2.3 <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">
4.3
Default Binding Rules .
) or by directly listing each operation of
the interface and defining bindings for them. Thus, it is an error
for a binding to not define bindings 6.1 Syntax Summary for all
the operations of the corresponding interface. </p>
Bindings
The binding constructs can be grouped
into two categories: those in Since
bindings are specified using extensions to the WSDL
namespace of
"http://www.w3.org/2004/08/wsdl" and those 2.0 language (i.e., binding extensions are not in
WSDL namespace. the WSDL 2.0 part 1
defines a set of binding constructs within namespace), the WSDL
namespace that can be used to host binding detail definitions.
Constructs XML for
defining expressing a binding details are defined within their own namespaces which
must be different will consist of a
mixture of elements and attributes from deleted text: the WSDL
namespace. ll these binding detail constructs are defined
outside WSDL namespace,
2.0 namespace and are typically used as extensions of from the deleted
text: hosting WSDL binding
constructs. In the following sections, we
will introduce the hosting extension's namespace, using WSDL binding constructs first, and then move on the the
binding extensions. 2.0's open
content model.
deleted text: <div class="div2"> <h3> <a
name="more-bindings-wsdl" id="more-bindings-wsdl"> </a>
5.1 Binding Constructs in WSDL Namespace </h3>
Let's have Here is a look at
syntax summary for binding ,simplified
by omitting optional documentation ,feature and
property elements. Bear in mind that this syntax summary only
shows the constructs
elements and attributes defined
within the WSDL 2.0 namespace. When an
actual binding is defined, elements and attributes from the
namespace deleted text:
first. The XML syntax of these constructs is summarized below:
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"? >
deleted text:
<documentation />?
<fault ref="<em>xs:QName</em>" >
<documentation />?
</fault>*
<fault ref="xs:QName" > </fault>*
<operation ref="xs:QName" >
<documentation />?
<input messageLabel="<em>xs:NCName</em>"? >
<documentation />?
</input>*
<output messageLabel="<em>xs:NCName</em>"? >
<documentation />?
</output>*
<feature ... />*
<property ... />*
<input messageLabel="xs:NCName"? > </input>*
<output messageLabel="xs:NCName"? > </output>*
</operation>*
deleted text:
<feature ... />*
<property ... />*
</binding>*
. . .
</description>
deleted text: <table border="1" summary="Editorial note:
KevinL"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: KevinL </b>
</td> <td align="right" valign="top" width="50%">
20040527 </td> </tr> <tr> <td colspan="2"
align="left" valign="top"> Need clarification - infault outfault
are missing from the binding operation syntax. Is it an oversight?
</td> </tr> </table> <table border="1"
summary="Editorial note: dbooth"> <tr> <td align="left"
valign="top" width="50%"> <b> Editorial note: dbooth
</b> </td> <td align="right" valign="top"
width="50%"> </td> </tr> <tr> <td
colspan="2" align="left" valign="top"> Trim some of this?
Redundant? </td> </tr> </table> <p> One
WSDL <code> description </code> element may contain
zero or more <code> binding </code> elements as its
direct children. </p>
The binding deleted
text: element has a required
<code> name </code> attribute. Within the same WSDL
target namespace , each binding must have a unique name. The
optional <code> interface </code> attribute refers, by
QName, to an <code> interface </code> . See the
previous section for how the <code> interface </code>
attribute can be used to achieve different levels of reusability of
the <code> binding </code> . </p> <p>
Careful readers may have already noticed that the <code>
binding </code> syntax is to
some extent symmetric with parallels the syntax of interface
</code> , in other
words, : each interface construct has a binding
counterpart. Simliar to <code>
interface </code> ,a <code> binding </code>
element can contain zero or more <code> fault </code> ,
zero or more <code> operation </code> , zero or more
<code> feature </code> , and zero or more <code>
property </code> . Be aware that despite of the syntax
Despite this syntactic similarity,
they are indeed different constructs
constructs, since they are in
different symbol spaces and are designed for different purpose. The <code> feature </code> and
<code> property </code> element will
purposes.
6.2 Reusable
Bindings
A binding can either be
examined in section @@@@. We will
explain 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.5 Defining a
Binding .
To define a reusable binding, the
fault binding and
element simply omits the
operation interface constructs attribute and
omits specifying any operation-specific and fault-specific binding
details. Endpoints can later refer to a reusable binding in
the following sections. 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.
<div class="div3">
<h4>
5.1.1 6.3 Binding Faults </h4>
A binding fault describes associates a concrete binding of message format
with an abstract fault within
of an interface to a particular concrete message format. More
precisely, it interface. It
describes how faults that occur within a message exchange of an
operation will be formatted
formatted, since the fault does not
occur by itself - it itself. Rather, a fault occurs as part of a
message exchange as defined
specified by an interface
operation and its binding counterpart counterpart, the binding operation
</code> . .
A binding fault has one required ref
attribute which is a reference, by Qname, 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 </code> .
.
<div class="div3"> <h4>
5.1.2 6.4 Binding Operations </h4>
A binding operation describes a concrete binding of
a particular operation of an interface to a particular concrete
message format.A format. A particular operation of an interface is
uniquely identified by the WSDL target namespace of the interface
and the name of the operation within that interface, via the
required ref attribute of binding operation
</code> . For
.As with faults, for each
operation within a binding </code> , , the value of
the ref attribute MUST
be unique. That is, one cannot define
multiple bindings
6.5 The SOAP
Binding Extension
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 same interface operation within a given
<code> WSDL 2.0 SOAP
binding </code> . </p> <table
border="1" summary="Editorial note: KevinL"> <tr> <td
align="left" valign="top" width="50%"> extension was already presented in Editorial note:
KevinL 2.5 Defining a
Binding </td> <td
align="right" valign="top" width="50%"> 20040527 </td>
</tr> <tr> <td colspan="2" align="left"
valign="top"> Need clarification - wording about QName
uniqueness in part 1 section 2.10.1 ,but some additional points are worth
mentioning:
-
Because the same binding extension is
used for both SOAP 1.2 and 2.11.1
need SOAP 1.1, a
wsoap:version
attribute is provided to change. it's not correct allow you to say "A
particular operation indicate which
version of an interface
SOAP you want. If this attribute is
uniquely identified by the
not specified, it defaults to SOAP
1.2.
-
The WSDL target namespace 2.0 SOAP
binding extension defines a set of default rules, so that bindings can be specified
at the interface and the name
of level or at the operation
within that interface" </td>
</tr> </table> <p> Corresponding to its interface
<code> level (or both), with
the operation </code>
counterpart, level taking precedence.
However, it does not define default binding <code> operation </code> may also have zero
or more <code> input </code> , <code> output
</code> , <code> infault </code> , and/or
<code> outfault </code> . The presence or absence of
these message and/or fault reference constructs within
rules for faults. Thus, if a
particular given interface defines any faults, then
corresponding binding <code>
operation </code> information
must be explicitly provided for each such fault.
-
If HTTP is governed by used as
the interface <code>
underlying protocol, then the binding can
(and should) control whether each operation </code> counterpart. </p> </div>
</div> <div class="div2"> <h3>
will use HTTP GET or POST. (See
<a
name="more-bindings-soap" id="more-bindings-soap">
6.7 HTTP GET Versus POST: Which to
Use? </a> 5.2 Extensions
for .)
Here is an example that illustrates both
a SOAP Binding </h3>
1.2 binding (as seen before) and a SOAP 1.1
binding.
Example 5-1. 6-1. SOAP binding
example placeholder - to be completed 1.2 and SOAP 1.1 Bindings
<?xml version="1.0" encoding="utf-8" ?>
<description
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/@@@@/wsdl/resSvc.wsdl"
xmlns:tns="http://greath.example.com/@@@@/wsdl/resSvc.wsdl"
xmlns:ghns="http://greath.example.com/@@@@/schemas/resSvc.xsd"
xmlns:wsoap="http://www.w3.org/2005/05/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/2005/05/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/2005/05/wsdl/soap"
wsoap:version="1.1"
wsoap:protocol="http://www.w3.org/2005/05/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>
6.5.1 Explanation of Example
Most of this example is the same as
previously explained in 2.5 Defining a
Binding ,so we'll only point
out lines that are demonstrating something new.
xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">-
This is the namespace for terms defined
within the SOAP 1.1 specification [ SOAP 1.1
].
wsoap:version="1.1"-
This line indicates that this binding
uses SOAP 1.1, rather than SOAP 1.2.
wsoap:protocol="http://www.w3.org/2005/05/soap11/bindings/HTTP">-
This line specifies that HTTP should be
used as the underlying transmission protocol. See also
6.7 HTTP GET
Versus POST: Which to Use? .
wsoap:code="soap11:Client"/>-
This line specifies the SOAP 1.1 fault
code that will be used in transmitting invalidDataFault.
5.3 Extensions for 6.6 The HTTP Binding Extension
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 5-2. 6-2. HTTP Binding example placeholder - to be completed
Extension
<description
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
. . .
type="http://www.w3.org/2005/05/wsdl/http"
xmlns:whttp="http://www.w3.org/2005/05/wsdl/http" >
. . .
<binding name="reservationHTTPBinding"
interface="tns:reservationInterface"
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/"/>
</service>
. . .
</description>
</div> </div> <div
class="div1"> <h2>
<a name="more-service"
id="more-service"> 6. More on Service
Endpoints </h2> 6.6.1
Explanation of Example
| Editorial note:
dbooth |
2005-04-15 |
| This section now seems largely redundant. Perhaps we
should reduce or eliminate it. ToDo:
Check this section. I'm not sure I got it all right, particularly
regarding whttp:location. Is the first sample request URI correct?
Shouldn't instance data for tCheckAvailability be in the path
component? What happens if a non-leaf element type is specified,
such as tCheckAvailability? |
type="http://www.w3.org/2005/05/wsdl/http"-
As described previously,
This declares the binding as being an HTTP binding.
service
xmlns:whttp="http://www.w3.org/2005/05/wsdl/http"
> construct-
This defines the namespace prefix for
elements and attributes defined by the WSDL 2.0 HTTP binding
extension.
whttp:methodDefault="GET">-
The default method for operations in this
interface will be HTTP GET.
whttp:location="{checkInDate}" >-
The whttp:location attribute specifies a set pattern for
serializing input message instance data into the path
component of alternate endpoints at
which a service the request URI. The
default binding rules for HTTP specify that the default input
serialization for GET is deleted
text: available. Zero or more
services </code> can be defined
within 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 description
whttp:location element. However, each service ) will either be serialized into the query string
portion of the URI or into the message body, as follows: if a
"/" is limited appended to a single
interface. The XML syntax 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
service tCheckAvailability type will be serialized into the query parameters. A
sample resulting URI for would therefore be
http://greath.example.com/2004/5-5-5?checkOutDate=6-6-5&roomType=foo
.
Here is summarized below: an
alternate example that serializes appends "/" to the type name in
order to serialize the remaining instance data into the message
body:
<div class="exampleInner"> <pre>
<description targetNamespace="<em>xs:anyURI</em>"
>
A <code> service </code>
has This would instead serialize
to a required <code> name
</code> attribute (also see section @@@@ for service
reference). Each request URI such
as: service http://greath.example.com/2004/bycheckInDate/5-5-5
within
6.7 HTTP GET Versus POST: Which to Use?
When a same
namespace binding using HTTP is
specified for an operation, the WSDL 2.0 author must
be named uniquely. A <code> service
</code> can only implement one single interface,
decide which HTTP method is appropriate to
use -- usually a choice between GET and it must specify POST.
In the single interface
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 implements via is
appropriate to use GET, versus when to use POST, in a finding
entitled URIs, Addressability,
and the <code> interface
</code> attribute. use of HTTP
GET and POST ([
W3C TAG
Finding: Use of HTTP GET ]). From the abstract:
A <code> service </code> may
contain one or more alternate <code> endpoints
</code> " . .
An <code> endpoint </code>
defines the particulars . designers
should adopt [GET] for safe operations such as simple queries. POST
is appropriate for other types of applications where a specific endpoint at which a given service is available.
</p> <p> An <code> endpoint </code>
user request has two required attributes: <code> name
</code> the potential to change
the state of the resource (or of related resources). The finding
explains how to choose between HTTP GET and <code> binding </code> . All <code>
endpoints </code> within POST
for an application taking into account architectural, security, and
practical considerations. "
Recall that the concept of a
safe operation was discussed in
5.4.1
Operation Attributes .(Briefly, a safe operation is one that does not cause
the invoker to incur new obligations.) Although the
service safe must
attribute of an interface operation
indicates that the abstract operation is safe, it does not
automatically cause GET to be named
uniquely via used at the
<code> name </code>
attribute. HTTP level when the
binding is specified. The required
<code> choice of GET or POST is
determined at the binding </code> attribute refers to, via Qname, a
<code> level:
-
If the WSDL 2.0 SOAP binding
extension is used ( 6.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"
definition. Note that if-
on the deleted text: refered binding specifies a particular interface, that interface MUST
be element (to indicate the
same use of
HTTP as the one implmented by
underlying protocol); and
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"-
on the parent binding
service operation .
element, which causes GET to be used by
default.
-
Like If the WSDL 2.0
HTTP binding deleted text:
constructs explained in section @@@@, the
WSDL <code> endpoint </code> construct is also like an
anchor for hosting extension elements
that are is used to provide information specific to a particular endpoint
in a server. directly (
6.6
The semantics of such extensions are
defined HTTP Binding
Extension ), GET may be
specified by the specification for
those extensions. Such specifications are expected to annotate the
WSDL setting either:
endpoint
whttp:methodDefault="GET"
construct with additional properties and
specify-
on the mapping between those properties and
binding element; or
whttp:method="GET"-
on the deleted text: XML
representation. For example, The SOAP and HTTP binding
deleted text: extensions defined in WSDL 2.0 part 3 also provides
extensions to be used under a service endpoint operation .
element, which overrides
whttp:methodDefault
if set on the binding element.
<a name="advanced"
id="advanced"> 7. Advanced Topics deleted text: -
TBD
deleted text: <table border="1" summary="Editorial note:
KevinL"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: KevinL </b>
</td> <td align="right" valign="top" width="50%">
20040526 </td> </tr> <tr> <td colspan="2"
align="left" valign="top"> This section is very incomplete, and
topics are still TBD. </td> </tr> </table>
7.1
Extensibility
WSDL 2.0 provides two extensibility mechanisms: an open content
model, which allows XML elements and attributes from other
(non-wsdl) (non-WSDL 2.0) XML namespaces to be interspersed
into in
a WSDL 2.0 document; and <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-20040803#Feature">
Features
and <a href=
"http://www.w3.org/TR/2004/WD-wsdl20-20040803#Property">
Properties
. Both mechanisms use URIs to identify the semantics of the
extensions. For extension XML elements and attributes, the
namespace URI of the extension element or attribute acts as an
unambiguous name for the semantics of that extension. For Features
and Properties, the Feature or Property is named by a URI.
In either case, the URI that identifies the semantics of an
extension SHOULD be dereferenceable to a document that describes
the semantics of that extension. As of this writing, there is no
generally accepted standard for what kind of document that should
be. However, the W3C TAG
has been discussing the issue (see TAG issue
namespaceDocument-8 ) and is likely to provide guidance at some
point.
7.1.1 Optional Versus Required
Extensions
Extensions can either be required or optional: optional.
An optional extension is one that the requester agent client may either engage or ignore, entirely at
its discretion, and is signaled by attribute
wsdl:required="false" ; whereas
a <em> required </em> extension is one that MUST be
supported and engaged by or
the requester agent in order for
absence of the interaction wsdl:required attribute (because it defaults to succeed properly, false).
Thus, a WSDL processor, acting on behalf of the client, that
encounters an unknown optional extension can safely ignore
it and continue to process the WSDL
2.0 document. However, it is signaled
by attribute <code> wsdl:required="true" </code>.
</p> <p> The optionality signaled by <code>
wsdl:required="false" </code> pertains important to stress that optional extensions are
only optional to the requester client deleted
text: agent -- not the
provider agent. The provider agent
service. A service MUST support
both all optional and required extensions that it
advertises in its WSDL 2.0
document.
A WSDL processor (acting
required extension is one that MUST be supported and engaged by
the client in order for the interaction to realize procede properly,
and is signaled by attribute wsdl:required="true" .If a requester agent) need
not support every conceivable required extension, but if it
sees WSDL processor, acting on behalf
of the client, encounters a required extension that it does
not recognize or does not support, then it MUST fault. cannot safely
continue to process the WSDL 2.0 document. In most practical cases,
this is likely to mean that the processor will require manual
intervention to deal with the extension. For example, a client
developer might manually provide an implementation for the required
extension to the WSDL processor.
7.1.2 Scoping of the
wsdl:required Attribute
<table border="1" summary="Editorial
note">
| Editorial note note:
dbooth |
2005-04-15 |
| To
do: ToDo: Need to check the
scoping rules to see if this is correct. |
As a convenience mechanism, the wsdl:required
attribute need not be specified on every extension element. If it
is omitted from an extension element, its effective value is
inherited from the smallest enclosing scope that explicitly sets
its value. If there is no enclosing scope that explicitly sets its
value, then its value defaults to false .
Because portions of a Web service description can be written in
different physical documents by different people, one should be
cautious about setting wsdl:required="false" when an
outer scope, written by someone else, had set
wsdl:required="true" .
7.2 Features and
Properties
[Add material from
http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0144.html
] After a few successful trials of
the reservation service, GreatH decides that it is time to make the
makeReservation operation secure, so that sensitive credit-card
information is not being sent across the public network in a
snoopable fashion. We will do this using the WSDL 2.0 Features and
Properties mechanisms [ WSDL 2.0 Core
Language ], which is
modeled after the Features and Properties mechanism defined in SOAP
1.2 [ SOAP 1.2 Part 1: Messaging Framework
].
To facilitate presentation, this section
will assume the existence of a hypothetical security feature named
" http://features.example.com/2005/securityFeature
", which defines, in the abstract, the idea
of message confidentiality. This feature has an associated
property, named " http://features.example.com/2005/securityFeature/securityLevel
", which defines various safety levels (from
0 meaning clear text, all the way through 10, involving highly
complex cryptographic algorithms with keys in the tens of thousands
of bits). We also assume that a SOAP module, named "
http://features.example.com/2005/modules/Security
", has been defined, which implements the
security feature described above.
GreatH has chosen an abstract security
feature which is standard in the fictitious hotels community, and
has integrated both a SOAP module and a new secure HTTP binding
into its infrastructure – both of which implement the security
feature (the SOAP module does this inside the SOAP envelope using
headers, and the secure binding does it at the transport layer).
Now they'd like to advertise and control the usage of these
extensions using WSDL 2.0.
7.2.1 SOAP
Modules
The first step GreatH takes is to require
the usage of the SOAP module in their normal SOAP/HTTP endpoint,
which looks like this:
Example 7-1. Requiring a SOAP Module in an Endpoint
. . .
<service name="reservationService"
interface="tns:reservationInterface">
<endpoint name="reservationEndpoint"
binding="tns:reservationSOAPBinding"
address ="http://greath.example.com/2004/reservation">
<wsoap:module uri="http://features.example.com/2005/modules/Security"
required="true"/>
</endpoint>
</service>
. . .
This syntax indicates that a SOAP Module
is required by this endpoint. This means that anyone using this
endpoint must both understand the specification that the module URI
references, and must use that specification when communicating with
the endpoint in question, which typically means including
appropriate SOAP headers on transmitted messages.
If the "required" attribute was not
present, or if it was set to " false ", then
the <wsoap:module> syntax would indicate optional the availability of the
referenced module, rather than a requirement to engage it, as
explained in 7.1.1
Optional Versus Required Extensions .
7.2.2
Abstract Features
Since GreatH began the web service
improvements, they have been talking to several travel agents. The
possibility of making their simple hotel interface an industry
standard amongst a consortium of hotels has come up, and as such
they would like to enable specifying the requirement for the
"makeReservation" operation to be secure at the interface level –
in other words indicating that the operation must be secure, but
without specifying exactly how that should concretely be achieved
(to enable maximal reuse of the interface). The next example uses
the WSDL 2.0 Feature element to indicate this.
Example 7-2. Declaring an Abstract Feature Requirement
. . .
<interface name="reservationInterface">
<operation name="makeReservation">
<feature uri="http://features.example.com/2005/securityFeature"
required="true"/>
. . . [The rest of the operation is unchanged] . . .
</operation>
</interface>
. . .
This declaration indicates that
understanding of, and compliance with, the specified security
feature is required for all uses of the "makeReservation"
operation. The security feature is abstract ,which means
that although it defines semantics and a level of detail about its
general operation, it expects a concrete component (like a SOAP
module or binding) to actually realize the
functionality.
By definition, if you understand a SOAP
module, you understand which (if any) abstract features it
implements. Therefore, since the security module in this example is
defined as an implementation of the abstract security feature, we
know that the use of this module satisfies the requirement to
implement the feature. Therefore users of the HTTP endpoint shown
above (with the required SOAP module) will be able to make use of
it. GreatH also defines a new endpoint:
Example 7-3. A SOAP
Binding Over a Secure HTTP Protocol
. . .
<binding name="reservationSecureSOAPBinding"
interface="tns:reservationInterface"
type="http://www.w3.org/2005/05/wsdl/soap"
wsoap:protocol="http://bindings.example.com/SOAPBindings/secureHTTP">
. ..
</binding>
. . .
<service name="reservationService">
. . .
<endpoint name="secureReservationEndpoint"
binding="tns:reservationSecureSOAPBinding"
address="https://greath.example.com/2004/secureReservation"/>
</service>
. . .
The user will have a choice as to which
of the endpoints, and therefore which binding, is to be used, but
they both satisfy the abstract feature requirement specified in the
interface.
Note that it is not necessary to declare
the abstract feature in order to use/require the SOAP module, or in
order to use/require the secure binding. Abstract feature
declarations serve purely to indicate requirements which must be
fulfilled by more concrete components such as modules or bindings.
In other words, the abstract feature declaration allows components
such as interfaces to be reused without caring exactly which SOAP
modules or bindings satisfy the feature.
7.2.3
Properties
So far we've discussed how to indicate
the availability or the "requiredness" of features and modules.
Often it is not enough to indicate that a particular extension is
available/required: you also need some way to control or
parameterize aspects of its behavior. This is achieved by the use
of WSDL 2.0 properties .Each
feature, SOAP module, or SOAP binding may express a variety
of properties
in its specification. These properties are
very much like variables in a programming language. If GreatH would
like to indicate that the securityLevel property should be 5 for
the "makeReservation" operation, it would look like
this:
Example
7-4. Defining a
Property
. . .
<interface name="reservationInterface">
<operation name="makeReservation">
<property
uri="http://features.example.com/2005/securityFeature/securityLevel">
<value>5</value>
</property>
. . . [rest of operation definition] . . .
</operation>
</interface>
. . .
The property element
specifies which property is to be set. By setting the
value element, a toolkit processing this WSDL 2.0 document is
informed that the securityLevel property must be set to 5. The
particular meanings of any such values are up to the
implementations of the modules/bindings that use them. The
property element can be placed at many different levels in a WSDL
2.0 document (see "Property Composition Model", section 2.8.1.1 in
WSDL 2.0 Part 1 [ WSDL 2.0 Core Language ]).
It is also possible to provide a
constraint on the value space for a given property. This allows the
author of the WSDL 2.0 document to indicate that several valid
values for the property are possible for a given scope, limiting
the value space already described in the specification that defined
the property. Let's extend our example to make this
clearer.
The security feature specification
defines securityLevel as an integer with values between 1 and 10,
each of which indicates, according to the spec, a progressively
higher level of security. The GreatH service authors, having read
the relevant specifications, have decided that any security level
between 3 and 7 will be supported by their infrastructure. Levels
less than 3 are deemed unsafe for GreatH's purposes, and levels
greater than 7 require too much in the way of resources to make it
worthwhile. We can express this in WSDL 2.0 as follows:
Example 7-5. Defining Property Constraints
. . .
<types>
<schema>
<simpleType name="securityLevelConstraint">
<restriction base="xs:int">
<min 3, max 7> <!-- check schema for syntax -->
</restriction>
</simpleType>
</schema>
</types>
. . .
<property uri="http://features.example.com/2005/securityFeature/securityLevel">
<constraint type="tns:securityLevelConstraint">
</property>
. . .
First we define, in the
types section, an XML Schema restriction type over integers
with minimum and maximum values, per our discussion above. Then
instead of using the value element
inside property
,we use constraint and
refer to the restriction type. This informs the implementation that
the property must have the appropriate values. This information
might be useful to a deployment user interface, for example, which
might allow an administrator to set this value with a slider when
deploying the service.
7.3 Import mechanism and authoring
style
[Discuss how In some circumstances you may want to split up a Web
service description into two or more documents. For example, if a
description is getting long or is being developed by several
authors, then it is convenient to divide it into several parts.
Another very important case is when you expect parts of the
description to be reused in several contexts. Clearly it is
undesirable to cut and paste sections of one document into another,
since that is error prone and leads to maintenance problems. More
importantly, you may need to reuse components that belong to a
wsdl:targetNamespace that is different than that of the document
you are writing, in which case the rules of WSDL
documents should 2.0 prevent you from simply cutting and pasting them
into your document.
To solve these problems, WSDL 2.0
provides two mechanisms for modularizing Web service description
documents: import
and include .This
section discusses the import mechanism and describes some typical
cases where it is be factored
used.
The import mechanism
lets you refer to allow
significant the definitions of Web
service components that belong
to other namespaces. To illustrate this,
consider the GreatH hotel reservation service. Suppose that the
reservation service uses a standard credit card validation service
that is provided by a financial services company. Furthermore,
suppose that companies in the financial services industry decided
that it would be reused.]
useful to report errors in credit card
validation using a common set of faults, and have defined these
faults in the following Web service description:
Example
7-6. Standard Credit Card
Validation Faults (credit-card-faults.wsdl)
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://finance.example.com/CreditCards/wsdl"
xmlns:tns="http://finance.example.com/CreditCards/wsdl"
xmlns:cc="http://finance.example.com/CreditCards/xsd">
<documentation>
This document describes standard faults for use
by Web services that process credit cards.
</documentation>
<types>
<xs:import xmlns:xs="http://www.w3.org/2001/XMLSchema"
namespace="http://finance.example.com/CreditCardFaults/xsd"
schemaLocation="credit-card-faults.xsd" />
</types>
<interface name="creditCardFaults">
<fault name="cancelledCreditCard" element="cc:CancelledCreditCard">
<documentation>Thrown when the credit card has been cancelled.</documentation>
</fault>
<fault name="expiredCreditCard" element="cc:ExpiredCreditCard">
<documentation>Thrown when the credit card has expired.</documentation>
</fault>
<fault name="invalidCreditCardNumber" element="cc:InvalidCreditCardNumber">
<documentation>Thrown when the credit card number is invalid.
This fault will occur if the wrong credit card type is specified.
</documentation>
</fault>
<fault name="invalidExpirationDate" element="cc:InvalidExpirationDate">
<documentation>Thrown when the expiration date is invalid.</documentation>
</fault>
</interface>
</description>
This example defines an interface,
creditCardFaults
,that contains four faults,
cancelledCreditCard
,expiredCreditCard
,invalidCreditCardNumber
,and invalidExpirationDate .These components belong to the namespace
http://finance.example.com/CreditCards/wsdl
.
Because these faults are defined in a
different wsdl:targetNamespace than the one used by the GreatH Web
service description, import must be used to make them available
within the GreatH Web service description, as shown in the
following example:
Example 7-7. Using
the Standard Credit Card Validation Faults
(use-credit-card-faults.wsdl)
<?xml version="1.0"?>
<description
targetNamespace="http://greath.example.com/2004/wsdl/resSvc"
xmlns:ghns="http://greath.example.com/2004/schemas/resSvc"
xmlns:cc="http://finance.example.com/CreditCards/wsdl"
xmlns="http://www.w3.org/2005/05/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
Description: The definition of the reservation Web service of
GreatH hotel. Author: Joe Somebody Date: 05/17/2004
</documentation>
<import namespace="http://finance.example.com/CreditCards/wsdl"
location="credit-card-faults.wsdl"/>
. . .
<interface name="reservation" extends="cc:creditCardFaults">
. . .
<operation name="makeReservation"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="ghns:makeReservation" />
<output messageLabel="Out"
element="ghns:makeReservationResponse" />
<outfault ref="invalidDataFault" messageLabel="Out" />
<outfault ref="cc:cancelledCreditCard" messageLabel="Out" />
<outfault ref="cc:expiredCreditCard" messageLabel="Out" />
<outfault ref="cc:invalidCreditCardNumber" messageLabel="Out" />
<outfault ref="cc:invalidExpirationDate" messageLabel="Out" />
</operation>
</interface>
</description>
The hotel reservation service declares
that it is using components from another namespace via the
import > element. The import element has a required
namespace attribute that specifies the other namespace, and an
optional location
attribute that gives the processor a hint
where to find the description of the other namespace. The
reservation interface extends the creditCardFault interface from the other namespace in order to make the
faults available in the reservation interface. Finally, the
makeReservation
operation refers to the standard faults in
its outfault
elements.
Another typical situation for using
imports is to define a standard interface that is to be implemented
by many services. For example, suppose the hotel industry decided
that it was useful to have a standard interface for making
reservations. This interface would belong to some industry
association namespace, e.g.
http://hotels.example.com/reservations/wsdl. Each hotel that
implemented the standard reservation service would define a service
in its own namespace, e.g.
http://greath.example.com/2004/wsdl/resSvc. The description of each
service would import the
http://hotels.example.com/reservations/wsdl namespace and refer to
the standard reservation interface in it.
7.4 Multiple
Logical WSDL Documents Describing
Interfaces for the Same Service
[Acknowledge Suppose a Web service wishes to expose two different
interfaces: a customer interface for its regular users, and a
management interface for its operator. A wsdl:service specifies
only one wsdl:interface, so to achieve the desired effect the
service provider would somehow need to indicate a relationship
between two services. How can a service provider indicate a
relationship between services? Potential strategies
include:
-
Declare both interfaces in the same
wsdl:description element. Although WSDL 2.0 does not ascribe any particular
significance to the fact that multiple logical two
wsdl:services are declared within the same wsdl:description, an
application or toolkit could interpret this to mean that they are
related in some way.
-
Declare both interfaces in the same
wsdl:targetNamespace. Again,
although WSDL documents might
try 2.0 does not ascribe any
particular significance to describe the fact that two
wsdl:services are declared within the same service. Explain why wsdl:targetNamespace, an application or toolkit could
interpret this to mean that they are related in some
might do way.
-
Add an extension to WSDL
2.0 that links together all
services that are related in this intentionally, why it might cause problems
way. WSDL 2.0's open content model permits
extension elements from other namespaces to appear in a WSDL 2.0
document.
-
Declare them in completely separate
WSDL documents, but use the same endpoint address for
some systems, both. I.e., declare a
wsdl:interface and explain
wsdl:service for the customer interface in
one WSDL document, and a wsdl:interface and wsdl:service for the
management interface in a different WSDL document, but use the same
endpoint address for both. (By "different WSDL document" we mean
that both documents are never included or imported into the same
WSDL 2.0 descriptions component.) Although this approach may work
in some circumstances, it means that the same endpoint address
would be used for two different purposes, which is apt to cause
confusion or ambiguity. Furthermore, it is contrary to the Web
architectural principle that different URIs should be used to identify different Web
resources. (See the Web Architecture [ Web
Architecture ] section
on URI collision .)
-
Use inheritance to combine the
customer interface and management interface into a single, larger wsdl:interface. Of course,
this reduces modularity and means that the
management interface becomes exposed to the customers, which
is not good.
Bear in mind that since the above
strategies step outside deleted
text: scope of the WSDL
language. See thread starting at
http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0045.html
] 2.0 language specifies (and are
therefore neither endorsed nor forbidden by the WSDL 2.0
specification) the WSDL 2.0 specification cannot define or
standardize their semantics.
The desire to express relationships
between services is also relevant to Web service versioning,
discussed next.
7.5
Versioning and Web Service Equivalency Versioning
A WSDL 2.0 document describes a set of
messages that a Web service may send and receive. In essence, it
describes a language for interacting with that service. However it
is possible for a Web service to exchange other messages beyond
those described in a particular WSDL 2.0 document. Often this
circumstance occurs following an evolution of the client and/or
service, and thus an evolution of the interaction
language.
How best to manage the evolution
(versioning) of Web based systems is, at the time of writing, the
subject of a wide ranging debate. However, there are three
activities within the W3C that are directly relevant to versioning
of Web services description:
While incomplete, these activities all
agree in one important respect: that versioning is difficult, but
you SHOULD anticipate and plan for change.
The draft finding on Versioning and
Extensibility details two key approaches to versioning:
7.5.1 Compatible Evolution
In compatible evolution ,designers are expected to limit changes to those that
are either backward or forward compatible, or both:
- Backward
compatible
-
The receiver behaves correctly if it
receives a message in an older version of the
interaction language.
- Forward
compatible
-
The receiver behaves correctly if it
receives a message in a newer version of the
interaction language.
Since Web services and their clients both
send and receive messages, these concepts can apply to both
parties. However, since WSDL 2.0 is service-centric, we will focus
on the case of service evolution.
There are three critical areas in which a
service described in WSDL 2.0 my evolve:
-
The service now also <a href=
"http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html">
http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html
supports additional binding. In compatible
evolution, this should be a safe addition, given that adding a new
binding should not impact any existing interactions using another
transport.
-
An interface supports new operations.
Again, in compatible evolution this is usually safe, given that
adding an additional operation to an abstract interface should not
impact any existing interactions.
-
The messages exchanged may include
additional data. How the messages themselves may change within a
description depends to a large extent upon the type system being
used to describe the message contents. RelaxNG [
RELAX
NG ] has good support for
describing vocabularies that ignore unknown XML, as does OWL/RDF.
XML Schema 1.0 has limited support for extending the description of
a message via the xs:any and
xs:anyAttribute
constructs. XML Schema 1.1 has been
chartered to provide "changes necessary to provide better support
for versioning of schemas", and it is anticipated that this will
include improved support for more "open content" and therefore
better support for compatible evolution of messages.
7.5.2 Big
Bang
The big
bang approach to versioning is
the simplest to currently represent in WSDL 2.0. In this approach,
any change to a WSDL 2.0 document implies a change to the
document's namespace, a change to the interface implies a new
interface namespace and a change to the message contents is
communicated using a new message namespace. This approach has
particular benefits where an agent may quickly tell if a service
has changed by simply comparing the namespace value.
7.5.3 Combined
Approaches
Per decision 2004-03-04
It is feasible to add combine the
results "compatible evolution" and "big bang" approaches in a
variety of different ways. For
example, the Versioning Task Force
also. namespace could be changed when
message descriptions are changed, but the namespace could stay the
same when new operations are added.
While the big bang approach is currently
the easiest to implement in WSDL 2.0, it can lead to a large number
of cloned interfaces that become difficult to manage, thus making
the compatible approach preferable to many for widely distributed
systems. In the end, the choice of a versioning strategy for Web
services described in WSDL 2.0 is left as an exercise to the
reader.
7.6 MTOM Support
This section shows how Features and
Properties can theSOAP Message
Transmission Optimization Mechanism (MTOM) [ SOAP MTOM
] may be used engaged in the WSDL
2.0 SOAP binding extension.
We will modify the CheckAvailability
operation of the GreatH Hotel Reservation Service ( Example 2-1
) to return not only the room rate, but
images of the room and the floorplan. This will involve modifying
the checkAvailabilityResponse data structure to include binary data
representing these two images, indicated by the
xs:base64Binary
data type. Here is an example:
Example
7-8. XML Schema with
Optimizable Elements
. . .
<xs:element name="checkAvailabilityResponse">
<xs:sequence>
<xs:element name="rate" type="xs:double"/>
<xs:element name="photo"
type="xmime:base64Binary"
xmime:expectedContentType="image/jpeg image/png" />
<xs:element name="floorplan"
xmime:expectedContentType="image/svg">
<xs:simpleContent>
<xs:restriction base="xs:base64Binary">
<xs:attribute ref="xmime:contentType"
fixed="image/svg" />
</xs:restriction>
</xs:simpleContent>
</xs:element>
</xs:sequence>
</xs:element>
. . .
Note the use of the
xmime:expectedContentType and xmime:contentType attributes to declare the expected media type of the
encoded data and to allow the client to indicate the
type at runtime, respectively. These
attributes are defined in Describing Media Content of Binary Data
in XML [ref].
A checkAvailabilityResponse message
conforming to this schema might look like this:
Example 7-9. Non-optimized SOAP Message with Embedded Binary
Data
<soap:Envelope
xmlns:soap='http://www.w3.org/2003/05/soap-envelope'
xmlns:xmime='http://www.w3.org/2005/05/xmlmime'>
<soap:Body>
<g:checkAvailabilityResponse
xmlns:g="http://greath.example.com/2004/schemas/resSvc">
<g:rate>129.95</g:rate>
<g:photo xmime:contentType='image/png'>/aWKKapGGyQ=</g:photo>
<g:floorplan xmime:contentType="image/svg">Faa7vROi2VQ=</g:floorplan>
</g:checkAvailabilityResponse>
</soap:Body>
</soap:Envelope>
While this (non-optimized) message
satisfies the schema definition, a service may choose to allow or
require that the binary data be sent in an optimized format using
the Message Transmission and Optimization Mechanism (MTOM).
The use of MTOM. @@
this feature by the WSDL 2.0 SOAP binding
extension is indicated as follows:
Example from GlenD:
http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0076.html
@@ 7-10. Specifying MTOM in a WSDL 2.0 Binding
. . .
<binding name="reservationSOAPBinding"
interface="tns:reservationInterface"
type="http://www.w3.org/2005/05/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">
<input name="checkAvailability" />
<output name="checkAvailabilityResponse">
<feature
uri="http://www.w3.org/2003/06/soap/features/http-optimization"
required="true" />
</output>
</operation>
. . .
</binding>
. . .
The HTTP Message Transmission
Optimization (MTOM) feature is engaged using the
feature element. Note that the attribute required=�?true�? on
the feature declaration indicates that the message must be encoded
using the HTTP Optimization feature. If the attribute were
required=�?false�? (or this attribute were absent), it would
indicate that the use of MTOM is optional for this service: the
service accepts either MTOM-encoded messages, or the embedded
base64Binary data directly in the Body, and the client is free to
send either form of message.
The example above shows MTOM enabled for
a specific message within an operation. Placing the feature
declaration as a child of operation would
require (or enable if required=�?false�?) MTOM support for all the
messages in that operation. Placing the feature declaration as a
child of binding
would require (or enable if
required=�?false�?) MTOM support for all the operations in that
interface.
<a name="adv-security"
id="adv-security"> 7.7 Security
Considerations RPC Style
</div> <div class="div2">
<h3>
Section <a
name="adv-RPCstyle" id="adv-RPCstyle"> 5.4.1 Operation Attributes 7.8 mentioned that the
(optional) style
attribute of an interface operation is used
to indicate that the operation conforms to a particular pre-defined
operation style, or set of constraints. Actually, if desired
the style
attribute can hold a list of URIs,
indicating that the operation simultaneously conforms to multiple
styles.
Operation styles are named using URIs, in
order to be unambiguous while still permitted new styles to be
defined without requiring updates to the WSDL 2.0 language. WSDL
2.0 Part 2 [ WSDL 2.0 Adjuncts ] defines three such operation styles; one of these is
the RPC Style (
RPC Style ).
The RPC
Style is designed to facilitate
programming language bindings to WSDL 2.0 constructs. It allows a
WSDL 2.0 interface operation to be easily mapped to a method or
function signature, such as a method signature in Java(TM) or C#.
RPC Style is restricted to operations
that use the In-Out or In-Only MEPs (see 5.4.3
Understanding Message Exchange Patterns (MEPs)
).
A WSDL 2.0 document makes use of the RPC
Style in an interface operation by first defining the operation in
conformance with all of the RPC Style rules, and
then setting that operation's
style attribute to include the URI that identifies the
RPC </h3> Style, thus asserting that the operation does indeed
conform to the RPC Style. These rules permit the input and output
message schemas to map conveniently to inputs and outputs of a
method signature. Roughly, input elements map to input parameters,
output elements map to output parameters, and elements that appear
both in the input and output message schemas map to input/output
parameters. WSDL 2.0 Part 2 section "
RPC Style " provides full details
of the mapping rules and requirements.
The RPC Style also permits the full
signature of the intended mapping to be indicated explicitly, using
the wrpc:signature attribute defined in WSDL 2.0 Part 2 section "
wrpc:signature Extension ". This is an (optional) extension to the WSDL 2.0
language whose value designates how input and output message schema
elements map to input and output parameters in the method
signature.
The example below illustrates how RPC
Style may be used to designate a signature. This example is a
modified version of the GreatH reservation service. In particular,
the interface
and types sections have
been modified to specify and conform to the RPC Style.
Example
7-11. Specifying RPC
Style
. . .
<types>
<xs:element name="checkAvailability">
<xs:complexType>
<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>
<xs:element name="checkAvailabilityResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="roomType" type="xs:string"/>
<xs:element name="rateType" type="xs:string"/>
<xs:element name="rate" type="xs:double"/>
</xs:sequence>
</xs:complexType>
</xs:element>
. . .
</types>
<interface name = "reservationInterface" >
<operation name="checkAvailability"
pattern="http://www.w3.org/2005/05/wsdl/in-out"
style="http://www.w3.org/2005/05/wsdl/style/rpc"
wrpc:signature=
"checkInDate #in checkOutDate #in roomType #inout rateType #out rate #return">
<input messageLabel="In"
element="tns:checkAvailability" />
<output messageLabel="Out"
element="tns:checkAvailabilityResponse" />
</operation>
. . .
</interface>
. . .
Note that the interface operation's name
" checkAvailability ", is the same as the localPart of the input element's
QName, " tns:checkAvailability ". This is one of the requirements of the RPC Style. The
name of the operation is used as the name of the method in a
language binding, subject to further mapping restrictions specific
to the target programming language. In this case, the name of the
method would be "checkAvailability".
The local children elements of the input
element and output element designate the parameters and the return
type for a method call. Note that the elements
checkInDate
,checkOutDate
are input parameters, however the
element roomType
is an in-out parameter, as it appears both
as a local element child of both input and output elements. This
indicates that the reservation system may change the room type
requested based on availability.
The reservation service also returns a
rate type for the reservation, such as "rack rate". The return
value for the method is designated as the "rate"
element.
Based on the value of the
wrpc:signature
attribute, the method signature would be
obtained following the order of the parameters. A sample mapping is
provided below for the Java(TM) language. This example was created
using JAX RPC 1.1 [ JAX RPC 1.1 ]
for mapping simple types to Java types and designated inout and
output parameters by using Holder classes.
Example 7-12. Sample Java(TM) Signature for RPC Style
public interface reservationInterface extends Remote{
double checkAvailability(java.util.calendar checkInDate,
java.util.calendar checkOutDate,
StringHolder roomType,
StringHolder rateType) throws RemoteException;
. . .
}
Programming languages may further specify
how faults are mapped to langauage constructs and their scopes,
such as Exceptions, but they are not specific to RPC
style.
7.9 7.8
Enabling Easy Message Dispatch
Suppose a WSDL 2.0 document has
two input-output operation
operations and uses the same input
message schema for both. When the service receives the input
message, how will the service know which operation is supposed to
be invoked? Although the data contained in a runtime message may be
sufficient to distinguish between the operations, this can be a
problem for WSDL 2.0 toolkits that
are looking only at the message schema, rather than the actual
messages. (For example, the toolkit may be operating at
designtime, design time, without access to the runtime
messages.) This is the problem of dispatch . How can a
WSDL 2.0 document be written to
ensure easy message dispatch? Strategies
include:
-
One technique is to
Use unique top-level elements
,i.e., ensure that the top-level
elements declared in the message schema schemas are
different for different operations. This is probably the most
general solution, since it is guaranteed to provide a way to
perform dispatch, without preventing toolkits from potentially
using other dispatch techniques.
-
Another technique is to define
Include a required feature extension that enables a particular
dispatching convention. This approach makes the dispatching
convention explicit, although it may not be supported by every WSDL
toolkit. However, as explained in
7.1.1 Optional Versus Required Extensions
,toolkits that do not natively support the
extension could seek manual input, thus permitting a client
developer to supply an appropriate module that implements the
necessary extension. This strategy has thus permits future WSDL
toolkits to support and process the extension automatically, while
also ensuring that the extension will be handled properly by
toolkits that are not yet able to process it
automatically.
To ensure that client and service
implementations can easily determine the interface operation under
which a received message was sent (even though not every client or
service may need to make such a determination), it is considered
good practice to follow one of the above strategies when authoring
WSDL 2.0 documents.
<a name="adv-get-vs-post"
id="adv-get-vs-post"> 7.10 GET
Versus POST: Which to Use? 7.9
Service and Endpoint References
[Add material Hyperlinking is one of the defining characteristics of
the Web. The ability to navigate from http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.html
one Web page to another is extremely useful.
It is therefore natural to apply this capability to Web services.
This section describes service
references and
endpoint references
,which are the Web service analogs of
document hyperlinks.
One may wonder, from a Web architectural
point of view, why anything more than a URI would be needed to
reference a Web service. Indeed, a service reference does make use
of a URI to indicate the endpoint address of a service. However, it
may also include additional metadata about that prescribes service, such
as the WSDL 2.0 interface and binding that the service
supports.
Service and endpoint references will be
illustrated by expanding the GreatH example already
discussed.
7.9.1 The
Reservation Details Web Service
When designing a Web application it is
natural to give each important concept a URI. In the GreatH hotel
reservation system, the important concepts are reservations, so we
begin our design by assigning a URI to each reservation. Since each
reservation has a unique confirmation number, e.g OMX736, we create
a URI for each reservation by appending the confirmation number to
a base URI, e.g. http://greath.example.com/2004/reservation/OMX736.
This URI will be the endpoint address for a Reservation Details Web
service that can retrieve and update the state of a
reservation. Example
7-13 shows the format of the
reservation detail.
Example 7-13. Detail for Reservation OMX736
<?xml version="1.0" encoding="UTF-8"?>
<reservationDetails
xmlns="http://greath.example.com/2004/schemas/reservationDetails">
<confirmationNumber>OMX736</confirmationNumber>
<checkInDate>2005-06-01</checkInDate>
<checkOutDate>2005-06-03</checkOutDate>
<roomType>single</roomType>
<smoking>false</smoking>
</reservationDetails>
The Reservation Details Web service
provides operations for retrieving and updating the detail for a
reservation. Example 7-14 shows the
description for this Web service. Note that there is no
wsdl:service
element in this description since the set of
reservations is dynamic. Instead, the endpoints for the
reservations will be returned by querying the Reservation List Web
service.
Example 7-14. The
Reservation Details Web Service Description:
reservationDetails.wsdl
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/2004/services/reservationDetails"
xmlns:tns="http://greath.example.com/2004/services/reservationDetails"
xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:wsoap="http://www.w3.org/2005/05/wsdl/soap"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
This document describes the GreatH Reservation Details Web
services. Use these services to retrieve or update reservation
details. Each reservation has its own service and endpoint. To
obtain the serice reference for a reservation, make a request to
the GreatH Reservation List Web service. See
reservationList.wsdl for a description of the Reservation List
Web service.
</documentation>
<types>
<xs:import
namespace="http://greath.example.com/2004/schemas/reservationDetails"
schemaLocation="reservationDetails.xsd" />
</types>
<interface name="reservationDetailsInterface">
<operation name="retrieve"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="#none" />
<output messageLabel="Out"
element="wdetails:reservationDetails" />
</operation>
<operation name="update"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In"
element="wdetails:reservationDetails" />
<output messageLabel="Out"
element="wdetails:reservationDetails" />
</operation>
</interface>
<binding name="reservationDetailsSOAPBinding"
interface="tns:reservationDetailsInterface"
type="http://www.w3.org/2005/05/wsdl/soap"
wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
<operation ref="tns:retrieve"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
<operation ref="tns:update"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
</binding>
</description>
Example
7-15 shows the XML schema
elements that are used in this Web service.
Example 7-15. The
Reservation Details Web Service XML Schema:
reservationDetails.xsd
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:tns="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:wdetails="http://greath.example.com/2004/services/reservationDetails"
xmlns:wsdl="http://www.w3.org/2005/05/wsdl"
xmlns:wsdli="http://www.w3.org/2005/05/wsdl-instance">
<import namespace="http://www.w3.org/2005/05/wsdl" />
<import namespace="http://www.w3.org/2005/05/wsdl-instance" />
<element name="confirmationNumber" type="string" />
<element name="checkInDate" type="date" />
<element name="checkOutDate" type="date" />
<element name="reservationDetails">
<complexType>
<sequence>
<element ref="tns:confirmationNumber" />
<element ref="tns:checkInDate" />
<element ref="tns:checkOutDate" />
<element name="roomType" type="string" />
<element name="smoking" type="boolean" />
</sequence>
</complexType>
</element>
<complexType name="ReservationDetailsSOAPEndpointType">
<complexContent>
<restriction base="wsdl:EndpointType">
<attribute name="binding" type="QName" use="required"
fixed="wdetails:reservationDetailsSOAPBinding" />
</restriction>
</complexContent>
</complexType>
<element name="reservationDetailsSOAPEndpoint"
type="tns:ReservationDetailsSOAPEndpointType">
<annotation>
<documentation>
This element contains a reference to the Reservation
Details Web Service SOAP Endpoint for this reservation.
</documentation>
</annotation>
</element>
<complexType name="ReservationDetailsServiceType">
<complexContent>
<restriction base="wsdl:ServiceType">
<sequence>
<sequence>
<element ref='wsdl:documentation' minOccurs='0'
maxOccurs='0' />
</sequence>
<choice minOccurs='1' maxOccurs='unbounded'>
<element ref='wsdl:endpoint' />
</choice>
</sequence>
<attribute name="interface" type="QName" use="required"
fixed="wdetails:reservationDetailsInterface" />
<attribute ref="wsdli:wsdlLocation" />
</restriction>
</complexContent>
</complexType>
<element name="reservationDetailsService"
type="tns:ReservationDetailsServiceType">
<annotation>
<documentation>
This element contains a reference to the Reservation
Details Web Service for this reservation.
</documentation>
</annotation>
</element>
</schema>
This XML schema contains the usual
definitions for the elements that appear in the messages of the Web
service. For example, the reservationDetails element is used in the messages of the retrieve and
update operations. In addition, the schema defines two
restrictions of WSDL complex types. The ReservationDetailsEndpointType
complex type restricts the
wsdl:EndpointType
complex type to have a
binding attribute whose value is the Reservation Details
binding, wdetails:reservationDetailsSOAPBinding
.The reservationDetailsSOAPEndpoint
element is thus a restriction of the
wsdl:endpoint
element that has the binding for the
Reservation Details service. This element will be used in the
Reservation List service.
The schema also defines the
ReservationDetailsServiceType complex type to restrict the wsdl:ServiceType to
have an interface
attribute whose value is the Reservation
Details service interace, wdetails:reservationDetailsInterface
.The reservationDetailsService element is thus a restriction of the
wsdl:service
element that has the interface for the
Reservation Details service. Note that the attributes of the
ReservationDetailsServiceType complex type have also been restricted to allow only the
additional wsdli:wsdlLocation attribute, which will be used in Example 7-19 to
specify the location of the WSDL 2.0 document that contains the
definition of the wdetails:reservationDetailsInterface
interface.
In general, when you want to describe
messages that contain endpoint references, you may use elements
that are based on the wsdl:EndpointType complex type. If the bindings of the endpoints are
fixed, you can define a restriction of the
wsdl:EndpointType
complex type that has a fixed value for
the binding
attribute. Similarly, when
you want to describe messages that contain
service references, you may use elements that are based on
the wsdl:ServiceType complex type. If the interfaces of the services are
fixed, you can define a restriction of the
wsdl:ServiceType
complex type that has a fixed value for
the interface
attribute. Note that the rules of XML Schema
do not allow wsdl:ServiceType to
be further restricted to have a fixed value for the
binding attribute of its nested wsdl:endpoint elements.
7.9.2 The Reservation List Web Service
Since the set of reservations changes as
reservations are made and cancelled, the Reservation Detail
endpoints are not described in a fixed WSDL document. Instead they
are returned as endpoint references in response to requests made on
a Reservation List Web service. The endpoint for the Reservation
List service will be
http://greath.example.com/2004/reservationList.
Example 7-16 shows the
format of the response from the Reservation List
service.
Example 7-16. Response from the Reservation List Web
Service
<?xml version="1.0" encoding="UTF-8"?>
<reservationList
xmlns="http://greath.example.com/2004/schemas/reservationList"
xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:wdetails="http://greath.example.com/2004/services/reservationDetails"
xmlns:wsdl="http://www.w3.org/2005/05/wsdl"
xmlns:wsdli="http://www.w3.org/2005/05/wsdl-instance"
wsdli:wsdlLocation="http://greath.example.com/2004/services/reservationDetails reservationDetails.wsdl">
<reservation>
<details:confirmationNumber>HSG635</details:confirmationNumber>
<details:checkInDate>2005-06-27</details:checkInDate>
<details:checkOutDate>2005-06-28</details:checkOutDate>
<details:reservationDetailsSOAPEndpoint
binding="wdetails:reservationDetailsSOAPBinding"
address="http://greath.example.com/2004/reservation/HSG635" />
</reservation>
<reservation>
<details:confirmationNumber>OMX736</details:confirmationNumber>
<details:checkInDate>2005-06-01</details:checkInDate>
<details:checkOutDate>2005-06-03</details:checkOutDate>
<details:reservationDetailsSOAPEndpoint
binding="wdetails:reservationDetailsSOAPBinding"
address="http://greath.example.com/2004/reservation/OMX736" />
</reservation>
<reservation>
<details:confirmationNumber>WUH663</details:confirmationNumber>
<details:checkInDate>2005-06-11</details:checkInDate>
<details:checkOutDate>2005-06-15</details:checkOutDate>
<details:reservationDetailsSOAPEndpoint
binding="wdetails:reservationDetailsSOAPBinding"
address="http://greath.example.com/2004/reservation/WUH663" />
</reservation>
</reservationList>
Here, the <details:reservationDetailsSOAPEndpoint>
elements contain endpoint references to the
Reservation Details Web services for the reservations HSG635,
OMX736, and WUH663. The endpoint references give the binding and
endpoint address of each service. In this example, all endpoints
have the same binding, i.e. wdetails:reservationDetailsSOAPBinding
. This QName identifies the WSDL 2.0 Binding
component that is defined in a WSDL 2.0 document. This example
shows the use of the wsdli:wsdlLocation attribute to locate the WSDL 2.0 document. The address
of each endpoint is the URI assigned to each
reservation.
Example
7-17 shows the description of the
Reservation List Web service. Note that it contains operations to
retrieve the entire list and to query for a list of reservations by
confirmation number, check-in date, and check-out date. In each
case, the operation returns a list of reservations.
Example
7-17. The Reservation List Web
Service Description: reservationList.wsdl
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/2004/services/reservationList"
xmlns:tns="http://greath.example.com/2004/services/reservationList"
xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:list="http://greath.example.com/2004/schemas/reservationList"
xmlns:wsoap="http://www.w3.org/2005/05/wsdl/soap"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
This document describes the GreatH Reservation List Web
services. Use this service to retrieve lists of reservations
based on a variety of search criteria.
</documentation>
<types>
<xs:import
namespace="http://greath.example.com/2004/schemas/reservationDetails"
schemaLocation="reservationDetails.xsd" />
<xs:import
namespace="http://greath.example.com/2004/schemas/reservationList"
schemaLocation="reservationList.xsd" />
</types>
<interface name="reservationListInterface">
<operation name="retrieve"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="#none" />
<output messageLabel="Out" element="list:reservationList" />
</operation>
<operation name="retrieveByConfirmationNumber"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In"
element="details:confirmationNumber" />
<output messageLabel="Out" element="list:reservationList" />
</operation>
<operation name="retrieveByCheckInDate"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="details:checkInDate" />
<output messageLabel="Out" element="list:reservationList" />
</operation>
<operation name="retrieveByCheckOutDate"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="details:checkOutDate" />
<output messageLabel="Out" element="list:reservationList" />
</operation>
</interface>
<binding name="reservationListSOAPBinding"
interface="tns:reservationListInterface"
type="http://www.w3.org/2005/05/wsdl/soap"
wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
<operation ref="tns:retrieve"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
<operation ref="tns:retrieveByConfirmationNumber"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
<operation ref="tns:retrieveByCheckInDate"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
<operation ref="tns:retrieveByCheckOutDate"
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
</binding>
<service name="reservationListService"
interface="tns:reservationListInterface">
<endpoint name="reservationListEndpoint"
binding="tns:reservationListSOAPBinding"
address="http://greath.example.com/2004/reservationList" />
</service>
</description>
Example
7-18 shows the schema for the
messages used in the Reservation List Web service.
Example
7-18. The Reservation List
Schema: reservationList.xsd
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://greath.example.com/2004/schemas/reservationList"
xmlns:tns="http://greath.example.com/2004/schemas/reservationList"
xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:wsdli="http://www.w3.org/2005/05/wsdl-instance">
<import namespace="http://www.w3.org/2005/05/wsdl-instance" />
<import
namespace="http://greath.example.com/2004/schemas/reservationDetails"
schemaLocation="reservationDetails.xsd" />
<element name="reservation">
<annotation>
<documentation>
A reservation contains the confirmation number, check-in
and check-out dates, and a reference to a Reservation
Details Web service.
</documentation>
</annotation>
<complexType>
<sequence>
<element ref="details:confirmationNumber" />
<element ref="details:checkInDate" />
<element ref="details:checkOutDate" />
<element ref="details:reservationDetailsSOAPEndpoint" />
</sequence>
</complexType>
</element>
<element name="reservationList">
<annotation>
<documentation>
A reservation list contains a sequence of zero or more
reservations.
</documentation>
</annotation>
<complexType>
<sequence>
<element ref="tns:reservation" minOccurs="0"
maxOccurs="unbounded">
</element>
</sequence>
<attribute ref="wsdli:wsdlLocation" />
</complexType>
</element>
</schema>
In the preceeding example, there was a
single endpoint associated with each Reservation Detail Web
service. Suppose GreatH hotel decided to provide a second, secure
endpoint. In this case, service references would be used to collect
together the endpoints for each reservation. The
reservationDetails.xsd schema defines the reservationDetailsService element for this purpose. It restricts the
wsdl:ServiceType
complex type to have a fixed value of
reservationDetailsInterface for the interface attribute.
Example 7-19 shows an
example of a message that contains a service reference for
reservation HGS635. Note that the service contains two endpoints,
one of which provides secure access to the Reservation Details Web service. Note the use
of the wsdli:wsdlLocation to provide the location for the WSDL 2.0 document that
defines the wdetails:reservationDetailsInterface
interface and the wdetails:reservationDetailsSOAPBinding
binding.
Example 7-19. A
Service Reference to the Reservation Details Web
Service
<?xml version="1.0" encoding="UTF-8"?>
<details:reservationDetailsService interface="wdetails:reservationDetailsInterface"
xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:wdetails="http://greath.example.com/2004/services/reservationDetails"
xmlns:wsdl="http://www.w3.org/2005/05/wsdl"
xmlns:wsdli="http://www.w3.org/2005/05/wsdl-instance"
wsdli:wsdlLocation="http://greath.example.com/2004/services/reservationDetails reservationDetails.wsdl">
<wsdl:endpoint
name="SOAP"
binding="wdetails:reservationDetailsSOAPBinding"
address="http://greath.example.com/2004/reservation/HSG635" />
<wsdl:endpoint
name="SECURE-SOAP"
binding="wdetails:reservationDetailsSOAPBinding"
address="https://greath.example.com/2004/reservation/HSG635" />
</details:reservationDetailsService>
7.9.3
Reservation Details Web Service Using HTTP Transfer
This section presents a variation on the
example in 7.9.1 The Reservation Details Web Service
.It illustrates the use of HTTP transfer
operations, GET versus POST
and PUT, to retrieve and update GreatH hotel
reservation details using the Representational State Transfer
(REST) architectural style described by Roy Fielding [
REST
]. REST is a distillation of the
architectural properties that Dr. Fielding identified as
well being
vital to the Web's robustness and enormous scalability.
Since each reservation in our example
will have a distinct URI, the Reservation Details Web service can
be offered using HTTP GET and HTTP PUT. The binding would be
modified as some useful
example] follows:
Example 7-20. Reservation Details Web Service Using HTTP
Transfer
. . .
<binding name="reservationDetailsHTTPBinding"
type="http://www.w3.org/2005/05/wsdl/http"
interface="tns:reservationDetailsInterface" >
<operation ref="tns:retrieve"
whttp:method="GET" />
<operation ref="tns:update"
whttp:method="PUT" />
</binding>
. . .
<div class="div2">
<h3>
As with the example in <a
name="adv-service-references" id=
"adv-service-references"> 7.9.1
The Reservation Details Web Service ,service and endpoint elements are not provided because
the Reservation List Web service provides the endpoints.
7.11
7.9.4 Reservation List Web Service
References </h3> Using HTTP GET
[Use
http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.html
This section continues the REST-style
example of 7.9.3
Reservation Details Web Service Using HTTP Transfer
by modifying the example of 7.9.2 The Reservation
List Web Service to use HTTP
GET.
The SOAP version of the Reservation List
Web service above offers four different search operations. These
can also be expressed as various
parameters in a starting point. Also
example(s) from Roberto per URI used
by HTTP GET:
Example 7-21. Reservation List Web Service Using HTTP
GET
. . .
<binding name="reservationListHTTPBinding"
type="http://www.w3.org/2005/05/wsdl/http"
interface="tns:reservationListInterface"
whttp:methodDefault="GET">
<operation ref="tns:retrieve"
whttp:location="" />
<operation ref="tns:retrieveByConfirmationNumber"
whttp:location="reservationList/ConfirmationNumber/{confirmationNumber/}" />
<operation ref="tns:retrieveByCheckInDate"
whttp:location="reservationList/CheckInDate/{checkInDate/}" />
<operation ref="tns:retrieveByCheckOutDate"
whttp:location="reservationList/CheckOutDate/{checkOutDate/}" />
</binding>
. . .
<service . . . >
<endpoint name="reservationListEndpoint"
binding="tns:reservationListHTTPBinding"
address="http://greath.example.com/2004/reservationList" />
. . .
</service>
. . .
A retrieval by Confirmation Number URI
would look like: http://greath.example.com/2004/reservationList/ConfirmationNumber/HSG635
.
Alternatively, a single query type may be
provided. This query type is a sequence of optional items. Any
items in the resolution at
sequence are serialized into the
end URI query
string. A query sequence for any of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html
] ConfirmationNumber, checkInDate,
checkOutDate would look like this:
Example 7-22. Query
Sequence Using a Single Query Type
<element name="reservationQuery">
<annotation>
<documentation>
A reservation contains the confirmation number, check-in
and check-out dates, and a reference to a Reservation
Details Web service.
</documentation>
</annotation>
<complexType>
<sequence>
<element ref="details:confirmationNumber" minOccurs="0"/>
<element ref="details:checkInDate" minOccurs="0"/>/>
<element ref="details:checkOutDate" minOccurs="0"/>/>
</sequence>
</sequence>
</complexType>
</element>
<div class="div2">
<h3>
The WSDL service that offers this type
serialized as a parameter would look like this:
<a name="adv-xml-schema-examples" id=
"adv-xml-schema-examples"> 7.12 XML Schema Examples </h3>
Example 7-23.
WSDL for Using a Single Query
Type
. . .
<interface name="reservationListInterfaceWithQuery">
<operation name="retrieveByReservationQuery"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In"
element="details:ReservationQuery" />
<output messageLabel="Out"
element="list:reservationList" />
</operation>
</interface>
<binding name="reservationListQueryHTTPBinding"
type="http://www.w3.org/2005/05/wsdl/http"
interface="tns:reservationListInterfaceWithQuery"
whttp:methodDefault="GET">
<operation ref="tns:retrieveByReservationQuery"
whttp:location="reservationList/{ReservationQuery}}" />
</binding>
. . .
<endpoint name="reservationListEndpoint"
binding="tns:reservationListHTTPBinding"
address="http://greath.example.com/2004/reservationList" />
. . .
[Add Paul Downey's contribution at
http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html
] Various URIs would be:
http://greath.example.com/2004/reservationList/ReservationQuery?confirmationNumber=HSG635
http://greath.example.com/2004/reservationList/ReservationQuery?checkInDate=06-06-05
.
It is important to observe that using the
URI serialization can result in very flexible queries and few
operations. The previous discrete SOAP operations are collapsed
into one "parameterized" operation.
7.13
Multiple In-Line 7.10
Importing Schemas
[Need WSDL
2.0 documents may contain one or more XML schemas defined within
the wsdl:types
element. This section illustrates the
correct way to explain
refer to these schemas, both from within the
same document and from other documents.
7.10.1 Schemas in Imported Documents
In this example, we consider some GreatH
Hotel Web services that retrieve and update reservation details.
The retrieval Web service is defined in the
retrieveDetails.wsdl
WSDL 2.0 document, along with a schema for
the message format. The updating Web service is defined in
the updateDetails.wsdl WSDL 2.0 document which imports the first document and
refers to both WSDL and schema definitions contained in the
imported document.
Example
7-24 shows the definition of the
retrieval Web service in the http://greath.example.com/2004/services/retrieveDetails
namespace. This WSDL 2.0 document also
contains an inline schema that describes the reservation detail in
the http://greath.example.com/2004/schemas/reservationDetails
namespace. This schema is visible to
the retrieveDetailsInterface interface definition which refers to it in the
retrieve operation's output message.
Example
7-24. The Retrieve Reservation
Details Web Service: retrieveDetails.wsdl
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/2004/services/retrieveDetails"
xmlns:tns="http://greath.example.com/2004/services/retrieveDetails"
xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
This document describes the GreatH Retrieve Reservation Details
Web service.
</documentation>
<types>
<xs:schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://greath.example.com/2004/schemas/reservationDetails">
<xs:element name="reservationDetails">
<xs:complexType>
<xs:sequence>
<xs:element name="confirmationNumber"
type="string" />
<xs:element name="checkInDate" type="date" />
<xs:element name="checkOutDate" type="date" />
<xs:element name="roomType" type="string" />
<xs:element name="smoking" type="boolean" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</types>
<interface name="retrieveDetailsInterface">
<operation name="retrieve"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="#none" />
<output messageLabel="Out"
element="wdetails:reservationDetails" />
</operation>
</interface>
</description>
Example
7-25 shows the definition of the
updating Web service in the http://greath.example.com/2004/services/updateDetails
namespace. The updateDetailsInterface interface extends the retrieveDetailsInterface interface. However, the retrieveDetailsInterface belongs to the http://greath.example.com/2004/services/retrieveDetails
namespace, so updateDetails.wsdl must import retrieveDetails.wsdl to make that namespace visible.
The updateDetailsInterface interface also uses the reservationDetails element definition that is
contained in the inline schema of the imported
retrieveDetails.wsdl
document. However, this can schema is not
automatically visible within the updateDetails.wsdl document. To make it visible, the
updateDetails.wsdl
document must import the namespace of the
inline schema within the types element using
the XML schema import element.
In this example, the
schemaLocation
attribute of the import element has
been omitted. The schemaLocation attribute is a hint to the WSDL processor that tells it
where to look for the imported schema namespace. However, the WSDL
processor has already processed the retrieveDetails.wsdl document which contains the imported namespace in an
inline schema so it should not need any hints. However, this
behavior depends on the implementation of the processor and so
cannot be done. See
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0126.html
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html
] relied on.
Although the WSDL 2.0 document may
validly omit the schemaLocation attribute, it is a best practice to either provide a
reliable value for it or move the inline schema into a separate
document, say reservationDetails.xsd ,and directly import it in the types element of
both retrieveDetails.wsdl and updateDetails.wsdl .In general, schemas that are expected to be referenced
from more than one WSDL 2.0 document should be defined in a
separate schema document rather than be inlined.
Example
7-25. The Update Reservation
Details Web Service: updateDetails.wsdl
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/2004/services/updateDetails"
xmlns:tns="http://greath.example.com/2004/services/updateetails"
xmlns:retrieve="http://greath.example.com/2004/services/retrieveDetails"
xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
This document describes the GreatH Update Reservation Details
Web service.
</documentation>
<import
namespace="http://greath.example.com/2004/services/retrieveDetails"
location="retrieveDetails.wsdl" />
<types>
<xs:import
namespace="http://greath.example.com/2004/schemas/reservationDetails" />
</types>
<interface name="updateDetailsInterface"
extends="retrieve:retrieveDetailsInterface">
<operation name="update"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In"
element="details:reservationDetails" />
<output messageLabel="Out"
element="details:reservationDetails" />
</operation>
</interface>
</description>
<div class="div2">
<h3>
<a name="adv-schema-location"
id="adv-schema-location"> 7.14 7.10.2 Multiple Inline Schemas in One
Document
A WSDL 2.0 document may define multiple
inline schemas in its types element. The
two or more schemas may have the same target namespace provided
that they do not define the same elements or types. It is an error
to define the same element or type more than once, even if the
definitions are identical.
Each namespace of an inline schema
becomes visible to the Web service definitions. However, the
namespaces are not automatically visible to the other inline
schemas. Each inline schema must explictly import any other
namespace it references. The schemaLocation attribute is not required in this case since the WSDL
processor knows the location of each schema by virtue of having
processed the enclosing WSDL document.
To illustrate this, consider
Example
7-26 which contains two inline
schemas. The http://greath.example.com/2004/schemas/reservationItems
namespace contains some elements for items
that appear in the reservation details. The
http://greath.example.com/2004/schemas/reservationDetails
namespace contains the
reservationDetails
element which refers to the item elements.
The schema for the http://greath.example.com/2004/schemas/reservationDetails
namespace contains an
import element that imports the http://greath.example.com/2004/schemas/reservationItems
namespace. No schemaLocation attribute is required for this import since the schema
is defined inline in the importing document.
Example
7-26. Multiple Inline Schemas:
retrieveItems.wsdl
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/2004/services/retrieveDetails"
xmlns:tns="http://greath.example.com/2004/services/retrieveDetails"
xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
This document describes the GreatH Retrieve Reservation Details
Web service.
</documentation>
<types>
<xs:schema targetNamespace="http://greath.example.com/2004/schemas/reservationItems">
<xs:element name="confirmationNumber" type="string" />
<xs:element name="checkInDate" type="date" />
<xs:element name="checkOutDate" type="date" />
<xs:element name="roomType" type="string" />
<xs:element name="smoking" type="boolean" />
</xs:schema>
<xs:schema targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:items="http://greath.example.com/2004/schemas/reservationItems">
<xs:import
namespace="http://greath.example.com/2004/schemas/reservationItems" />
<xs:element name="reservationDetails">
<xs:complexType>
<xs:sequence>
<xs:element ref="items:confirmationNumber" />
<xs:element ref="items:checkInDate" />
<xs:element ref="items:checkOutDate" />
<xs:element ref="items:roomType" />
<xs:element ref="items:smoking" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</types>
<interface name="retrieveDetailsInterface">
<operation name="retrieve"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="#none" />
<output messageLabel="Out"
element="wdetails:reservationDetails" />
</operation>
</interface>
</description>
7.10.3 The
schemaLocation Attribute </h3>
[ACTION: 2003-11-13: David
In the preceding examples, schemas were
defined inline in WSDL 2.0 documents. This section discusses the
correct way to add discussion /
example(s) re: @schemaLocation specify a schemaLocation attribute on a schema import element to
provide a processor with a hint for embedded locating these
schemas.
Example
7-25 shows how one WSDL 2.0
document imports a schema defined in another, i.e. Example
7-24 .Similarly, Example
7-26 shows how one schema in a
WSDL 2.0 document imports another schema defined in the same
document. In both of these examples, the schemaLocation attribute was omitted since the WSDL processor was
assumed to know how to locate the imported schemas
because they were part of the WSDL documents
being processed. The schemaLocation attribute can be used to give the primer. See
discussion in
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0135.html
processor a URI reference that explicitly
locates the schemas. A URI reference is a URI plus an optional
fragment identifier that indicates part of the resource. For
schemas, the fragment should identify the schema element. The
simplest way to accomplish this is to use the
id attribute, however XPointer can also be used.
7.10.3.1 Using the id Attribute to Identify Inline
Schemas
Example
7-27 shows the use of the
id attribute. Both of the inline schemas have
id attributes. The id of the http://greath.example.com/2004/schemas/reservationItems
schema is items and thread
called "Schemas the id of the
http://greath.example.com/2004/schemas/reservationDetails
schema is details .The
import element in imported
WSDL" the http://greath.example.com/2004/schemas/reservationDetails
schema uses the id of the
http://greath.example.com/2004/schemas/reservationItems
schema in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/thread.html
] the schemaLocation attribute, i.e. #items .
Example 7-27. Using
Ids in Inline Schemas: schemaIds.wsdl
<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2005/05/wsdl"
targetNamespace="http://greath.example.com/2004/services/retrieveDetails"
xmlns:tns="http://greath.example.com/2004/services/retrieveDetails"
xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<documentation>
This document describes the GreatH Retrieve Reservation Details
Web service.
</documentation>
<types>
<xs:schema id="items"
targetNamespace="http://greath.example.com/2004/schemas/reservationItems">
<xs:element name="confirmationNumber" type="string" />
<xs:element name="checkInDate" type="date" />
<xs:element name="checkOutDate" type="date" />
<xs:element name="roomType" type="string" />
<xs:element name="smoking" type="boolean" />
</xs:schema>
<xs:schema id="details"
targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
xmlns:items="http://greath.example.com/2004/schemas/reservationItems">
<xs:import
namespace="http://greath.example.com/2004/schemas/reservationItems"
schemaLocation="#items" />
<xs:element name="reservationDetails">
<xs:complexType>
<xs:sequence>
<xs:element ref="items:confirmationNumber" />
<xs:element ref="items:checkInDate" />
<xs:element ref="items:checkOutDate" />
<xs:element ref="items:roomType" />
<xs:element ref="items:smoking" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</types>
<interface name="retrieveDetailsInterface">
<operation name="retrieve"
pattern="http://www.w3.org/2005/05/wsdl/in-out">
<input messageLabel="In" element="#none" />
<output messageLabel="Out"
element="wdetails:reservationDetails" />
</operation>
</interface>
</description>
7.15 7.11 Mapping to RDF and Semantic Web
| Editorial note: KevinL |
20050429 |
| This section might be removed - pending on the
availability of the RDF mapping note. |
WSDL 2.0 is a language designed primarily
with XML syntax. While XML is almost universally understood, it has
several issues:
-
The ability to compose two XML documents
into one depends on the languages of those documents. WSDL 2.0 does
not permit Web service descriptions in different targetNamespaces
to be merged into a single (physical) XML document.
-
The ability to extend XML languages with
other XML languages depends on the languages again. WSDL 2.0 is
extremely extensible, but the meaning of every single extension in
WSDL must be defined explicitly. Putting a piece of XMI (XML format
for UML) into a WSDL 2.0 document may have different meaning from
putting it into an XHTML document. Therefore XML-based
extensibility has very high cost if many languages are
involved.
-
Similarly, extending another XML language
with pieces of WSDL 2.0, while possible, has to be defined for all
the possible destinations. Putting a WSDL 2.0 interface element
into a UDDI registry may mean a different thing from putting that
interface element into an XHTML document.
-
Finally, the meaning of a portion of a
WSDL 2.0 document is not defined by the WSDL 2.0 specification.
While an interface element could form a single XML document, it is
not a WSDL 2.0 document, so its meaning is largely
undefined.
Applications that require such levels of
composability (or decomposability) are increasingly being based on
RDF [ RDF ], a
graph-based knowledge representation language, and Web Ontology
Language (OWL) [ OWL ], which
can be thought of as an advanced schema language for RDF.
Effectively, a WSDL 2.0 document represented in RDF can be more
easily extended with arbitrary RDF assertions and the WSDL 2.0
information can be more easily associated with arbitrary other
knowledge.
7.11.1 RDF
Representation of WSDL 2.0
WSDL 2.0: Mapping to RDF
@@bibref@@ describes how WSDL 2.0 constructs
can be expressed in RDF using classes of resources (described with
an ontology expressed in OWL) and assertions over individual
resources. As RDF represents knowledge using resources and
relationships between them, we need to turn WSDL 2.0 concepts into
this model. This is done as follows.
-
First, all components in WSDL 2.0 (like
Interfaces, Operations, Bindings, Services, Endpoints etc.,
including extensions) are turned into resources identified with the
appropriate URIs created according to @@Appendix C@@.
-
Further, things are represented as
resources:
-
Element declarations gathered from XML
Schema (or similarly, other components from other type
systems)
-
Message content models
-
Message exchange patterns (the URI
identifying the MEP is the URI of the resource)
-
Operation styles (similarly to MEPs, the
URI of an operation style is the URI of the resource)
-
All the resources above are given the
appropriate types using rdf:type statements (an interface will
belong to the class Interface and an operation within an interface
will belong to the class InterfaceOperation, for
example).
-
All relationships in WSDL 2.0 (like an
Operation belonging to an Interface and having a given operation
style) are turned into RDF statements using appropriate properties,
such as operation
and operationStyle .
7.16 7.12 Notes on URIs
This section deleted text:
does not directly contribute to the
specification, but provides background that may be useful
when authoring a WSDL 2.0 document or
implementing the WSDL 2.0
specification.
7.16.1 7.12.1 XML
Namespaces and Schema Locations
It is a common misperception to equate either the target
namespace of an XML Schema or the value of the xmlns
attribute in XML instances with the location of the corresponding
schema. Even though namespaces are URIs, and URIs may be locations,
and it may be possible to retrieve a schema from such a location,
this does not mean that the retrieved schema is the only
schema that is associated with that namespace. There can be
multiple schemas associated with a particular namespace, and it is
up to a processor of XML to determine which one to use in a
particular processing context. The WSDL specification provides the
processing context here via the import mechanism,
which is based on XML Schema's term for the similar concept.
7.16.2 7.12.2 Relative URIs
Throughout this document there are fully qualified URIs used in
WSDL 2.0 and XSD examples.
The In some
cases, the use of a fully qualified URI is simply to
illustrate the referencing concepts. The however, the
use of relative URIs is allowed and warranted in many cases. For
information on processing relative URIs, see RFC2396 .
7.16.3 7.12.3 Generating Temporary URIs
deleted text: <table border="1" summary="Editorial note:
dbooth"> <tr> <td align="left" valign="top"
width="50%"> <b> Editorial note: dbooth </b>
</td> <td align="right" valign="top" width="50%">
</td> </tr> <tr> <td colspan="2"
align="left" valign="top"> Is this convention vendor-specific?
http://tempuri.org only seems to mention MS tools. If so, this
section needs to be further edited or removed. </td>
</tr> </table>
When working with WSDL,
In general, when a WSDL 2.0 document is
published for use by others, it should contain URIs that are
globally unique. This is usually done by allocating them under a
domain name that is controlled by the issuer. For example, the W3C
allocates namespace URIs under its base domain name,
w3.org.
However, it is sometimes desirable
to make up a temporary URI for an
entity, for use during development,
but not make the URI globally unique for all time and have it
"mean" that version of the entity (schema, WSDL 2.0 document, etc.). There
is a particular Reserved Top
Level DNS Names [
IETF RFC
2606 ] specifies
some URI base names that are
reserved for use for this type of behavior. The For example,
the base URI "http://tempuri.org/" "http://example.org/" can be used to construct a
temporary URI without any unique
association to an entity. For
example, This means that two
people or programs could choose to simultaneously use the
temporary URI " http://tempuri.org/userSchema" http://example.org/userSchema" for two completely
different schemas, and as
schemas. As long as the scope of
deleted text: the use of the
these URIs does not intersect, then
they are considered would be unique enough. This has the further benefit that the entity referenced
by the URI can be versioned without having to generate a new URI,
as long as However, it
deleted text: makes sense within the processing context. It is
not recommended that " http://tempuri.org/" http://example.org/" be used as a base for
stable, fixed entities.
