Building a service contract
A WSDL file is an XML file that describes one or more Web services. The description includes everything from the methods, or operations, available in the service to the schema for the messages that form the inputs and outputs of the operations.
If you're familiar with WSDL files or already have one that you want to use and don't care how they work, you can safely skip this section and move on to "Alternative: Import a WSDL file." But if you're new to WSDL files or have used them before, but would like a refresher, this section will be very helpful.
The ability to visually build WSDL files and XML Schema Definition (XSD) files in Eclipse should be a great help when building WSDL files in Eclipse. If you'd like, you can always switch the WSDL editor to Source mode to edit the source yourself. The WSDL file includes four major parts, which are described at a high level below and explored in greater detail in the rest of this section.
- This section of the WSDL file covers the types used in the Web service request and response messages.
- This contains the messages sent to and received from the Web service. In the visual Eclipse editor, they are shown as the input and output of the Web service operation.
- This lists the operations the Web service exposes.
- This includes the communication protocols the Web service uses.
- This describes the service or services exposed.
types element can contain information about the types
used in the SOAP messages. The types are conveniently described in XML schema, and you
can import other types. The Eclipse editor works well with both. One advantage of using
external schemas is that you can reuse complex types that have already been defined. In
contrast, an advantage of using inline (that is, inside the WSDL) schema is that your
WSDL file contains everything that needs to be known about the Web service.
Note: To keep things simple, this tutorial focuses on defining types in inline schema.
message element defines the messages sent in and
received from the operations. If you think of a Web service operation as being a method
in PHP code, the
message element describes the parameters
sent into the method and the return type that the method returns.
portType element describes the operations a Web service
exposes. If you think of a Web service, again, as a PHP class, the
portType element would be explaining the public methods the PHP class exposes.
binding element explains how the operations are exposed
in terms of which protocol is used to access them. In most of the examples you find,
the SOAP protocol is used to access Web service operations. However, other protocols may be used, such as HTTP.
service element describes the Web service, allowing you
to group similar operations in a collection of operations that make sense as a service.
Building or providing a WSDL file first, then writing the code to implement the service according to the WSDL file (contract) is called contract-first development. Building the contract before worrying about how you're going to implement it has a few advantages.
- Open implementation
- It leaves you free to implement the service however you see fit. As long as you comply with the contract, it doesn't matter if you build the Web service in the PHP, Java, Groovy, or any other language.
- Concurrent development
- If you build the contract first, you can give the contract out to your consumers so they can start developing clients to call the services. As long as you comply with the contract you've given to your consumers, you both can build your code concurrently. If you did bottom-up Web service development, in which you build the code first, then expose the contract for the service, other people are waiting for you to finalize your code base.
- Proper analysis
- Creating the contract first keeps you and your team honest by performing analysis up front because the analysis leads to the content of the contract. If you build the Web service from the bottom up, there's a greater likelihood that your service grows organically, and you could end up with a contract more specific to your implementation than you might intend.