Incorporating service-oriented design principles into formal standards is critical to the success of SOA within an organization. Provided in this section is a set of guidelines that can be used as a starting point from which you can derive your own standards.
15.5.1. Apply naming standards
Labeling services is the equivalent to labeling IT infrastructure. It is therefore essential that service interfaces be as consistently self-descriptive as possible.
Naming standards therefore need to be defined and applied to:
Existing naming conventions vary by organization. Some employ OO naming standards where objects are assigned nouns and methods are labeled with verbs. Others simply apply verbs to both components and their methods. Although it would be very useful, there is no perfect naming standard for all organizations. The key is that whatever standards you choose must be implemented consistently throughout all service-oriented solution environments.
Here are some suggestions:
15.5.2. Apply a suitable level of interface granularity
As evidenced by the case study examples in this chapter, the granularity at which services can be designed can vary. The trend to create interfaces for Web services that are coarser than those traditionally designed for RPC-based components has been encouraged by vendors as a means of overcoming some of the performance challenges associated with XML-based processing.
Performance, of course, is critical to the success and ultimate evolution of service-oriented solutions. However, other considerations also need to be taken into account. The coarser the granularity of an interface, the less reuse it may be able to offer. If multiple functions are bundled into a single operation, it may be undesirable for requestors who only require the use of one of those functions. Additionally, some coarse-grained interfaces may actually impose redundant processing or data exchange by forcing requestors to submit data not relevant to a particular activity.
Service interface granularity is a key strategic decision point that deserves a good deal of attention during the service-oriented design phase. Here are some guidelines for tackling this issue:
Regardless of your approach, ensure that it is consistent and predictable so that an SOA can meet performance demands while remaining standardized.
TLS chose an approach to interface granularity where services positioned for use by requestors outside of TLS would provide consistently coarse-grained interfaces. Operations on these services would accept all of the data required to process a particular activity. Further round-trips between external requestor and the service would only be required if absolutely necessary or if internal policies demanded it.
Services used within TLS could provide less coarse-grained operations to facilitate reuse and a broader range of potential (internal) requestors, as long as the processing overhead imposed by less coarse-grained operations was acceptable.
15.5.3. Design service operations to be inherently extensible
Regardless of how well services are designed when first deployed, they can never be fully prepared for what the future holds. Some types of business process changes result in the need for the scope of entities to be broadened. As a result, corresponding business services may need to be extended. While service characteristics such as reusability and composability are thought through when partitioning logic as part of the service modeling process, extensibility is more of a physical design quality that needs to be considered during design.
Depending on the nature of the change, extensibility can sometimes be achieved without breaking the existing service interface. It is important to design operations and messages to be as activity-agnostic as possible. This supports the processing of future non-specific values and functions that are still related to the operation's or message's overall purpose. Further, it is a good habit to respond to new processing requirements by first investigating the possibility of composing other available services (including services that can be purchased or leased). This may succeed in fulfilling requirements without having to touch the service interface.
Note that extensions to an existing service interface will impact the corresponding XSD schema. These extensions can be facilitated by supplying new schemas specifically for the extension. Before going down this road, though, ensure that established version control standards are firmly in place.
Due to the size of the TLS corporation, it is not uncommon for employees to be reallocated or to seek vertical or lateral position changes. The latter scenario is made further common by the "promote from within" motto encouraged by many divisional directors.
When an employee changes position or rank, the employee is expected to update his/her own profile using a form on the local intranet. Because this step is voluntary, it is often never performed. This, predictably, results in an increasingly out-of-date set of profiles. To counter this trend, the TLS Timesheet Submission Process is altered to include an employee profile verification step. Once implemented, it will verify profile information prior to accepting a timesheet. Timesheets submitted by employees with invalid profiles will simply be rejected.
To implement this new requirement, the Timesheet Service interface is not altered. Instead, the underlying service logic is extended to incorporate a separate application service that performs the profile verification.
15.5.4. Identify known and potential service requestors
Services are almost always built as part of the delivery of a specific automation solution. Therefore, they are designed to address business requirements as they pertain to that application. Limiting a service design to fulfill immediate requirements can inhibit its potential as a reusable, adaptive, and interoperable unit of processing logic.
It is therefore advisable that any existing service design process incorporate a speculative analysis of how that service may be utilized outside its initial application boundaries. In other words, it can be useful and practical to identify any potential future service requestors and to then incorporate their anticipated requirements into the current service design.
This can lead to additional functional requirements, which may or may not be desirable, depending on the current project scope, budget, and other related constraints. More importantly, though, this can lead to design refinements that may not significantly impact the current project at all. For example, it may be possible to adjust the granularity of service interfaces at the design stage without much impact to the overall project.
15.5.5. Consider using modular WSDL documents
WSDL service descriptions can be assembled dynamically at runtime through the use of import statements that link to separate files that contain parts of the service definition. This allows you to define modules for types, operations, and bindings that can be shared across WSDL documents.
It also allows you to leverage any existing XSD schema modules you may already have designed. Many organizations separate schemas into granular modules that represent individual complex types. This establishes a centralized repository of schemas that can be assembled into customized master schema definitions. By enabling you to import XSD schema modules into the types construct of a WSDL definition, you now can have your WSDL documents use those same schema modules.
Incidentally, the WS-I Basic Profile requires that when designing modular WSDL definitions, the import statement be used to import other WSDL definitions or XSD schemas.
TLS considers importing the bindings construct so that it can be reused and perhaps even dynamically determined. However, it is later decided to leave the bindings construct as part of the WSDL document. Here is the import statement used to carry out this test:
Example 15.22. An import element used to pull in the bindings construct residing in a separate file.
15.5.6. Use namespaces carefully
A WSDL definition consists of a collection of elements with different origins. Therefore, each definition often will involve a number of different namespaces. Following is a list of common namespaces used to represent specification-based elements:
When assembling a WSDL from modules, additional namespaces come into play, especially when importing XSD schema definitions. Further, when defining your own elements, you can establish more namespaces to represent application-specific parts of the WSDL documents. It is not uncommon for larger WSDL documents to contain up to ten different namespaces and the qualifiers to go along with them. Therefore, it is highly recommended that you organize the use of namespaces carefully within and across WSDL documents.
The WS-I Basic Profile requires the use of the targetNamespace attribute to assign a namespace to the WSDL as a whole. If the XSD schema is embedded within the WSDL definition, then the WS-I Basic Profile requires that it also be assigned a targetNamespace value (which can be the same value used by the WSDL targetNamespace).
Some of the common namespaces identified earlier are not required by the TLS Employee Service and therefore are omitted from the list of definitions attributes. A targetNamespace is added, along with two namespaces associated with the two imported schemas.
Example 15.23. The namespace declarations within the definitions element of the TLS Employee.wsdl file.
targetNamespace="http://www.xmltc.com/tls/employee/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:act= "http://www.xmltc.com/tls/employee/schema/accounting/" xmlns:hr="http://www.xmltc.com/tls/employee/schema/hr/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.xmltc.com/tls/employee/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> ...
15.5.7. Use the SOAP document and literal attribute values
There are two specific attributes that establish the SOAP message payload format and the data type system used to represent payload data. These are the style attribute used by the soap:binding element and the use attribute assigned to the soap:body element. Both of these elements reside within the WSDL binding construct.
How these attributes are set is significant as it relates to the manner in which SOAP message content is structured and represented:
When considering these two attributes, the following four combinations are possible and supported by SOAP:
The style:document + use:literal combination is preferred by SOA because it supports the notion of the document-style messaging model that is key to realizing the features of many key WS-* specifications. Further, the WS-I Basic Profile requires that the use attribute always be set to "literal."
In building the concrete part of the Employee Service interface definition, TLS architects decide to use the style:document + use:literal combination, as shown here:
Example 15.24. The binding construct of the TLS Employee.wsdl document.
15.5.8. Use WS-I Profiles even if WS-I compliance isn't required
If WS-I compliance is not on your list of immediate requirements, it still is recommended that you consider using the many standards and best practices provided by the Basic Profile document. They are sound, well researched, and proven and can save you a great deal of time and effort when developing your own design standards.
Another WS-I deliverable we have not covered in this book is the Basic Security Profile, which governs and standardizes the use of security-related specifications for interoperability purposes. Visit www.ws-i.org for more information.
15.5.9. Document services with metadata
As evidenced by the discussions we had about WS-Policy and WS-MetadataExchange in Chapter 7, the WS-* platform is placing an ever-increasing amount of emphasis on the quality and depth of service descriptions. It won't be uncommon, though, for many SOAs to exist without the benefit of a technical environment capable of supporting service description content beyond that provided by WSDL definitions.
Policies in particular represent an important metadata supplement to WSDL definitions. For example, a policy may express certain security requirements, processing preferences, and behavioral characteristics of a service provider. This allows service requestors to better assess a service provider and offers them the opportunity to be fully prepared for interaction.
Polices are formally implemented using a set of WS-* specifications described in Chapter 7. Regardless of whether these specifications actually are used in an organization, policy information should still be documented as part of any service design. This not only provides developers building service requestors for a given service provider a great deal of useful information, it also accommodates an eventual move to when policies become a common part of service-oriented architectures.
Whatever unique properties a service has, they should be documented to easily communicate a service's requirements, characteristics, or restrictions to others that may want to use it. This information can be added to a WSDL definition through the use of the documentation element and it could even be contained within a metadata document that is published separately and easily accessible. This promotes the discovery and reuse of services. When possible, this documentation also can be physically attached to electronic modeling diagrams.
If you are designing WS-I compliant services, you can improve the quality of your service description metadata by attaching WS-I conformance claims. These advertise compliance to specific WS-I profiles. See www.ws-i.org for more information.
SUMMARY OF KEY POINTS