WSDL: Difference between revisions
m
Tweaks
m (tidying up) |
m (Tweaks) |
||
| Line 16: | Line 16: | ||
*'''types''' - only one element (optional) describing the extended data types used by the service | *'''types''' - only one element (optional) describing the extended data types used by the service | ||
*'''message''' - defining the in and out messages used by the service's operations | *'''message''' - defining the in and out messages used by the service's operations | ||
*'''portType''' - | *'''portType''' - the abstract definition of the service | ||
*'''binding''' - providing a link between the abstract definition and the concrete implementation | *'''binding''' - providing a link between the abstract definition and the concrete implementation | ||
*'''service''' - the concrete specification of a service | *'''service''' - the concrete specification of a service | ||
| Line 28: | Line 28: | ||
* The XML Schema namespace, where the base XML types are defined: <span style="color:midnightblue;">xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>"</span> | * The XML Schema namespace, where the base XML types are defined: <span style="color:midnightblue;">xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>"</span> | ||
* The [[SOAP]] namespace: <span style="color:midnightblue;">xmlns:soap="<nowiki>http://schemas.xmlsoap.org/wsdl/soap/</nowiki>"</span> | * The [[SOAP]] namespace: <span style="color:midnightblue;">xmlns:soap="<nowiki>http://schemas.xmlsoap.org/wsdl/soap/</nowiki>"</span> | ||
* The service's own namespace, which is usually associated with the namespace prefix "tns" - ('''t'''his '''n'''ame'''s'''pace): <span style="color:midnightblue;">xmlns:tns="http://''yourDomain/yourService/serviceName''</span> | * The service's own namespace, which is usually associated with the namespace prefix "tns" - ('''t'''his '''n'''ame'''s'''pace): <span style="color:midnightblue;">xmlns:tns="http://''yourDomain/yourService/serviceName''"</span> | ||
* The "target" namespace, which is | * The "target" namespace, which is generally identical to the "tns" one: <span style="color:midnightblue;">targetNamespace="http://''yourDomain/yourService/serviceName''"</span> | ||
There may be ''many'' more than these (look at any Microsoft .Net service WSDL), but most services will define at least these ones as a minimum, although not always in exactly | There may be ''many'' more than these (look at any Microsoft .Net service WSDL), but most services will define at least these ones as a minimum, although not always in exactly this form. In particular, the choice of namespace prefixes is arbitrary, so the base namespace might be specified as "xmlns:wsdl", rather than just "xmlns"; "xmlns:xs" is often seen as "xmlns:xsd"; "xmlns:soap" might be "xmlns:soap12" (in reference to SOAP 1.2) or many other variations - remember that it is the actual namespace URI which is being referenced that is important, not the prefix used to represent it in the document, which can be anything. | ||
===The "''service''" element=== | ===The "''service''" element=== | ||
| Line 38: | Line 38: | ||
Like most of the WSDL main elements, the service element can have a <documentation> element within it. In [[Visual DataFlex]] you can set this via the "psDocumentation" property of the Web Service object. It will also have a '''name''' attribute, which will be whatever you set the psServiceName property of your Web Service object to. | Like most of the WSDL main elements, the service element can have a <documentation> element within it. In [[Visual DataFlex]] you can set this via the "psDocumentation" property of the Web Service object. It will also have a '''name''' attribute, which will be whatever you set the psServiceName property of your Web Service object to. | ||
The crucial element within the service is the '''<port>'''. This defines an implementation of the service as a network resource and has a "binding" attribute which will | The crucial element within the service is the '''<port>'''. This defines an implementation of the service as a network resource and has a "binding" attribute which will point to a '''<binding>''' element (see below) in the same WSDL document (and hence will tend to have the namespace prefix "tns": this namespace). This will attribute will lead us on our trail, ''up'' the WSDL, to our next stop, the binding element. | ||
While there are sometimes other protocols defined (HTTP, SMTP, FTP, etc.), the commonest by far is for SOAP, so within the <port> element it is common to find a '''<soap:address>''' element, specifying, via its "location" attribute, the actual [[URI]] through which the service can be invoked. | While there are sometimes other protocols defined (HTTP, SMTP, FTP, etc.), the commonest by far is for SOAP, so within the <port> element it is common to find a '''<soap:address>''' element, specifying, via its "location" attribute, the actual [[URI]] through which the service can be invoked. | ||
| Line 74: | Line 74: | ||
The '''types''' element is optional, but is generally required for an non-trivial services, especially those of Document-style. There is only ever one types element in a WSDL document. | The '''types''' element is optional, but is generally required for an non-trivial services, especially those of Document-style. There is only ever one types element in a WSDL document. | ||
Within the types element there will be one or more '''<schema>''' elements within the "<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>" namespace. Within ''these'' will be the definitions of all the data types beyond the XML primitive types, and in fact in Document-style services even the most primitive data type (including none at all!) is generally referenced to a specific definition in a schema. | Within the types element there will be one or more '''<schema>''' elements within the "<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>" namespace. Within ''these'' will be the definitions of all the data types used by the service, beyond the XML primitive types, and in fact in Document-style services even the most primitive data type (including none at all!) is generally referenced to a specific definition in a schema. | ||
The topic of XML schema definitions is beyond the scope of this article however, so our investigation of the elements of WSDL, and their decomposition, must end there. | The topic of XML schema definitions is beyond the scope of this article however, so our investigation of the elements of WSDL, and their decomposition, must end there. | ||
==Example== | ==Example== | ||
To illustrate the above here is a sample of a very simple service WSDL | To illustrate the above here is a sample of a very simple (it takes a single string as a parameter and returns another string) service WSDL: start from the '''''service''''' element at the bottom and work up through the various elements to the '''''types''''' definitions: | ||
<?xml version="1.0" encoding="UTF-8" ?> | <?xml version="1.0" encoding="UTF-8" ?> | ||
<definitions xmlns="<nowiki>http://schemas.xmlsoap.org/wsdl/</nowiki>" | <'''definitions''' xmlns="<nowiki>http://schemas.xmlsoap.org/wsdl/</nowiki>" | ||
xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>" | xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>" | ||
xmlns:soap="<nowiki>http://schemas.xmlsoap.org/wsdl/soap/</nowiki>" | xmlns:soap="<nowiki>http://schemas.xmlsoap.org/wsdl/soap/</nowiki>" | ||
xmlns:tns="<nowiki>http://unicorninterglobal.com/sample/" | xmlns:tns="<nowiki>http://unicorninterglobal.com/sample/</nowiki>" <span style="color:red">--set from psServiceURI</span> | ||
name="Hello" | |||
targetNamespace="<nowiki>http://unicorninterglobal.com/sample/</nowiki>"> <span style="color:red">--set from psServiceURI</span> | |||
<types> | <'''types'''> | ||
<xs:schema elementFormDefault="qualified" targetNamespace="<nowiki>http://unicorninterglobal.com/sample/</nowiki>"> | <xs:schema elementFormDefault="qualified" targetNamespace="<nowiki>http://unicorninterglobal.com/sample/</nowiki>"> | ||
<xs:element name="'''SayHello'''"> <span style="color:red">--link from input message</span> | <xs:element name="'''SayHello'''"> <span style="color:red">--link from input message</span> | ||
| Line 108: | Line 108: | ||
</types> | </types> | ||
<message name="'''SayHelloSoapRequest'''"> <span style="color:red">--link from portType</span> | <'''message''' name="'''SayHelloSoapRequest'''"> <span style="color:red">--link from portType</span> | ||
<part name="parameters" element="'''tns:SayHello'''" /> <span style="color:red">--link to type definition</span> | <part name="parameters" element="'''tns:SayHello'''" /> <span style="color:red">--link to type definition</span> | ||
</message> | </message> | ||
<message name="'''SayHelloSoapResponse'''"> <span style="color:red">--link from portType</span> | <'''message''' name="'''SayHelloSoapResponse'''"> <span style="color:red">--link from portType</span> | ||
<part name="parameters" element="'''tns:SayHelloResponse'''" /> <span style="color:red">--link to type definition</span> | <part name="parameters" element="'''tns:SayHelloResponse'''" /> <span style="color:red">--link to type definition</span> | ||
</message> | </message> | ||
<portType name="'''HelloSoapType'''"> <span style="color:red">--link from binding</span> | <'''portType''' name="'''HelloSoapType'''"> <span style="color:red">--link from binding</span> | ||
<operation name="SayHello"> | <operation name="SayHello"> | ||
<documentation>This operation says 'Hello!'</documentation> | <documentation>This operation says 'Hello!'</documentation> <span style="color:red">--set from <span style="color:gray">{ Description = "..." }</span> meta-data on function</span> | ||
<input message="'''tns:SayHelloSoapRequest'''" /> <span style="color:red">--link to message</span> | <input message="'''tns:SayHelloSoapRequest'''" /> <span style="color:red">--link to message</span> | ||
<output message="'''tns:SayHelloSoapResponse'''" /> <span style="color:red">--link to message</span> | <output message="'''tns:SayHelloSoapResponse'''" /> <span style="color:red">--link to message</span> | ||
| Line 124: | Line 124: | ||
</portType> | </portType> | ||
<binding name="'''HelloSoapBinding'''" type="'''tns:HelloSoapType'''"> <span style="color:red">--links ''from'' service and ''to'' portType</span> | <'''binding''' name="'''HelloSoapBinding'''" type="'''tns:HelloSoapType'''"> <span style="color:red">--links ''from'' service and ''to'' portType</span> | ||
<soap:binding style="document" transport="<nowiki>http://schemas.xmlsoap.org/soap/http</nowiki>" /> | <soap:binding style="document" transport="<nowiki>http://schemas.xmlsoap.org/soap/http</nowiki>" /> | ||
<operation name="SayHello"> | <operation name="SayHello"> | ||
| Line 137: | Line 137: | ||
</binding> | </binding> | ||
<service name="Hello"> | <'''service''' name="Hello"> | ||
<documentation>Sample documentation for the service</documentation> <span style="color:red">--from psDocumentation</span> | <documentation>Sample documentation for the service</documentation> <span style="color:red">--set from psDocumentation</span> | ||
<port name="HelloSoap" binding="'''tns:HelloSoapBinding'''"> <span style="color:red">--connects to the "binding" element</span> | <port name="HelloSoap" binding="'''tns:HelloSoapBinding'''"> <span style="color:red">--connects to the "binding" element</span> | ||
<soap:address location="<nowiki>http://www.sample.com/services/Hello.wso</nowiki>" /> <span style="color:red">--service endpoint URI</span> | <soap:address location="<nowiki>http://www.sample.com/services/Hello.wso</nowiki>" /> <span style="color:red">--service endpoint URI</span> | ||