- From: Kevin Liu <kliu@dev.w3.org>
- Date: Sat, 23 Oct 2004 05:11:36 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv8063/ws/desc/wsdl20 Modified Files: wsdl20-primer.xml Log Message: added set of examples for later use Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.13 retrieving revision 1.14 diff -C2 -d -r1.13 -r1.14 *** wsdl20-primer.xml 14 Sep 2004 12:35:04 -0000 1.13 --- wsdl20-primer.xml 23 Oct 2004 05:11:34 -0000 1.14 *************** *** 1381,1384 **** --- 1381,2071 ---- </div2> </div1> + + <div1 id="examples"> + <head>Examples </head> + <ednote> + <name>KevinL</name> + <date>20041022</date> + <edtext> Examples here are intended for use in various sections of the primer. This section will be removed after the examples here are incorporated into the appropriate sections. + </edtext> + </ednote> + + <eg xml:space="preserve"> + + Index of examples + ================= + + Introduction + Example 1 - the hotel reservation service + Interface + Example 2.1 - use xs:import as child of wsdl:types + Example 2.2 - using xs:import and xs:include under xs:schema + Example 3 - intra-types schema reference using fragmental id + Example 4 - defining reusable faults using interface inheritance + Example 5 - using RPC style + Binding + Example 6 - Defining soap headers in soap1.2 binding + Example 7 - soap1.1 binding (To be done, pending the work of soap1.1 binding) + Example 8 - http binding + Advanced Topics + Example 9 - Alternative authoring styl for the reservation service in Example 1 Using wsdl import and include + Example 10 - using media type and MTOM for attachment support + + + + + Introduction + -------------------- + Example 1 - the hotel reservation service + + <?xml version="1.0" encoding="utf-8" ?> + <definitions xmlns="http://www.w3.org/2004/08/wsdl" + targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl" + xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12" + xmlns:soap="http://www.w3.org/2003/05/soap-envelope" + xmlns:tns= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"> + + <types> + <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + + <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="tRoomType"/> + </xs:sequence> + </xs:complexType> + + <xs:simpleType name="tRoomType"> + <xs:restriction base="xs:string"> + <xs:enumeration value="Single"/> + <xs:enumeration value="Double"/> + <xs:enumeration value="Queen"/> + <xs:enumeration value="King"/> + </xs:restriction> + </xs:simpleType> + + <xs:element name="checkAvailabilityResponse" type="xs:double"/> + + <xs:element name="MakeReservation" type="tMakeReservation"/> + <xs:complexType name="tMakeReservation"> + <xs:sequence> + <xs:element name="customerName" type="xs:string"/> + <xs:element name="billingAddress" type="xs:string"/> + <xs:element name="creditCardNumber" type="xs:string"/> + </xs:sequence> + </xs:complexType> + + <xs:element name="makeReservationResponse" type="xs:string"/> + + <xs:element name="invalidCreditCardError" type="xs:string"/> + + <xs:element name="inValidDataError" type="tInvalidDataError"/> + <xs:complexType name="tInvalidDataError"> + <xs:sequence> + <xs:element name="DataField" type="xs:string"/> + <xs:element name="Description" type="xs:string"/> + </xs:sequence> + </xs:complexType> + </xs:schema> + </types> + + <interface name = "reservation" > + + <fault name = "inValidCreditCardFault" + element = "ghns:invalidCreditCardError"/> + + <fault name = "inValidDataFault" + element = "ghns:invalidDataError"/> + + <operation name="checkAvailability" pattern="http://www.w3.org/2004/03/wsdl/in-out" > + + <input messageLabel="In" element="ghns:checkAvailability" /> + + <output messageLabel="Out" element="ghns:checkAvailabilityResponse" /> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + </operation> + + <operation name="makeReservation" pattern="http://www.w3.org/2004/03/wsdl/in-out" > + + <input messageLabel="In" element="ghns:makeReservation"/> + + <output messageLabel="Out" element="ghns:makeReservationResponse"/> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + <outfault ref="inValidCreditCardFault" messageLabel="Out"/> + + </operation> + + </interface> + + <binding name="reservationSOAPBinding" + interface="tns:reservation" + type="http://www.w3.org/2004/08/wsdl/soap12" + wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP" + wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response"> + + <fault ref="tns:invalidCreditCardFault" wsoap:code="soap:Sender"/> + + <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/> + + </binding> + + <service name="reservationService" interface="tns:reservation"> + + <endpoint name="reservationEndpoint" + binding="tns:reservationSOAPBinding" + address ="http://www.greath.com/reservation"/> + + </service> + + </definitions> + + + + Interface + ----------------------------- + + examples of using xsd import and include + + When the schema is defined in separate files, they can be imported or included into wsdl + + Option 1, when the whole schema is defined in a single file, one may use xs:import as a child of wsdl:type to import that schema + + Example 2.1 - use xs:import as child of wsdl:types + + <types> + + <xs:import namespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + schemaLocation= "http://www.greath.com/2004/05/schemas/reservationService.xsd"/> + + </types> + + Option 2, when some elements are embedded under wsdl:type, some other elements defined in different files, one may using xs:import as a child of xs:schema to import elements with different namespace, and use xs:include to include elements under same namespace + + Example 2.2 - using xs:import and xs:include under xs:schema + + file 1 + <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/checkAvailability.xsd" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="http://www.greath.com/2004/05/schemas/checkAvailability.xsd"> + + <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="tRoomType"/> + </xs:sequence> + </xs:complexType> + + <xs:simpleType name="tRoomType"> + <xs:restriction base="xs:string"> + <xs:enumeration value="Single"/> + <xs:enumeration value="Double"/> + <xs:enumeration value="Queen"/> + <xs:enumeration value="King"/> + </xs:restriction> + </xs:simpleType> + + <xs:element name="checkAvailabilityResponse" type="xs:double"/> + + </xs:schema> + + file 2 (stored at http://www.greath.com/2004/05/schemas/reservationService1.xsd) + + <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + + <xs:element name="MakeReservation" type="tMakeReservation"/> + <xs:complexType name="tMakeReservation"> + <xs:sequence> + <xs:element name="customerName" type="xs:string"/> + <xs:element name="billingAddress" type="xs:string"/> + <xs:element name="creditCardNumber" type="xs:string"/> + </xs:sequence> + </xs:complexType> + + <xs:element name="makeReservationResponse" type="xs:string"/> + + </xs:schema> + + Some elements are embedded in the WSDL file. + + + <definitions ...> + + <types> + <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + + <xs:import namespace="http://www.greath.com/2004/05/schemas/checkAvailability.xsd" + schemaLocation= "http://www.greath.com/2004/05/schemas/checkAvailability.xsd"/> + + <xs:include + schemaLocation= "http://www.greath.com/2004/05/schemas/reservationService1.xsd"/> + + <xs:element name="invalidCreditCardError" type="xs:string"/> + + <xs:element name="inValidDataError" type="tInvalidDataError"/> + <xs:complexType name="tInvalidDataError"> + <xs:sequence> + <xs:element name="DataField" type="xs:string"/> + <xs:element name="Description" type="xs:string"/> + </xs:sequence> + </xs:complexType> + + </xs:schema> + </types> + + ... + + </definitions> + + + Example 3 - intra-types schema reference using fragmental id + <definitions...> + <type> + <xs:schema targetNamespace = "a" id="a"> ....</schema> + + <xs:schema targetNamespace = "b"> + <xs:import namespace = "a" schemalocation = "#a"/> ... + </schema> + + <xs:schema targetNamespace = "a"> + <xs:include schemalocation = "#a"/> ... + </schema> + + <type> + </definitions> + + + Example 4 - defining reusable faults using interface inheritance + + + <definitions...> + + <interface name = "dataFault"> + + <fault name = "inValidDataFault" + element = "ghns:invalidDataError"/> + + </interface> + + <interface name = "reservation" extends = "tns:dataFault"> + + <fault name = "inValidCreditCardFault" + element = "ghns:invalidCreditCardError"/> + + <operation name="checkAvailability" pattern="http://www.w3.org/2004/03/wsdl/in-out" > + + <input messageLabel="In" element="ghns:checkAvailability" /> + + <output messageLabel="Out" element="ghns:checkAvailabilityResponse" /> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + </operation> + + <operation name="makeReservation" pattern="http://www.w3.org/2004/03/wsdl/in-out" > + + <input messageLabel="In" element="ghns:makeReservation"/> + + <output messageLabel="Out" element="ghns:makeReservationResponse"/> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + <outfault ref="inValidCreditCardFault" messageLabel="Out"/> + + </operation> + + </interface> + + ... + + </definitions> + + + Note that the schema of the input and output messages of operation "makeReservation" meets all the rules of the RPC style, so if desired, the operation "makeResercation" can be marked using RPC style. + + Example 5 - using RPC style + + <definitions xmlns:wrpc = "http://www.w3.org/2004/08/wsdl/rpc" ...> + + ... + + <interface name = "reservation" ...> + + ... + + <operation name="makeReservation" pattern="http://www.w3.org/2004/03/wsdl/in-out" + style = "http://www.w3.org/2004/08/wsdl/style/rpc" + wrpc:signature = "(ghns:customerName #in) (ghns:billingAddress #in) (ghns:creditCardNumber #in) (ghns:makeReservationResponse #return)"> + + <input messageLabel="In" element="ghns:makeReservation"/> + + <output messageLabel="Out" element="ghns:makeReservationResponse"/> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + <outfault ref="inValidCreditCardFault" messageLabel="Out"/> + + </operation> + + </interface> + + ... + + </definitions> + + + + Binding section + ----------------- + + Assume the soap binding of our "reservation" interface uses two soap modules: one for reliability with the uri of "http://example.com/reliability" and is appliable to all messages exchanged with the service, the other for security with the uri of "http://example.com/security" and is only appliable to the input message of operation "checkAvailability". Example 6 shows how to include these soap modules in the soap 1.2 binding. + + Example 6 - Defining soap headers in soap1.2 binding + + <definitions...> + ... + <binding name="reservationSOAPBinding" + interface="tns:reservation" + type="http://www.w3.org/2004/08/wsdl/soap12" + wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP" + wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response"> + + + <fault ref="tns:invalidCreditCardFault" wsoap:code="soap:Sender"/> + + <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/> + + <wsoap:module uri= "http://example.com/reliability" required = "1"/> + + <operation ref = "tns:checkAvailability"> + <input> + <wsoap:module uri= "http://example.com/reliability" required = "1"/> + </input> + </operation> + ... + + </binding> + ... + + </definitions> + + the corresponding run time input message for checkAvailability would be something like + + + POST /reservation HTTP/1.1 + Host: http://www.greath.com + Content-Type: application/soap+xml; charset="utf-8" + Content-Length: nnnn + + <?xml version="1.0" ?> + <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> + + <soapenv:Header> + <r:some-reliability-headerblock xmlns:r="http://example.com/reliability"> + ... + </r:some-reliability-headerblock> + <r:some-security-headerblock xmlns:r="http://example.com/security"> + ... + </r:some-security-headerblock> + </soapenv:Header> + + <soapenv:Body> + <m:checkAvailability xmlns:m="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + <m:chekcInDate>2008-11-11</m:checkInDate> + <m:chekcOutDate>2008-11-28</m:checkOutDate> + <m:roomType>King</m:roomType> + </m:checkAvailability> + </soapenv:Body> + </soapenv:Envelope> + + + + Example 7 - soap1.1 binding (To be done, pending the work of soap1.1 binding) + + + Example 8 - http binding + + <definitions...> + ... + <binding name="reservationHTTPBinding" + interface="tns:reservation" + type="http://www.w3.org/2004/08/wsdl/http" + whttp:version="1.1" + whttp:cookies = "0"> + + <fault ref="tns:invalidCreditCardFault" whttp:code="400"/> + + <fault ref="tns:invalidDataFault" whttp:code="400"/> + + <operation ref = "tns:checkAvailability" + whttp:method= "POST" + whttp:inputSerialization= "application/xml"> + + <input whttp:transferCoding="???" /> + + </operation> + ... + + </binding> + + <service name="reservationService" interface="tns:reservation"> + + <endpoint name="reservationEndpoint" + binding="tns:reservationHTTPBinding" + address ="http://www.greath.com/reservation" + whttp:authenticationType = "none"/> + + </service> + + </definitions> + + + The corresponding HTTP message is something like: + + POST /reservation HTTP/1.1 + Host: http://www.greath.com + Content-Type: application/xml; charset="utf-8" + Content-Length: nnnn + + <m:checkAvailability xmlns:m="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + <m:chekcInDate>2008-11-11</m:checkInDate> + <m:chekcOutDate>2008-11-28</m:checkOutDate> + <m:roomType>King</m:roomType> + </m:checkAvailability> + + + Advanced Topics + ------------------- + Example 9 - Alternative authoring styl for the reservation service in Example 1 Using wsdl import and include + + file 1: http://www.greath.com/2004/05/schemas/reservationService.xsd + + <?xml version="1.0" encoding="utf-8" ?> + <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + + <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="tRoomType"/> + </xs:sequence> + </xs:complexType> + + <xs:simpleType name="tRoomType"> + <xs:restriction base="xs:string"> + <xs:enumeration value="Single"/> + <xs:enumeration value="Double"/> + <xs:enumeration value="Queen"/> + <xs:enumeration value="King"/> + </xs:restriction> + </xs:simpleType> + + <xs:element name="checkAvailabilityResponse" type="xs:double"/> + + <xs:element name="MakeReservation" type="tMakeReservation"/> + <xs:complexType name="tMakeReservation"> + <xs:sequence> + <xs:element name="customerName" type="xs:string"/> + <xs:element name="billingAddress" type="xs:string"/> + <xs:element name="creditCardNumber" type="xs:string"/> + </xs:sequence> + </xs:complexType> + + <xs:element name="makeReservationResponse" type="xs:string"/> + + <xs:element name="invalidCreditCardError" type="xs:string"/> + + <xs:element name="inValidDataError" type="tInvalidDataError"/> + <xs:complexType name="tInvalidDataError"> + <xs:sequence> + <xs:element name="DataField" type="xs:string"/> + <xs:element name="Description" type="xs:string"/> + </xs:sequence> + </xs:complexType> + </xs:schema> + + File 2 - http://www.greath.com/2004/05/wsdl/reservationService-interface.wsdl + + <?xml version="1.0" encoding="utf-8" ?> + <definitions xmlns="http://www.w3.org/2004/08/wsdl" + targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl" + xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:tns= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"> + + <types> + + <xs:import namespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + schemaLocation= "http://www.greath.com/2004/05/schemas/reservationService.xsd"/> + + </types> + + + <interface name = "reservation" > + + <fault name = "inValidCreditCardFault" + element = "ghns:invalidCreditCardError"/> + + <fault name = "inValidDataFault" + element = "ghns:invalidDataError"/> + + <operation name="checkAvailability" pattern="http://www.w3.org/2004/03/wsdl/in-out" > + + <input messageLabel="In" element="ghns:checkAvailability" /> + + <output messageLabel="Out" element="ghns:checkAvailabilityResponse" /> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + </operation> + + <operation name="makeReservation" pattern="http://www.w3.org/2004/03/wsdl/in-out" > + + <input messageLabel="In" element="ghns:makeReservation"/> + + <output messageLabel="Out" element="ghns:makeReservationResponse"/> + + <outfault ref="inValidDataFault" messageLabel="Out"/> + + <outfault ref="inValidCreditCardFault" messageLabel="Out"/> + + </operation> + + </interface> + + </definitions> + + File 3 - http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl + + <?xml version="1.0" encoding="utf-8" ?> + <definitions xmlns="http://www.w3.org/2004/08/wsdl" + targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl" + xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12" + xmlns:soap="http://www.w3.org/2003/05/soap-envelope" + xmlns:tns= "http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl"> + + + + <binding name="reservationSOAPBinding" + interface="tns:reservation" + type="http://www.w3.org/2004/08/wsdl/soap12" + wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP" + wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response"> + + <fault ref="tns:invalidCreditCardFault" wsoap:code="soap:Sender"/> + + <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/> + + </binding> + + + </definitions> + + + File 4 - the complete service definition + + <?xml version="1.0" encoding="utf-8" ?> + <definitions xmlns="http://www.w3.org/2004/08/wsdl" + targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl" + xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12" + xmlns:soap="http://www.w3.org/2003/05/soap-envelope" + xmlns:tns= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl" + xmlns:bns = "http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl"> + + <include location = "http://www.greath.com/2004/05/wsdl/reservationService-interface.wsdl"/> + <import namespace = "http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl" + location = "http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl"/> + + <service name="reservationService" interface="tns:reservation"> + + <endpoint name="reservationEndpoint" + binding="bns:reservationSOAPBinding" + address ="http://www.greath.com/reservation"/> + + </service> + + </definitions> + + + Example 10 - using media type and MTOM for attachment support + + Let's say that the checkAvailability operation may return a vedio file for a virtual tours of the room availale. Example 10 shows how to indicate in WSDL that MTOM may be used to optimize the transmission. + + The schema of the response message in Example 1 needs to be modified to indicate the expected media type. + + + <?xml version="1.0" encoding="utf-8" ?> + <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns:xmlmime="http://www.w3.org/@@@@/@@/xmlmime" + xmlns="http://www.greath.com/2004/05/schemas/reservationService.xsd"> + + <xs:import namespace="http://www.w3.org/@@@@/@@/xmlmime" + schemaLocation="http://www.w3.org/@@@@/@@/xmlmime"/> + + + ... + + <xs:element name="checkAvailabilityResponse" type="xmlmime:base64binary"> + xmlmime:expectedMediaType="vedio/*"/> + + ... + + </xs:schema> + + Then in the binding, use a feature to indicate the use of MTOM + + <?xml version="1.0" encoding="utf-8" ?> + <definitions xmlns="http://www.w3.org/2004/08/wsdl" + targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl" + xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd" + xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12" + xmlns:soap="http://www.w3.org/2003/05/soap-envelope" + xmlns:tns= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl" + xmlns:bns = "http://www.greath.com/2004/05/wsdl/reservationService-binding.wsdl"> + + ... + + <binding name="reservationSOAPBinding" + interface="tns:reservation" + type="http://www.w3.org/2004/08/wsdl/soap12" + wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP" + wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response"> + + ... + + <wsdl:feature uri="http://www.w3.org/2004/08/soap/features/http-optimization"/> + + ... + + </binding> + + ... + + </definitions> + + + + </eg> + + + </div1> </body> </spec>
Received on Saturday, 23 October 2004 05:11:37 UTC