Patterns from SOA Design Patterns by Thomas Erl, Part 1

The first draft of SOA Design Patterns had 60 patterns that were reviewed by more than 100 selected SOA specialists from all over the world. During the same time the draft was subject to public review on soapatterns.org. The SOA community was invited to contribute with their own patterns, ones they had used and had been validated in production. The response led to a collection of 34 new patterns. The end result was a catalog of 85 individual and compound patterns plus 28 candidate patterns – as today - subject to further review and validation by the SOA community. These patterns can be used as guidelines for solid SOA design and implementation. In this article we present 3 Inventory Governance Patterns from chapter 10 of the book: Canonical Expression, Metadata Centralization, and Canonical Versioning.

When first designing a service inventory, there are steps that can be taken to ensure that the eventual effort and impact of having to govern the inventory is reduced. This chapter provides a set of patterns that supply some fundamental design-time solutions specifically with the inventory’s post-implementation evolution in mind.

Canonical Expression (275) refines the service contract in support of increased discoverability, which goes hand-in-hand with Metadata Centralization (280), a pattern that essentially establishes a service registry for the discovery of service contracts. These patterns are further complemented by Canonical Versioning (286), which requires the use of a consistent, inventory-wide versioning strategy.

All of these patterns are considered fundamental to inventory governance in that they support and are influenced by the Service Discoverability principle, which actually shapes service meta information in such a manner that it can be effectively discovered and interpreted.

Note - The governance patterns in this chapter focus on fundamental technical and design-related governance issues only. The upcoming title SOA Governance as part of this book series will provide a collection of additional technical and organizational best practices and patterns.

Canonical Expression

How can service contracts be consistently understood and interpreted?

Table 10.1
Profile summary for the Canonical Expression pattern.

Problem

Service contracts delivered or extended by different projects and at different times are naturally shaped by the architects and developers that work with them. The manner in which the service context and the service’s individual capabilities are defined and expressed through the contract syntax can therefore vary. Some may use descriptive and verbose conventions, while others may use terse and technical formats. Furthermore, the actual terms used to express common or similar capabilities may also vary.

Because services are positioned as enterprise resources, it is fully expected that other project teams will need to discover and interpret the contract in order to understand how the service can be used. Inconsistencies in how technical service contracts are expressed undermine these efforts by introducing a constant risk of misinterpretation (on a technical level). The proliferation of these inconsistencies furthermore places a convoluted face on a service inventory, increasing the effort to effectively navigate various contracts to study possible composition design options.

Solution

Standardized naming conventions can be applied to the delivery of all service contracts so as to ensure the consistent expression of service contexts and capabilities (Figure 10.1).

Figure 10.1
The expression of service contracts is aligned across services.

Application

A set of naming and functional expression conventions needs to be established as formal design standards. The realization of consistent contract design is then attained via the disciplined use of these conventions within common analysis and design processes.

An example of a standard associated with contract expression is the CRUD (create, read, update, delete) convention traditionally used to outfit components with a predictable set of methods. Entity services in particular often require these types of data processing functions, and using standardized verbs to express them supports the application of this pattern.

With Web services in particular, this pattern will tend to impact the design of WSDL definitions, as illustrated in Figure 10.2.

Figure 10.2
The WSDL definitions of the four services are affected by Canonical Expression.

Note - This pattern can be applied regardless of whether the service contract is decoupled.

Impacts

The relevance of Canonical Expression may at first appear trivial. However, when building a collection of services, especially within larger enterprise environments, a consistent functional expression significantly reduces tangible risk factors.

The primary requirement to successfully applying this pattern is the incorporation and enforcement of the required design standards. If a formal design process has already been established in support of Decoupled Contract (401) and Canonical Schema (158), then the effort to include a step dedicated to Canonical Expression is usually minor.

Note also that unlike Canonical Schema (158), which often must be limited to domain service inventories due to its governance impact, this pattern can more easily be positioned as an enterprise-wide standard. This benefits the enterprise as a whole as consistent expression is established across all domains.

Relationships

The naming conventions introduced by Canonical Expression influence how several other patterns are applied (as listed at the top of Figure 10.3). This pattern fundamentally supports the goals of Contract Centralization (409) and Metadata Centralization (280) by enhancing the intuitiveness of service identification and reuse.

Figure 10.3
Canonical Expression keeps the external expression of service contracts consistent, thereby affecting contract and context-related patterns.

Case Study Example

An early pilot version of the Inventory Processing service has been used for testing purposes. It consists of a Web service that was auto-generated using a development tool that derived the Web service contract from component class interfaces that exist as part of the custom legacy inventory management system.

Although this Web service has been valuable for various assessment purposes, once architects take a closer look at the actual Web service contract code, they detect some content that raises concerns:

• The Web service operations inherited the cryptic legacy component method names.
• Several of the Web service operations have input and output message schemas that are derived from input and output legacy method parameters that are too granular for message-based service interaction.
• There is no real concept of an inventory record because it was not supported within the legacy component API.

These and other issues prompt Cutit to move ahead with a formal design process that requires the definition of service contracts prior to the development of underlying logic. This design process is completed subsequent to a formal analysis and modeling process during which architects collaborate with business analysts to define conceptual service candidates. These candidates then form the basis of the physical service designs.

Architects and developers can now avoid irregularities and problematic characteristics within service contracts because they have gained control of the definition of these contracts.

Metadata Centralization

How can service metadata be centrally published and governed?

Table 10.2
Profile summary for the Metadata Centralization pattern.

Problem

When growing a service inventory and fostering fundamental qualities such as those realized by Service Normalization (131) and Logic Centralization (136), there is a constant risk of project teams inadvertently (or sometimes even intentionally) delivering new services or service capabilities that already exist or are already in development (Figure 10.4).

Figure 10.4
Without an awareness of the full range of existing and upcoming services, there is a constant risk that project teams will deliver service logic that already exists or is already in development.

This leads to undesirable results, most notably:

• the introduction of redundant service logic, which runs contrary to Logic Centralization (136)
• the introduction of overlapping service contexts, which runs contrary to Service ­Normalization (131)
• an overall less effective service inventory and technology architecture, bloated and convoluted by the added redundancy and denormalization and in need of additional governance effort

All of these characteristics can undermine an SOA initiative by reducing its strategic benefit potential.

Solution

A service registry is established as a central part of the surrounding infrastructure and is used by service owners and designers to:

• register existing services and capabilities
• register services and capabilities in development

As emphasized in discovery-related governance patterns, the registration process requires that discovery information be recorded in a highly descriptive and communicative manner so that it can be used by project teams to:

• locate and interpret existing services and learn about their functional contexts and boundaries
• locate and interpret service capabilities and learn about their invocation and interaction requirements

By providing a current and well-maintained registry of service contexts and capabilities, effective service discovery can be achieved (Figure 10.5).

Figure 10.5
The fundamental discovery process during which a human locates a potential service via a service registry representing the service inventory and then interprets the service to determine its suitability.

Note - Metadata Centralization is clearly a design pattern associated with the Service Discoverability design principle and the discovery of services in general. Why then is it not simply called Service Discovery?

Service discovery itself is a process that is carried out once an enterprise has successfully applied Metadata Centralization to its architecture and the Service Discoverability design principle to its services. The process of service discovery is therefore related to a set of SOA governance patterns documented separately in the upcoming title SOA Governance that will be released as part of this book series.

Application

The application of this pattern requires the following common steps:

1. Regularly apply the Service Discoverability principle to all service contracts being modeled and designed.
2. Use service profiles and supporting processes to standardize the documentation of service and capability metadata. For example, a common part of service profiles is a standard vocabulary used for keywords that are attached to the service registry records.
3. Implement a reliable service registry product and position it as a standard part of the supporting infrastructure.

Finally, formal processes for the registration and discovery of services and capabilities need to be established.

Note - This pattern can be applied to a single service inventory or multiple domain inventories, depending on the ability of the service registry product to associate domains with service profile records. For a service profile template and descriptions of service discovery and interpretation processes, see Chapters 16 and 12, respectively, in SOA Principles of Service Design.

Impacts

Service registration and discovery processes are key success factors for the effective governance of a service inventory. If the processes are not respected or followed consistently by project teams or if the registry is not kept current, then the value potential of Metadata Centralization will severely diminish.

From a design perspective, however, this pattern will introduce the need for metadata standardization, as per the Service Discoverability principle. It will further require that metadata documentation and registration become part of the standard service delivery lifecycles.

There may further be a need to create a new organizational role in support of realizing Metadata Centralization. A person or a group would act as service registry custodian and assume responsibility for collecting the required metadata and maintaining the registry.

Relationships

Metadata Centralization essentially establishes a service registry, which is key to ensuring the long-term successful application of Logic Centralization (136) and Contract Centralization (409). If the correct services and their contracts can be effectively located (discovered), then the risk of inadvertently introducing redundant logic into an environment is reduced, further supporting Service Normalization (131).

Agnostic services represent the primary type of service for which metadata needs to be centralized for discovery purposes, which is why this pattern is especially relevant to services defined as a result of Entity Abstraction (175) and Utility Abstraction (168).

Figure 10.6
Metadata Centralization facilitates discovery and therefore relates to other patterns that rely on design-time awareness in order to be consistently applied.

Case Study Example

As explained in the Logic Centralization (136) example from Chapter 6, the original functional overlap between the Alleywood Areas and Region services could have gone undetected, resulting in the quality and integrity of the service inventory being negatively affected. For this reason, it was determined early on that a service registry would be required to support Service Normalization (131) and ensure the consistent application of Logic Centralization (136).

However, due to the decision to establish separate domain service inventories, architects struggle with the option of implementing a separate service registry for each inventory. Although it would continue to allow each group to govern their respective service collection independently, it would establish two different repositories.

It is anticipated that Alleywood and Tri-Fold services will need to interoperate. Those creating cross-inventory compositions will therefore need to issue separate queries in order to discover the required service capabilities.

The awkwardness of this governance architecture eventually prompts McPherson to establish a central enterprise service registry instead (Figure 10.7). This registry is governed by the McPherson Enterprise Group and allows Alleywood and Tri-Fold project teams to search each others’ inventories.

Figure 10.7
A global registry that spans services across Alleywood and Tri-Fold inventories.

Canonical Versioning

How can service contracts within the same service inventory be versioned with minimal impact?

Table 10.3
Profile summary for the Canonical Versioning pattern.

Problem

When service contracts within the same service inventory are subjected to different versioning approaches and conventions, post-implementation contract-level disparity emerges, compromising interoperability and effective service governance Figure 10.8). This can negatively impact design-time consumer development, runtime service access, service reusability, and the overall evolution of the service inventory as a whole.

Figure 10.8
Services that have been versioned differently become challenging to compose and interoperate and also difficult to interpret.

Solution

Service contracts within the same inventory are versioned according to the same conventions and as part of the same overall versioning strategy (Figure 10.9). This ensures a consistent governance path for each service, thereby preserving contract standardization and intra-inventory compatibility and interoperability.

Figure 10.9
When services are versioned according to the same overarching strategy, they can retain their original standardization and interoperability and are more easily understood by consumer designers.

Application

This pattern generally requires that a single versioning strategy be chosen, comprised of a series of rules and conventions that essentially become governance standards.

Canonical Versioning approaches can vary depending on the complexion of the enterprise, existing versioning or configuration management methodologies that may already be in place, and the nature of the overall governance strategy that may have also been ­established.

There are three common strategies that provide a baseline set of rules:

• Strict – Any compatible or incompatible change results in a new version of the service contract. This approach does not support backwards or forwards compatibility and is most commonly used when service contracts are shared between partner organizations and when changes to a contract can have legal implications.
• Flexible – Any incompatible change results in a new version of the service contract, and the contract is designed to support backwards compatibility but not forwards compatibility.
• Loose – Any incompatible change results in a new version of the service contract and the contract is designed to support backwards compatibility and forwards compatibility.

Note - The terms “backwards compatibility" and “forwards compatibility" are explained in the description for Compatible Change (465) in Chapter 16. For examples of each of these versioning strategies, see Chapters 20–23 in Web Service Contract Design and Versioning for SOA.

Impacts

There is the constant risk that project teams will continue to use their own versioning approaches, or rely too heavily on patterns like Concurrent Contracts (421), which allows them to simply add new contracts to an existing service.

The successful application of any versioning strategy will require strong support for the adherence to its rules and conventions to the extent that the chosen versioning approach becomes an inventory-wide standard on par with any other design standard. This introduces the need for a new organizational role that is tasked with enforcing the processes and syntactical characteristics that are defined as part of the strategy.

Relationships

Canonical Versioning essentially formalizes the application of Compatible Change (465), Version Identification (472), and Termination Notification (478), in that the overarching strategy established by this pattern will determine how and to what extent each of these more specific versioning patterns is applied.

The application of Metadata Centralization (280) results in a service registry that enables effective discovery of different contract versions and Canonical Expression (275) implements characteristics in service contracts that improve their legibility. Both of these patterns therefore aid the goals of Canonical Versioning.

Figure 10.10
Canonical Versioning is primarily related to other versioning patterns.

Note - Before continuing with this case study example, be sure to read up on the Policy Check service that was defined in the State Repository (242) case study example and then later positioned to support multiple inventories as part of the example for Cross-Domain Utility Layer (267).

Case Study Example

The FRC announced that due to new government legislation, it has revised some of its policies. This changes the policy data that was being made available electronically via its public Web services.

The Alleywood Policy Check service was originally positioned to shield the rest of the Alleywood service inventory from these types of changes by providing the sole access point for FRC policy data. Although its service logic can be augmented to accommodate changes to the FRC services, architects soon realize that they cannot prevent having to issue a new version of the Policy Check contract because the FRC has added new content and structure into their policy schemas.

Being the first time they’ve had to contend with a major versioning issue, the Alleywood team decides that some formal approach needs to be in place before they proceed. After some research into common versioning practices and further deliberation, they produce a versioning strategy comprised of a set of specific conventions and rules:

Version Identification (472) will be applied as follows:

• Version information will be expressed in major numbers displayed left of the decimal point and minor version numbers displayed to the right of the decimal point (e.g., “1.0").
• Minor and major contract version numbers will be expressed using the WSDL ­documentation element by displaying the word “Version" before the version number (e.g., <documentation>Version 1.0</documentation>)
• Major version numbers will be appended to the WSDL definition’s target namespace and prefixed with a “v" as shown here: http://alleywoodlumber/contract/po/v1

Compatible Change (465) will be applied as follows:

• A compatible change in the WSDL definition increments the minor version number and does not change the WSDL definition target namespace.
• A compatible change in the XML Schema definition increments the minor version number and does not change the XML Schema or WSDL definition target ­namespaces.
• An incompatible change in the WSDL definition increments the major version number and forces a new WSDL target namespace value.
• An incompatible change in the XML Schema definition increments the major version number and forces a new target namespace value for both the XML Schema and WSDL definitions.

The previously described scenario results in a set of incompatible changes that requires that the major version number of the Policy Check service contract be incremented from 1.0 to 2.0.

This example demonstrates the beginning of the Policy Check XML Schema and WSDL definitions after this change has occurred:

<xsd:schema xmlns:xsd=
  "http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://alleywoodlumber/schema/pc/v2"
  xmlns="http://alleywoodlumber/schema/pc/v2"
  version="2.0">
  <xsd:annotation>
    <xsd:documentation>
      Version 2.0
    </xsd:documentation>
  </xsd:annotation>
  ...
</xsd:schema>

<definitions name="Policy Check" targetNamespace=
  "http://alleywoodlumber/contract/pc/v2"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://alleywoodlumber/contract/pc/v2"
  xmlns:pc="http://alleywoodlumber/schema/pc/v2"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <documentation>
    Version 2.0
  </documentation>
  ...
</definitions>

Example 10.1
Fragments from the Policy Check Web service contract documents that show the effects of applying a versioning strategy.

The Alleywood architects acknowledge that defining the versioning approach is only the first step. In order for Canonical Versioning to be fully realized, these new rules and standards must be applied to any future service contracts that need to be versioned. This leads to the creation of a new process that is placed under the jurisdiction of the governance group.

This chapter is an excerpt from the book, SOA Design Patterns, authored by Thomas Erl, with additional contributors, published by Prentice Hall in January 2009 as part of The Prentice Hall Service-Oriented Computing Series from Thomas Erl, ISBN 0136135161, Copyright 2009 SOA System Inc. For more info please visit informit.com/soa or soapatterns.org.