WSDL: Difference between revisions
From DataFlex Wiki
Jump to navigationJump to search
Adding...
(Adding...) |
(Adding...) |
||
| Line 3: | Line 3: | ||
WSDL is most commonly automatically generated by the service software - this is the case with [[Visual DataFlex]] - but in some cases, where the software used does not provide this capability, it may be hand-written. This latter case can produce some very idiosyncratic and non-standard WSDL that causes problems for service consumers. | WSDL is most commonly automatically generated by the service software - this is the case with [[Visual DataFlex]] - but in some cases, where the software used does not provide this capability, it may be hand-written. This latter case can produce some very idiosyncratic and non-standard WSDL that causes problems for service consumers. | ||
If your software platform or toolkit provides for automatic generation of WSDL from your own services, and for automatic creation of ''proxy'' or ''stub'' client code from other people's services, then it should never be necessary to understand the complexities of WSDL... ''until | If your software platform or toolkit provides for automatic generation of WSDL from your own services, and for automatic creation of ''proxy'' or ''stub'' client code from other people's services, then it should never be necessary to understand the complexities of WSDL... ''until something goes wrong!'' Then you may have to ''"look under the hood"''. | ||
(''Note: I will be describing WSDL 1.x here - 2.0 is different in a number of regards. [[User:Mikepeat|Mike]]'') | (''Note: I will be describing WSDL 1.x here - 2.0 is different in a number of regards. [[User:Mikepeat|Mike]]'') | ||
==Structure== | ==Structure== | ||
WSDL can be quite formidable to understand for those not used to looking at such things. Probably the easiest way to get to grips with | WSDL can be quite formidable to understand for those not used to looking at such things. Probably the easiest way to get to grips with it is to break it down into its various components. | ||
After any initial processing instruction (<?xml version="1.0" encoding="UTF-8"?> or similar) there will be the outer '''<description>''' element, which will typically also define a number of '''''[[namespace]]s''''' that will be used in the document. | After any initial processing instruction (<?xml version="1.0" encoding="UTF-8"?> or similar) there will be the outer '''<description>''' element, which will typically also define a number of '''''[[namespace]]s''''' that will be used in the document. | ||
| Line 31: | Line 31: | ||
* The "target" namespace, which is often identical to the "tns" one: ="<span style="color:midnightblue;">targetNamespace="http://''yourDomain/yourService/serviceName''"</span> | * The "target" namespace, which is often 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 that 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 that is being referenced that is important, not the prefix used to represent it | 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 that 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 that 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 usually point to a <binding> element (see below) in the same WSDL document (and hence will tend to have the namespace prefix "tns": this | 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 usually 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. | ||
===The "''binding''" element=== | ===The "''binding''" element=== | ||
The '''binding''' element is what joins the physical implementation of the | 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. | ||
| Line 56: | Line 56: | ||
===The "''portType''" element=== | ===The "''portType''" element=== | ||
The '''portType''' element is the abstract representation of the service and is identified by its ''name'' attribute (what the ''type'' attribute of a ''binding'' | The '''portType''' element is the abstract representation of the service and is identified by its ''name'' attribute (what the ''type'' attribute of a ''binding'' element points to). | ||
It will contain a number of '''operation''' elements, one for each operation of the service. | It will contain a number of '''operation''' elements, one for each operation of the service. | ||
Each operation ''may'' contain a '''documentation''' element, describing the operation (in Visual DataFlex you can set this through the "{ Description = }" meta-data tag that | Each operation ''may'' contain a '''documentation''' element, describing the operation (in Visual DataFlex you can set this through the "{ Description = }" meta-data tag that precedes your published Function or Procedure). | ||
There will then be '''<input>''' and '''<output>''' elements, each of which will contain a ''message'' attribute, pointing to (the ''name'' attribute of) a '''message''' element (see below) which will hold the definition of that input or output message. Such message elements will usually appear within the same WSDL document and thus will commonly have the "tns" prefix. | There will then be '''<input>''' and '''<output>''' elements, each of which will contain a ''message'' attribute, pointing to (the ''name'' attribute of) a '''message''' element (see below) which will hold the definition of that input or output message. Such message elements will usually appear within the same WSDL document and thus will commonly have the "tns" prefix. | ||
| Line 72: | Line 72: | ||
===The "''types''" element=== | ===The "''types''" element=== | ||
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. | |||
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== | |||
To illustrate the above here is a sample of a very simple service WSDL, which we will then decompose. | |||
===The Full WSDL=== | |||
<?xml version="1.0" encoding="UTF-8" ?> | |||
<definitions xmlns="<nowiki>http://schemas.xmlsoap.org/wsdl/</nowiki>" | |||
xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema</nowiki>" | |||
xmlns:soap="<nowiki>http://schemas.xmlsoap.org/wsdl/soap/</nowiki>" | |||
xmlns:tns="<nowiki>http://unicorninterglobal.com/sample/" | |||
name="Hello" | |||
targetNamespace="http://unicorninterglobal.com/sample/</nowiki>"> | |||
<types> | |||
<xs:schema elementFormDefault="qualified" targetNamespace="<nowiki>http://unicorninterglobal.com/sample/</nowiki>"> | |||
<xs:element name="SayHello"> | |||
<xs:complexType> | |||
<xs:sequence> | |||
<xs:element name="sName" type="xs:string" /> | |||
</xs:sequence> | |||
</xs:complexType> | |||
</xs:element> | |||
<xs:element name="SayHelloResponse"> | |||
<xs:complexType> | |||
<xs:sequence> | |||
<xs:element name="SayHelloResult" type="xs:string" /> | |||
</xs:sequence> | |||
</xs:complexType> | |||
</xs:element> | |||
</xs:schema> | |||
</types> | |||
<message name="SayHelloSoapRequest"> | |||
<part name="parameters" element="tns:SayHello" /> | |||
</message> | |||
<message name="SayHelloSoapResponse"> | |||
<part name="parameters" element="tns:SayHelloResponse" /> | |||
</message> | |||
<portType name="HelloSoapType"> | |||
<operation name="SayHello"> | |||
<documentation>This operation says 'Hello!'</documentation> | |||
<input message="tns:SayHelloSoapRequest" /> | |||
<output message="tns:SayHelloSoapResponse" /> | |||
</operation> | |||
</portType> | |||
<binding name="HelloSoapBinding" type="tns:HelloSoapType"> | |||
<soap:binding style="document" transport="<nowiki>http://schemas.xmlsoap.org/soap/http</nowiki>" /> | |||
<operation name="SayHello"> | |||
<soap:operation soapAction="" style="document" /> | |||
<input> | |||
<soap:body use="literal" /> | |||
</input> | |||
<output> | |||
<soap:body use="literal" /> | |||
</output> | |||
</operation> | |||
</binding> | |||
<service name="Hello"> | |||
<documentation>Sample documentaion for the service</documentation> | |||
<port name="HelloSoap" binding="tns:HelloSoapBinding"> | |||
<soap:address location="<nowiki>http://localhost:8088/LutonWS/Hello.wso</nowiki>" /> | |||
</port> | |||
</service> | |||
</definitions> | |||
[[Category: Web Services]] [[Category:WIP]] | [[Category: Web Services]] [[Category:WIP]] | ||
