- From: Arthur Ryman via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 27 Mar 2005 16:13:03 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv4049 Modified Files: wsdl20-primer.xml Log Message: Added primer section on Service References. Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.38 retrieving revision 1.39 diff -C2 -d -r1.38 -r1.39 *** wsdl20-primer.xml 23 Mar 2005 03:40:09 -0000 1.38 --- wsdl20-primer.xml 27 Mar 2005 16:13:01 -0000 1.39 *************** *** 1583,1590 **** --- 1583,2108 ---- <p>[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.html that prescribes when to use GET versus POST as well as some useful example]</p> </div2> + <div2 id="adv-service-references"> <head>Service References</head> + <ednote> + <name>Arthur</name> + <date>20050326</date> + <edtext> + This is the first draft. Please review. + The source for all the examples is in the test suite. + See <loc href="http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/documents/good/ServiceReference-1G/">ServiceReference-1G</loc>. + </edtext> + </ednote> <p>[Use http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.html as a starting point. Also example(s) from Roberto per the resolution at the end of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ]</p> + + <p> + Hyperlinking is one of the defining characteristics + of the Web. The ability to navigate from one Web + page to another is extremely useful. It is therefore + natural to apply this capability to Web services. + This section describes + <em>service references</em> + which are the Web service analogs of document + hyperlinks. + </p> + + <div3 id="reservationDetails"><head>The Reservation Details Web Service</head> + + <p> + When designing a Web application it is natural to + give each important concept a URI. In the 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 Detail Web service that can retrieve and + update the state of a reservation. + <specref ref='reservationDetails-OMX736.xml' /> + shows the format of the reservation detail. + </p> + + <example id="reservationDetails-OMX736.xml"> + <head>Detail for Reservation OMX736</head> + <eg><![CDATA[<?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>]]></eg> + </example> + + <p> + The Reservation Details Web service provides operations for retrieving and updating the detail for a reservation. + <specref ref="reservationDetails.wsdl"/> shows the description for this Web service. + Note that there is no <code>wsdl:service</code> 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. + </p> + + <example id="reservationDetails.wsdl"> + <head>The Reservation Details Web Service Description: reservationDetails.wsdl</head> + <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?> + <description xmlns="http://www.w3.org/2004/08/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/2004/08/wsdl/soap12" + 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/2004/03/wsdl/in-out"> + <input messageLabel="In" element="#none" /> + <output messageLabel="Out" + element="wdetails:reservationDetails" /> + </operation> + + <operation name="update" + pattern="http://www.w3.org/2004/03/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/2004/08/wsdl/soap12" + 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> + + ]]></eg></example> + + <p> + <specref ref="reservationDetails.xsd" /> shows the XML schema elements that are used in this Web service. + </p> + + <example id="reservationDetails.xsd"> + <head> + The Reservation Details Web Service XML Schema: + reservationDetails.xsd + </head> + <eg><![CDATA[<?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/2004/08/wsdl"> + + <import namespace="http://www.w3.org/2004/08/wsdl" + schemaLocation="../../../xmlcatalog/wsdl/wsdl20.xsd" /> + + <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="ReservationDetailsEndpointType"> + <complexContent> + <restriction base="wsdl:EndpointType"> + <attribute name="binding" type="QName" use="required" + fixed="wdetails:reservationDetailsSOAPBinding" /> + </restriction> + </complexContent> + </complexType> + + <complexType name="ReservationDetailsServiceType"> + <complexContent> + <restriction base="wsdl:ServiceType"> + <sequence> + <element name="endpoint" + type="tns:ReservationDetailsEndpointType" /> + </sequence> + <attribute name="interface" type="QName" use="required" + fixed="wdetails:reservationDetailsInterface" /> + </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> + ]]></eg> + </example> + + <p> + This XML schema contains the usual definitions for the elements + that appear in the messages of the Web service. For example, the + <code>reservationDetails</code> + element is used in the messages of the retrieve and update + operations. In addition, the schema defines two + <em>restrictions</em> + of WSDL complex types. The + <code>ReservationDetailsEndpointType</code> + complex type restricts the + <code>wsdl:EndpointType</code> + complex type to have a + <code>binding</code> + attribute whose value is the Reservation Details binding, + <code>wdetails:reservationDetailsSOAPBinding</code>. + </p> + + <p> + The schema also defines the + <code>ReservationDetailsServiceType</code> + complex type to restrict the + <code>wsdl:ServiceType</code> + to have an + <code>interface</code> + attribute whose have is the Reservation Details service + interace, + <code>wdetails:reservationDetailsInterface</code> + . The + <code>reservationDetailsService</code> + element is thus a restriction of the + <code>wsdl:service</code> + element that has the interface and binding for the Reservation + Details service and whose endpoint address is that of the + corresponing reservation. This element is used in the definition + of the Reservation List Web service. + </p> + + </div3> + + <div3 id="reservationList"> + <head>The Reservation List Web Service</head> + <p> + 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 service 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. + </p> + + <ednote> + <name>Arthur</name> + <date>20050326</date> + <edtext> + There is a minor problem in this example. + For some reason, the Xerces parser thinks + that when I restrict the + <code>wsdl:ServiceType</code> + complex type by constraining the + <code>wsdl:endpoint</code> + element to have a fixed value for its + <code>binding</code> + attribute, that the namespace of the + <code>wsdl:endpoint</code> + element changes to the target namespace of + the schema. I assume this is a bug in + Xerces. I'd appreciate it if someone could + try validating this example with another + processor. + </edtext> + </ednote> + <p> + <specref ref="reservationList-all.xml" /> + shows the format of the response from the + Reservation List service. + </p> + <example id="reservationList-all.xml"> + <head> + Response from the Reservation List Web + Service + </head> + <eg> + <![CDATA[<?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:wsdli="http://www.w3.org/2004/08/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:reservationDetailsService + interface="wdetails:reservationDetailsInterface"> + <details:endpoint name="SOAP" + binding="wdetails:reservationDetailsSOAPBinding" + address="http://greath.example.com/2004/reservation/HSG635"/> + </details:reservationDetailsService> + </reservation> + + <reservation> + <details:confirmationNumber>OMX736</details:confirmationNumber> + <details:checkInDate>2005-06-01</details:checkInDate> + <details:checkOutDate>2005-06-03</details:checkOutDate> + <details:reservationDetailsService + interface="wdetails:reservationDetailsInterface"> + <details:endpoint name="SOAP" + binding="wdetails:reservationDetailsSOAPBinding" + address="http://greath.example.com/2004/reservation/OMX736"/> + </details:reservationDetailsService> + </reservation> + + <reservation> + <details:confirmationNumber>WUH663</details:confirmationNumber> + <details:checkInDate>2005-06-11</details:checkInDate> + <details:checkOutDate>2005-06-15</details:checkOutDate> + <details:reservationDetailsService + interface="wdetails:reservationDetailsInterface"> + <details:endpoint name="SOAP" + binding="wdetails:reservationDetailsSOAPBinding" + address="http://greath.example.com/2004/reservation/WUH663"/> + </details:reservationDetailsService> + </reservation> + + </reservationList>]]> + </eg> + </example> + + <p> + Here, the + <code> + <details:reservationDetailsService> + </code> + elements contain service references to the + Reservation Details Web services for the + reservations HSG635, OMX736, and WUH663. The + service references given the interface, binding, + and endpoint address of each service. In this + example, all endpoints have the same interface + and binding, i.e. + <code> + wdetails:reservationDetailsInterface + </code> + and + <code> + wdetails:reservationDetailsSOAPBinding + </code> + . These QNames identify WSLD Interface and + Binding components that are defined in a WSDL + document. This example shows the use of the + <code>wsdli:wsdlLocation</code> + attribute to locate the WSDL document. The + address of each endpoint is the URI assigned to + each reservation. + </p> + + <p> + <specref ref="reservationList.wsdl" /> + shows the description of the Reservation List + Web service. Note that is 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. + </p> + + <example id="reservationList.wsdl"> + <head> + The Reservation List Web Service + Description: reservationList.wsdl + </head> + <eg> + <![CDATA[<?xml version="1.0" encoding="utf-8" ?> + <description xmlns="http://www.w3.org/2004/08/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/2004/08/wsdl/soap12" + 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/2004/03/wsdl/in-out"> + <input messageLabel="In" element="#none" /> + <output messageLabel="Out" element="list:reservationList" /> + </operation> + + <operation name="retrieveByConfirmationNumber" + pattern="http://www.w3.org/2004/03/wsdl/in-out"> + <input messageLabel="In" + element="details:confirmationNumber" /> + <output messageLabel="Out" element="list:reservationList" /> + </operation> + + <operation name="retrieveByCheckInDate" + pattern="http://www.w3.org/2004/03/wsdl/in-out"> + <input messageLabel="In" element="details:checkInDate" /> + <output messageLabel="Out" element="list:reservationList" /> + </operation> + + <operation name="retrieveByCheckOutDate" + pattern="http://www.w3.org/2004/03/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/2004/08/wsdl/soap12" + 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>]]> + </eg> + </example> + + <p><specref ref="reservationList.xsd"/>Shows the schema for the messages used in the Reservation List Web service.</p> + <example id="reservationList.xsd"> + <head></head> + <eg><![CDATA[<?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/2004/08/wsdl-instance"> + + <import namespace="http://www.w3.org/2004/08/wsdl-instance" + schemaLocation="../../../xmlcatalog/wsdl/wsdl20-instance.xsd" /> + + <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:reservationDetailsService" /> + </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> + ]]></eg> + </example> + </div3> </div2> + <div2 id="adv-xml-schema-examples"><head>XML Schema Examples</head> <p>[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]</p>
Received on Sunday, 27 March 2005 16:13:04 UTC