WSDL: Difference between revisions
m
minor tweak
m (tidying up) |
m (minor tweak) |
||
(5 intermediate revisions by the same user not shown) | |||
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:soap11" (in reference to SOAP 1.1) 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=== | ||
Although the last of the children of the <description> element, the '''service''' element is the natural starting point for human WSDL readers. There ''can'' be more than one service defined in a single WSDL document, which is sometimes sensible for describing different physical services which share the same logical definition (a service provider might provide the same service from a number of different network locations - i.e. servers - to provide redundancy, or multiple services might share some aspects, in particular data types, in common), however most commonly only a single service will be described. | Although the last of the children of the <description> element, the '''service''' element is the natural starting point for human WSDL readers. There ''can'' be more than one service defined in a single WSDL document, which is sometimes sensible for describing different physical services which share the same logical definition (a service provider might provide the same service from a number of different network locations - i.e. servers - to provide redundancy, or multiple services might share some aspects, in particular data types, in common), however most commonly only a single service will be described. | ||
As with serveral 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 45: | Line 45: | ||
The '''binding''' element is what joins the physical implementation of the service - a <port> element within the <service> element - to its logical (or abstract) definition, which is represented by the <portType> element (see below). | The '''binding''' element is what joins the physical implementation of the service - a <port> element within the <service> element - to its logical (or abstract) definition, which is represented by the <portType> element (see below). | ||
The binding element will have two attributes which effect this joining: its '''name''' attribute, which is what is pointed to by the ''binding'' attribute of the service "port" element above, and its '''type''' attribute which in turn points to a "portType" (again, usually defined within the same WSDL document and hence having a "tns" prefix. | The binding element will have two attributes which effect this joining: its '''name''' attribute, which is what is pointed to by the ''binding'' attribute of the service "port" element above, and its '''type''' attribute which in turn points to a "portType" (again, usually defined within the same WSDL document and hence having a "tns" prefix). | ||
Within the binding element there will be one or more protocol binding elements, the most common of which is the '''<soap:binding>'''. This will define the SOAP ''style'' attribute, either "[[RPC Style SOAP|rpc]]" or "[[Document Style SOAP|document]]", and a ''transport'' element, set to a URI defining that, such as "<nowiki>http://schemas.xmlsoap.org/soap/http</nowiki>". | Within the binding element there will be one or more protocol binding elements, the most common of which is the '''<soap:binding>'''. This will define the SOAP ''style'' attribute, either "[[RPC Style SOAP|rpc]]" or "[[Document Style SOAP|document]]", and a ''transport'' element, set to a URI defining that, such as "<nowiki>http://schemas.xmlsoap.org/soap/http</nowiki>". | ||
Line 53: | Line 53: | ||
Each of these will contain first a operation protocol binding, such as '''<soap:binding>''' which will again define a ''style'' attribute and also a ''soapAction'' attribute; this latter will appear as the HTTP Header field "''SOAPAction''" in the messages sent to and from the operation (in Visual DataFlex services this is set to an empty string). | Each of these will contain first a operation protocol binding, such as '''<soap:binding>''' which will again define a ''style'' attribute and also a ''soapAction'' attribute; this latter will appear as the HTTP Header field "''SOAPAction''" in the messages sent to and from the operation (in Visual DataFlex services this is set to an empty string). | ||
Following this there will be '''<input>''' and '''<output>''' elements for the operation, containing a definition of the way data is to be passed in the messages. Typically this will take the form of a '''<soap:body>''' element with a ''use'' attribute specifying either "literal" or "encoded. If an "encoded" usage is specified then an ''encodingStyle'' attribute may be present, pointing to a URI defining the style, such as "<nowiki>http://schemas.xmlsoap.org/soap/encoding/</nowiki>". There may also be a ''namespace'' attribute, for specifying a specific namespace for the operation. Additionally may be a '''<soap:header>''' element, but discussion of this falls outside the scope of this article. | Following this there will be '''<input>''' and '''<output>''' elements for the operation, containing a definition of the way data is to be passed in the messages. Typically this will take the form of a '''<soap:body>''' element with a ''use'' attribute specifying either "literal" or "encoded. If an "encoded" usage is specified then an ''encodingStyle'' attribute may be present, pointing to a URI defining the style, such as "<nowiki>http://schemas.xmlsoap.org/soap/encoding/</nowiki>". There may also be a ''namespace'' attribute, for specifying a specific namespace for the operation. Additionally there may be a '''<soap:header>''' element, but discussion of this falls outside the scope of this article. | ||
===The "''portType''" element=== | ===The "''portType''" element=== | ||
Line 72: | Line 72: | ||
===The "''types''" element=== | ===The "''types''" element=== | ||
The '''types''' element is optional, but is generally required for | The '''types''' element is optional, but is generally required for any 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> |