Chapter 4. Defining Your Logical Interfaces
Abstract
Logical service interfaces are defined using the
portType element.
Overview
Logical service interfaces are defined using the WSDL
portType element. The portType element is a collection of abstract operation definitions. Each operation is defined by the input, output, and fault messages used to complete the transaction the operation represents. When code is generated to implement the service interface defined by a portType element, each operation is converted into a method containing the parameters defined by the input, output, and fault messages specified in the contract.
Process
To define a logical interface in a WSDL contract you must do the following:
- Create a
portTypeelement to contain the interface definition and give it a unique name. See the section called “Port types”. - Create an
operationelement for each operation defined in the interface. See the section called “Operations”. - For each operation, specify the messages used to represent the operation’s parameter list, return type, and exceptions. See the section called “Operation messages”.
Port types
A WSDL
portType element is the root element in a logical interface definition. While many Web service implementations map portType elements directly to generated implementation objects, a logical interface definition does not specify the exact functionality provided by the the implemented service. For example, a logical interface named ticketSystem can result in an implementation that either sells concert tickets or issues parking tickets.
The
portType element is the unit of a WSDL document that is mapped into a binding to define the physical data used by an endpoint exposing the defined service.
Each
portType element in a WSDL document must have a unique name, which is specified using the name attribute, and is made up of a collection of operations, which are described in operation elements. A WSDL document can describe any number of port types.
Operations
Logical operations, defined using WSDL
operation elements, define the interaction between two endpoints. For example, a request for a checking account balance and an order for a gross of widgets can both be defined as operations.
Each operation defined within a
portType element must have a unique name, specified using the name attribute. The name attribute is required to define an operation.
Operation messages
Logical operations are made up of a set of elements representing the logical messages communicated between the endpoints to execute the operation. The elements that can describe an operation are listed in Table 4.1, “Operation message elements”.
| Element | Description |
|---|---|
input | Specifies the message the client endpoint sends to the service provider when a request is made. The parts of this message correspond to the input parameters of the operation. |
output | Specifies the message that the service provider sends to the client endpoint in response to a request. The parts of this message correspond to any operation parameters that can be changed by the service provider, such as values passed by reference. This includes the return value of the operation. |
fault | Specifies a message used to communicate an error condition between the endpoints. |
An operation is required to have at least one
input or one output element. An operation can have both input and output elements, but it can only have one of each. Operations are not required to have any fault elements, but can, if required, have any number of fault elements.
The elements have the two attributes listed in Table 4.2, “Attributes of the input and output elements”.
| Attribute | Description |
|---|---|
name | Identifies the message so it can be referenced when mapping the operation to a concrete data format. The name must be unique within the enclosing port type. |
message | Specifies the abstract message that describes the data being sent or received. The value of the message attribute must correspond to the name attribute of one of the abstract messages defined in the WSDL document. |
It is not necessary to specify the
name attribute for all input and output elements; WSDL provides a default naming scheme based on the enclosing operation’s name. If only one element is used in the operation, the element name defaults to the name of the operation. If both an input and an output element are used, the element name defaults to the name of the operation with either Request or Response respectively appended to the name.
Return values
Because the
operation element is an abstract definition of the data passed during an operation, WSDL does not provide for return values to be specified for an operation. If a method returns a value it will be mapped into the output element as the last part of that message.
Example
For example, you might have an interface similar to the one shown in Example 4.1, “personalInfo lookup interface”.
Example 4.1. personalInfo lookup interface
interface personalInfoLookup
{
personalInfo lookup(in int empID)
raises(idNotFound);
}
This interface can be mapped to the port type in Example 4.2, “personalInfo lookup port type”.
Example 4.2. personalInfo lookup port type
<message name="personalLookupRequest">
<part name="empId" element="xsd1:personalLookup"/>
<message/>
<message name="personalLookupResponse">
<part name="return" element="xsd1:personalLookupResponse"/>
<message/>
<message name="idNotFoundException">
<part name="exception" element="xsd1:idNotFound"/>
<message/>
<portType name="personalInfoLookup">
<operation name="lookup">
<input name="empID" message="tns:personalLookupRequest"/>
<output name="return" message="tns:personalLookupResponse"/>
<fault name="exception" message="tns:idNotFoundException"/>
</operation>
</portType>