Service descriptions (with WSDL)

When we covered loose coupling in Chapter 3 as part of our primitive SOA discussion, we introduced the essential need for service descriptions. This part of SOA provides the key ingredient to establishing a consistently loosely coupled form of communication between services implemented as Web services.

For this purpose, description documents are required to accompany any service wanting to act as an ultimate receiver. The primary service description document is the WSDL definition (Figure 5.14).

Figure 5.14. WSDL definitions enable loose coupling between services.

Note

Only WSDL concepts are discussed in this section. For WSDL language examples, see the WSDL language basics section in Chapter 13.

In Plain English

To provide Reconnect with the information it needs about Chuck, we are supplied with a brochure and a form. The brochure explains that:

1. The location service offered by Reconnect requires the completion of the form.
2. Once the form is received, the search will be performed.
3. Once the search has been completed, a response will be mailed out to us.

This form requires us to organize background details about Chuck into specific fields. We fill out the form and sign a disclaimer that states that though Reconnect will perform the search on our behalf, results cannot be guaranteed.

Collectively, the brochure and the form represent a service description vaguely similar to a WSDL definition. The WSDL establishes the terms of use for the service provider by defining exactly the information it requires to perform its service and also whether or not a response will be issued.

Case Study

For RailCo to design its B2B Web services in full compliance with the TLS services, RailCo acquires the WSDL service description published by TLS for their Accounts Payable Service. This definition file then is used by developers to build the Invoice Submission Service so that it can process SOAP messages in accordance with the service interface requirements defined in the TLS service descriptions.

Further, RailCo provides TLS with a copy of the WSDL definition for the RailCo Order Fulfillment Service. TLS registers this service description and adds it to the list of vendor endpoints that will receive electronic purchase orders. (Figure 5.15 illustrates both scenarios.)

Figure 5.15. Each service requestor is using the WSDL of a service provider to ensure that messages sent will be understood and accepted.

 

Note that because it is TLS that defines the terms of message exchange with other parties, RailCo developed both of its services to meet TLS's requirements.

The Invoice Submission Service was built as a service requestor that issues messages compliant with the Accounts Payable WSDL. The Order Fulfillment Service was designed as a service provider according to published specifications by TLS. This guarantees TLS that its Purchase Order Service (acting as a service requestor) can continue to issue messages in its current format and that all recipient endpoints will be able to receive and understand them.

 

5.3.1. Service endpoints and service descriptions

A WSDL describes the point of contact for a service provider, also known as the service endpoint or just endpoint. It provides a formal definition of the endpoint interface (so that requestors wishing to communicate with the service provider know exactly how to structure request messages) and also establishes the physical location (address) of the service.

Let's dig a bit deeper into how the service description document itself is organized. A WSDL service description (also known as WSDL service definition or just WSDL definition) can be separated into two categories:

• abstract description
• concrete description

Figure 5.16 shows how these individual descriptions comprise a WSDL definition. Note the logical hierarchy established within the parts of the abstract definition. We will explain each of these parts shortly.

Figure 5.16. WSDL document consisting of abstract and concrete parts that collectively describe a service endpoint.

 

5.3.2. Abstract description

An abstract description establishes the interface characteristics of the Web service without any reference to the technology used to host or enable a Web service to transmit messages. By separating this information, the integrity of the service description can be preserved regardless of what changes might occur to the underlying technology platform.

Below is a description of the three main parts that comprise an abstract description.

portType, operation, and message

The parent portType section of an abstract description provides a high-level view of the service interface by sorting the messages a service can process into groups of functions known as operations.

Each operation represents a specific action performed by the service. A service operation is comparable to a public method used by components in traditional distributed applications. Much like component methods, operations also have input and output parameters. Because Web services rely exclusively on messaging-based communication, parameters are represented as messages. Therefore, an operation consists of a set of input and output messages.

Note that the transmission sequence of these messages can be governed by a predetermined message exchange pattern that also is associated with the operation. (Message exchange patterns are discussed in Chapter 6.)

Note

The term "portType" is being renamed to "interface" in version 2.0 of the WSDL specification.

 

5.3.3. Concrete description

For a Web service to be able to execute any of its logic, it needs for its abstract interface definition to be connected to some real, implemented technology. Because the execution of service application logic always involves communication, the abstract Web service interface needs to be connected to a physical transport protocol. This connection is defined in the concrete description portion of the WSDL file, which consists of three related parts:

binding, port, and service

A WSDL description's binding describes the requirements for a service to establish physical connections or for connections to be established with the service. In other words, a binding represents one possible transport technology the service can use to communicate. SOAP is the most common form of binding, but others also are supported. A binding can apply to an entire interface or just a specific operation.

Related to the binding is the port, which represents the physical address at which a service can be accessed with a specific protocol. This piece of physical implementation data exists separately to allow location information to be maintained independently from other aspects of the concrete description. Within the WSDL language, the term service is used to refer to a group of related endpoints.

Note

The term "port" is being renamed "endpoint" in version 2.0 of the WSDL specification. The WSDL endpoint should not be confused with the general term "endpoint" used to reference the point of contact for a Web service. Though related, the term "endpoint" is used in a much broader sense than the WSDL endpoint, which refers to a language element that only represents the physical address of the service.

Case Study

The TLS Accounts Payable Service was created to receive invoices submitted by numerous vendors. Its associated service description therefore has a simple abstract description consisting of one interface definition that contains a single operation called SubmitInvoice.

Specified within the operation is one input and one output message. The input message is responsible for accepting the invoice document from a vendor service requestor (such as the RailCo Invoice Submission Service). The output message is used by the Accounts Payable Service to send a message of acknowledgement indicating that the submitted invoice document has been successfully received and that its contents are valid. The concrete part of this service description simply binds the operation to the SOAP protocol and provides a location address for the Accounts Payable Service.

 

5.3.4. Metadata and service contracts

So far we've established that the abstract and concrete descriptions provided by a WSDL definition express technical information as to how a service can be interfaced with and what type of data exchange it supports.

WSDL definitions frequently rely on XSD schemas to formalize the structure of incoming and outgoing messages. Another common supplemental service description document is a policy. Policies can provide rules, preferences, and processing details above and beyond what is expressed through the WSDL and XSD schema documents. (Policies are explained in Chapter 7.)

So now we have up to three separate documents that each describe an aspect of a service:

• WSDL definition
• XSD schema
• policy

Each of these three service description documents can be classified as service metadata, as each provides information about the service. Service description documents can be collectively viewed as establishing a service contracta set of conditions that must be met and accepted by a potential service requestor to enable successful communication.

Note that a service contract can refer to additional documents or agreements not expressed by service descriptions. For example, a Service Level Agreement (SLA) agreed upon by the respective owners of a service provider and its requestor can be considered part of an overall service contract (Figure 5.17).

Figure 5.17. A service contract comprised of a collection of service descriptions and possibly additional documents.

 

5.3.5. Semantic descriptions

Most of the metadata currently provided by services focuses on expressing technical information related to data representation and processing requirements. However, these service description documents generally do not prove useful in explaining details about a service's behavioral characteristics. In fact, the most challenging part of providing a complete description of a Web service is in communicating its semantic qualities.

Examples of service semantics include:

• how a service behaves under certain conditions
• how a service will respond to a specific condition
• what specific tasks the service is most suited for

Most of the time service semantics are assessed by humans, either verbally by discussing the qualities of a service with its owner, or by reading supplementary documentation published alongside service descriptions. The ultimate goal is to provide sufficient semantic information in a structured manner so that, in some cases, service requestors can go as far as to evaluate and choose suitable service providers independently.

Semantic information is usually of greater importance when dealing with external service providers, where your knowledge of another party's service is limited to the information the service owner decides to publish. But even within organizational boundaries, semantic characteristics tend to take on greater relevance as the amount of internal Web services grows.

Although service policies can be designed to express preferences and assertions that communicate aspects of service behavior, efforts are currently underway (primarily by the W3C) to continually extend the semantic information provided by service description documents. For the time being, we must focus on the service description capabilities offered to us through WSDL definitions, XSD schemas, and policies.

5.3.6. Service description advertisement and discovery

As we've established, the sole requirement for one service to contact another is access to the other service's description. As the amount of services increases within and outside of organizations, mechanisms for advertising and discovering service descriptions may become necessary. For example, central directories and registries become an option to keep track of the many service descriptions that become available. These repositories allow humans (and even service requestors) to:

• locate the latest versions of known service descriptions
• discover new Web services that meet certain criteria

When the initial set of Web services standards emerged, this eventuality was taken into account. This is why UDDI formed part of the first generation of Web services standards. Though not yet commonly implemented, UDDI provides us with a registry model worth describing.

Private and public registries

UDDI specifies a relatively accepted standard for structuring registries that keep track of service descriptions (Figure 5.18). These registries can be searched manually and accessed programmatically via a standardized API.

Figure 5.18. Service description locations centralized in a registry.

Public registries accept registrations from any organizations, regardless of whether they have Web services to offer. Once signed up, organizations acting as service provider entities can register their services.

Private registries can be implemented within organization boundaries to provide a central repository for descriptions of all services the organization develops, leases, or purchases.

Following are descriptions of the primary parts that comprise UDDI registry records.

Business entities and business services

Each public registry record consists of a business entity containing basic profile information about the organization (or service provider entity). Included in this record are one or more business service areas, each of which provides a description of the services offered by the business entity. Business services may or may not be related to the use of Web services.

Binding templates and tModels

You might recall that WSDL definitions stored implementation information separately from the actual interface design. This resulted in an interface definition that existed independently from the transport protocols to which it was eventually bound. Registry records follow the same logic in that they store binding information in a separate area, called the binding template.

Each business service can reference one or more binding templates. The information contained in a binding template may or may not relate to an actual service. For example, a binding template may simply point to the address of a Web site. However, if a Web service is being represented, then the binding template references a tModel. The tModel section of a UDDI record provides pointers to actual service descriptions (Figure 5.19).

Figure 5.19. The basic structure of a UDDI business entity record.

Note

UDDI language syntax is not covered in this book. For your reference, an introductory UDDI tutorial has been published at www.ws-standards.com/uddi.asp. Additional recommended reading is provided at www.serviceoriented.ws.

Case Study

At any given time there are several concurrent development and integration projects underway at TLS. Almost every project results in the creation of new services. Some are developed as part of service-oriented solutions, while others originate from legacy adapters and ancillary services appended to older distributed systems. The net result is a constantly growing pool of unmanaged services.

After a year-end review of past development initiatives, it was discovered that several project teams had inadvertently built Web services with very similar functionality. To avoid a recurrence of redundant effort, a private registry was created (Figure 5.20). Project teams responsible for any currently active service descriptions were required to register their services in the registry (and this registration process became part of the standard development lifecycle from there on).

Figure 5.20. The TLS service registry containing pointers to current TLS WSDL definitions.

SUMMARY OF KEY POINTS

• The WSDL definition is divided into two parts: the abstract description that defines the service interface, and the concrete description that establishes the transport and location information.
• The two other primary service description documents are XSD schemas and policies.
• Service descriptions can be dynamically discovered by humans or applications, using private or public service registries.