|
|
|
 Introduction: |
You've made it this far through the drudgery and the good news is you are almost ready to pick up a programming language and try out apnscp esprit.
Let's recap what we know thus far:
- A client sends a request to the server in the form of a SOAP envelope
- The server examines the operation, performs it, and ships the data back to the client
- Data sent between the client/server is handled differently based upon the data type used
We know how the whole process works except for one critical question:
How does the server know if a command is valid and how does it know
what parameters it should expect, if any?
That is the where the WSDL chips in.
|
|
|
| A Basic WSDL: |
In an effort to avoid overkill, we're going to take a look at a very, very, very basic WSDL file. These define the style and structure of a SOAP request.
<?xml version="1.0" ?>
<wsdl:definitions
name="net.esprit.soap"
targetNamespace="urn:net.esprit.soap"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="urn:net.esprit.soap"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:s="http://www.w3.org/2001/XMLSchema">
<wsdl:types xmlns="http://schemas.xmlsoap.org/wsdl/" />
<message name="common_get_disk_quota_request">
</message>
<message name="common_get_disk_quota_response">
<part name="return" type="xsd:struct" />
</message>
<portType name="common_port">
<operation name="common_get_disk_quota">
<input message="tns:common_get_disk_quota_request" />
<output message="tns:common_get_disk_quota_response" />
</operation>
</portType>
<binding name="common_binding" type="tns:common_port">
<operation name="common_get_disk_quota">
<soap:operation soapAction="urn:net.esprit.soap#common_get_disk_quota" />
<input>
<soap:body use="encoded" namespace="urn:net.esprit.soap"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded" namespace="urn:net.esprit.soap"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>
<service name="common_service">
<documentation />
<port name="common_port" binding="tns:common_binding">
<soap:address location="urn:net.esprit.soap" />
</port>
</service>
</wsdl:definitions>
Looks pretty scary and daunting? Don't worry, it isn't. Here's the main elements that you need to know:
|
|
|
| "message": |
The message element informs the SOAP client and SOAP server what parameters it's expecting from the client and what parameters the server should return.
This acts as a guide if you will for sending the data. In our now infamous common_get_disk_quota operation, you see there is no part child element for
common_get_disk_quota_request. This means that the operation should receive no additional parameters, i.e. it will be invoked as common_get_disk_quota().
The other message element defined in the WSDL is "common_get_disk_quota_response". Looking at the part child element, we see first that it exists
and it has an attribute called type. type just says how the parameter (or return value) should be rendered. It's xsd:struct, which means it should be treated
as an array with multiple values. Most languages render xsd:struct types as hashes with a key => value notation.
|
|
|
| "service" & "port": |
service elements contain several closely related ports and can be thought of almost as clases. They are there for the
grouping only.
ports are a more specific collection of operations. They contain child elements named operation with an attribute name.
These values in the name attribute are the functions that you call directly from your SOAP client. input and output children
simply refer to what message should be used in calling the operation.
|
|
|
| Wrap-up: |
That's all you really need to know when deciphering a WSDL. Those three elements make up the essential information you need to know in order to write a script
that successfully queries the SOAP server and retrieves the data. Of course you also see binding in the mix, but that merely dictates the style
to be used during invocation — not essential for what you're trying to do.
Here's a quick diagram to explain the relationship between all the components:
And that's all there is to esprit! Let's get to the fun stuff: authenticating and per-language implementations.
|
|
Links:
