- 4.1 What is a Web Service Contract?
- 4.2 The Parts of a Web Service Contract
- 4.3 Technologies Used to Create Web Service Contracts
- 4.4 Guidelines for Using Web Service Contract Technologies
This chapter is from the book
This chapter is from the book
This chapter is from the book
4.2 The Parts of a Web Service Contract
Having just established a high-level structure of a Web service contract, let’s drill down a bit to explore how abstract and concrete descriptions are further sub-divided into smaller parts.
Primary Parts of the Abstract Description
Figure 4.3 provides us with a logical view of the parts that comprise the abstract description. This means that when this section of a contract is actually created, these parts will be physically structured differently (as shown later in the A Physical View of the Abstract Description section).
The following sections are numbered to correspond with the numbers on Figure 4.3.
)
Figure 4.3 A logical view of the primary parts of an abstract description.
1. Port Type (Interface) Definition
The definition of the port type is the cornerstone of a Web service contract. Think of a port as a place of entry (such as a port used to receive ships for transferring cargo). A Web service contract can have one or more “types” of ports. Each port type essentially represents a technical interface or access point.
Note that for reasons we’ll explain later, it is sometimes more appropriate to refer to the port type definition as the “interface definition.”
2. Operation Definition
For a Web service to be used by another program, it needs to expose externally consumable capabilities or functions. These are referred to as operations and are expressed as operation definitions.
A port type acts as a container for a set of related operations.
3. Message Definition
When a Web service is being invoked via one of its operations, the consumer program needs to exchange data with it in order for the Web service to perform the requested function. A message definition essentially establishes a “mini-structure” for the data to be transmitted.
There are three types of message definitions:
- Input–a message sent to the Web service by a consumer program
- Output–a message sent by the Web service to the consumer program
- Fault–an error notification message sent by the Web service to the consumer program
An operation can contain one or all of these message definitions but would generally not contain only an output or a fault message.
4. Type Definition
The data for a given input, output, or fault message needs to have a pre-defined structure of its own. That way, the Web service knows whether or not it is receiving or sending valid data. This data structure is established in a body type definition.
Messages further support the inclusion of message-specific metadata (information about the message that accompanies the message). For this form of supplementary data, a header type definition is also provided.
Finally, just as message transmissions can encounter error conditions, so can the processing of message metadata. Therefore, an additional headerfault type definition is available for when a response to a metadata-related error condition needs to be sent.
5. Policy Definition
All of the previous definitions in the abstract description have collectively defined the functional aspects of the Web service contract. Policy definitions can be created to extend the technical interface by expressing further behavioral requirements and characteristics of the service.
A Web service contract can have any number of supplementary policies. The horizontal arrows in Figures 4.3 and 4.4 indicate that polices can be specific to certain parts of the abstract description.
)
Figure 4.4 A physical view of the primary parts of an abstract description.
Note that polices can also be applied to parts of the concrete description.
A Physical View of the Abstract Description
So far we’ve been focusing on the logical view of the abstract description because it is conceptually important to understand it from this perspective. However, this is a book about technology, and the hundreds of pages that follow this chapter are all concerned with how Web service contracts are physically built.
Therefore, it’s time that we start learning about how the organization of the various definitions we’ve described so far differs in a real-world contract document. As shown in Figure 4.4, the purpose behind the physical structure is to promote reuse in support of flexible and normalized Web service contracts.
By following the numbers in Figure 4.4 we can trace back the actual location of the previously described definitions. While the port type definition (1) and policy definitions (5) are pretty much in the same place, we can see that the message definitions (3) and the type definitions (4) are no longer part of the port type or operation definitions (2).
Type and message definitions are positioned in separate parts of the contract so that they can be reused as follows:
- Each type definition can be used by multiple message definitions.
- Each message definition can be used by multiple operations (as input, output, and fault messages).
Although Figure 4.4 shows a series of available types, it does not make a distinction between a body, header, or headerfault type. All three types can exist as individual type definitions (4) but are then bundled together into one message definition (3). The body portion of this message is then associated with an input, output, or fault message as part of the operation definition (2).
WSDL 2.0 Changes to Physical View
We’ve intentionally avoided mentioning specific technologies so far in this chapter in order to establish as much of an abstract perspective of Web service contracts as possible. But it is worth noting that this book covers two different versions of the WSDL language used to express the Web service contract structure.
WSDL is explained later in this chapter. At this stage, we just need to point out that the physical view we just described complies with WSDL version 1.1. In version 2.0, the message definitions section (3) is removed, and operation definitions (2) refer directly to individual type definitions (4).
Primary Parts of the Concrete Description (Part I)
A concrete description supplements the abstract description with implementation-specific details required for the Web service to be invoked and communicated with by service consumer programs.
As we established earlier, the concrete description corresponds to the “how” and “where” sections of a Web service contract. We’ll focus on these sections individually, starting with the “how” considerations addressed by the binding-related definitions illustrated in Figure 4.5.
)
Figure 4.5 The primary parts of the binding portion of the concrete description. (Note that this represents both logical and physical views.)
The following sections are numbered to correspond with the numbers on Figure 4.5.
1. Port Type (Interface) Binding Definition
A binding definition details the communication technology that can be used by consumer programs to invoke and interact with the Web service.
A port type definition within an abstract description can be associated with one or more binding definitions, each of which contains the following two pieces of information:
- Messaging Protocol Binding–Defines a technology or industry standard (the message protocol) that specifies the format in which a message should be packaged by the sender and then unpackaged by the receiver.
- Transport Protocol Binding–Defines the communications technology (the transport protocol) with which the message should be transmitted across a network.
2. Operation Binding Definition
An operating binding definition represents the same type of binding definition as the port type binding, except that it is specific to the operation only. If the operation does not have this binding specified, it inherits the binding settings from its parent port type.
3. Message Binding Definitions
As with the operation binding, the message binding definition also represents a granular form of binding definition that, in this case, is specific to an input or output (or fault) message. If a message-specific binding is not provided, the message inherits the binding settings from its parent operation or its parent port type (if an operation binding is not present).
It is also here in the message binding definition that the header and headerfault parts of a message get associated with an input, output, or fault message that was defined in the abstract description. The reason again for making this association here is because not all message protocols support the use of header and headerfault parts.
4. Policy Definition
As with the definitions of an abstract description, policies can also be defined for the individual parts of a concrete description. Policies for binding definitions tend to be related to the configuration and runtime requirements of a particular messaging or transport protocol.
Primary Parts of the Concrete Description (Part II)
This final portion of the Web service contract structure focuses on the “where” section, as shown in Figure 4.6.
)
Figure 4.6 The primary parts of the service portion of the concrete description. (Note that this represents both logical and physical views.)
The following sections are numbered to correspond with the numbers on Figure 4.6.
1. Service Definition
The service definition simply groups related port (endpoint) definitions together. The port definition is explained shortly.
2. Port (Endpoint) Definition
Each binding definition needs to be associated with a port definition (also referred to as an endpoint definition), which simply acts as a container for the address definition (explained shortly). The same port definition can be used by different port type, operation, or message binding definitions.
3. Address Definition
An address definition establishes a physical network address. Depending on the communication technology (transport protocol) defined by the port type, operation, or message binding definition that is referencing the parent port definition for this address definition, the actual address value might be a Web URL, an email address, or some other type of transport-specific address.
4. Policy Definition
Policies can be created for address-related definitions in the concrete description. This may be necessary when certain requirements or characteristics specific to the network address need to be expressed.
How Parts of a Contract Relate to Each Other
As you may have already gathered, Web service contracts are highly modular. Let’s take a minute to describe some of the relationships these parts can have:
- On a high level, one abstract description can have one or more associated concrete descriptions, each specifying a different messaging and/or transport protocol.
- One port type (interface) definition can have multiple operation definitions.
- Each operation definition can reference multiple message definitions.
- Each message definition can reference multiple type definitions.
- One port type (interface) definition can be associated with multiple binding definitions.
- Each binding definition can have multiple port (endpoint) definitions.
- A service definition can group multiple port (endpoint) definitions.
- Policies can be applied to most of these definitions.
Figure 4.7 illustrates these relationships by providing an example of one port type definition that is associated with two port type binding definitions (relationship A), each with its own port definition (relationship B).
)
Figure 4.7 An example of how abstract and concrete descriptions can relate to each other. (Note that fault messages have been omitted from this diagram.)
Based on the numbers used in this diagram, we can further assume that the port type definition (1), the operation definition (2), and a message definition (3) each has its own corresponding binding definition. Also, the port type binding definition is associated with a port (4) that establishes its address.
These relationships are discussed in detail in subsequent chapters. At this point it’s just helpful for us to understand that various types of relationships can exist.
The Primary Parts of a Message
It’s important to remember that building Web service contracts is more than just creating an interface to underlying service logic. The contract defines, in a very specific manner, the actual interaction requirements of the Web service. And, as you may have gathered from the previous two sections, both abstract and concrete descriptions express these interaction requirements by defining input and output messages and the technologies used to support the processing of these messages.
Let’s therefore take the time to familiarize ourselves with the basic parts of a message. As shown in Figure 4.8, messages are wrapped in envelopes that have a basic structure of their own.
)
Figure 4.8 The fundamental structure of a message envelope.
Note that the following parts are not referred to as “definitions” because they represent an actual manifestation of what was established in the Web service contract definitions. In other words, runtime processors use the Web service contract definitions to generate these parts of the message (at runtime).
The following sections are numbered to correspond with the numbers on Figure 4.8.
1. Envelope
The scope of a message is defined by its envelope. This name is appropriate because it describes the message as a container of information. When discussing Web services, the terms “envelope” and “message” are frequently used interchangeably.
2. Body
The body represents a part of the message reserved for the data or the document being transported. Therefore, the type of information that usually resides within the message body is persistent in that its lifespan is greater than the time it takes for the message to be transmitted.
You’ll notice the body part containing the body type. This relates back to the body type definition established in the abstract description. That type definition determined the structure for this portion of the message envelope.
Because a message exists as an actual body of data that is being transmitted somewhere, the body type in the message envelope would typically be populated with real data (like an invoice document) organized as per the body type definition from the message definition of the abstract description.
3. Fault
A message can be solely intended as a notification from the Web service to a consumer program that an error has occurred. The details of the error are housed in the fault part of the message envelope, which resides within the body section.
The fault part also has a type associated with it. This type corresponds to the fault type definition that was part of the abstract description’s message definition.
4. Header
The header part of a message provides a location in which supplementary data about the message (metadata) can be stored. This data is usually temporary or non-persistent in nature in that its lifespan is generally equivalent to or shorter than the duration of the message transmission. A header allows metadata to be organized into sub-divided sections called header blocks.
Headers can contain many different types of header blocks, each dedicated to providing a distinct piece of supplementary data. This information is used by different programs to either help route a message or process its contents.
The first header block in Figure 4.8 is structured as per the header type definition that was established in the message definition of the abstract description. Similarly, the second header block is based on the headerfault type definition from the abstract description.