Service Reuse and Entitlement

J2EE Journal, 2008

READS: 12,417

At a glance the reuse of a service and entitlement to those service results have nothing in common. But on the second thought, the more a service gets reused the greater the chance of serving users with different access rights to the service results.
We’ll discuss two models of reuse and see which one is more suitable for resolving data visibility tasks. Service Reuse Models
In the early days of SOA, service reuse was one of the main selling points in pitching the new architecture principle to business clients. It’s still a mystery to me why the idea of reuse has worked this time – it’s not new to IT or business. Before, object-oriented architecture promised business reuse and component-oriented architecture swore to it. Then IT finally got a great deal of reuse out of standardized API; this helped solve some business problems but failed to provide the promised scale of improvement.

In this article we’ll analyze a traditional service reuse – reuse “as is.” But industry knows another kind of reuse – a container-like reuse. Some of you are probably familiar with J2EE (now JEE) containers for Web and business (EJB) applications and components. The same container can be reused for deploying multiple different components. The container enforces a certain development model by specifying what design elements are possible and impossible to use in the components, such as multithreading.

By analogy to the container, the same service operation can be reused as a channel providing the exchange of different extended messages between service consumer and service provider. Here we’ll analyze container-like reuse of the service – reuse via extension.

To complete this observation, let’s explain what we mean by a service reuse. If one understands service reuse as a use of the service in multiple projects, it may or may not be service reuse. It depends on how different the projects are.

Assume we are working in financial fund management. The task is to represent historical fund prices to the consumer. To implement this task with services we need, for example, to invoke an authorization service to control access to 1) the related Web page, 2) the business service aggregating historical fund prices, 3) the fund business service, and 4) the data acquisition service to retrieve data from the persistent store. How many reuses do we have in this example? My answer is none. We just used the authorization service several times against different protected entities.

Reuse in the service eco-system means that a service gets used in different execution contexts. For example, a mutual fund valuation service is built into the multinational financial organization. The service may be reused for funds operating in different countries. Even if countries speak the same language, like the U.S.A. and the U.K., the business execution context is different in these two places because of different laws and industry regulations.

Reuse Companion
A question about service interface granularity usually accompanies decisions of service reuse. The granularity of a service interface is a matter of art rather than a strongly regulated practice. It is a tradeoff in every case and has to take into consideration not only coding requirements but also performances, network capabilities, and service lifecycle management.

Indeed, if the interface provides fine-grained operations, like an API, it’s suitable for the reuse “as is.” Such reuse may reach high numbers at the beginning of a reuse process. However, try to recall the scale of effort required to move to a next version of the API, which is not totally backward-compatible… It’s close to a nightmare – and the wider reuse, the worse it is.

If we use a coarse-grained service interface, it’s less sensitive to the changes than the fine-grained one. However, some people believe that a coarse-grained service interface promotes the risk of massive programmatic mistakes. They think that such interfaces disallow concrete compilation control over the information passed through the “widely open” operations. I disagree with such a opinion because:

• Control based on operation granularity is inherited from the OOA, which doesn’t necessarily work for function-oriented SOA services
• The granularity of operations in a SOA is usually combined with strong types of the messages – message schemas. Following SOA best practices, for a document-style service, the document schema is one of the strongest data-type controls
• The granularity of the operations and message schemas aren’t a responsibility of the developer (who can make programmatic mistakes) but rather the design decision. As such, they go through multiple design reviews and controls, which minimize the chance of mistakes.

In the next sections we’ll demonstrate that reuse via extension provides the needed compromise between granularity and reusability.

Service Categories and Reusability
In SOA practice and in some advanced SOA books (e.g., written by Thomas Erl), SOA services are grouped into three major categories: utility, entity, and business service. As the name suggests, utility services are helpers that provide service-oriented environment for other services and applications.

An example of a utility service is a security access control service. It is agnostic to any business processes, entities, tools, instruments, and applications; so, it can be reused in many execution contexts.

Another category is entity services. These services are tricky things – there’s is a debate in the SOA community over whether an entity service is a SOA anti-pattern. An entity service represents business data objects in the service world. However, each service consumer has its own “view” of the shared business data object, and each architectural layer and execution context has its own requirements for the business data object. Obviously, we can expect less traditional reuse of the entity services than utility services.

The final category comprises business services. Such services implement business functions, features, units of work, and, occasionally business activities. Business services can work together representing an implementation of a business process. Some business processes may be embedded into the business services. Figure 1illustrates reuse of the different service categories.

It might surprise some but in the business world we don’t see much reuse of business services, i.e. the use of a service in different business contexts or situations. This is because of the business ownership model and the complexity of management across business lines. Currently, a SOA business service is seen as a reflection of the real business world. So business service reuse is less across the enterprise than the early SOA enthusiasts claimed.

Figure 2 depicts the difference in reuse between service categories depending on the reuse model. As described above, traditional reuse degrades due to inflexibility to changes in the business caused by the differences and changes in the execution contexts. On the other hand, coarse-grained service interfaces provide certain flexibility. So, we’re looking for a mechanism capable of balancing specific and generic aspects of the service interface. Reuse via extension allows using the strongly typed service operations, typical for fine-grained interfaces simultaneously with flexible, extendable messages, which is closer to the coarse-grained model.

As the graph in Figure 2 shows, reuse via extension doesn’t offer many benefits over traditional reuse for utility services. However, the more dynamic a business environment becomes, i.e., the more changes required to keep the business competitive in the market, the more traditional reuse looses to reuse via extension for the entity services and, especially, for the business services. Below we’ll discuss one possible way of implementing reuse via extension for Web Services.

Web Services Example of Reuse via Extension
Let’s consider a use-case where a SOA service with a Web Service interface valuates an investment fund in a hypothetical company called Enterprise. Sometimes valuation is needed for fund processing but, in the future, it could be the final action in a business process and the valuation would have to be stored in a database.

The business client has indicated that not all requirements for the valuation are formulated yet but the valuation operation has to be available to end users as soon as possible. The development team recognizes that the valuation would be reused in multiple business scenarios over time, and some of them aren’t known yet. If the number of actions associated with the valuation grows and each action to be represented as a service function, there is little chance for traditional service reuse. However, if the new service functions are defined as extensions of the same core operation, we can achieve service reusability with reuse via extension.

Service Interface Definition
The development team creates a Web Services interface for the Valuation Service (see Listings 1 and 2) and defines only one operation – valuateFund(). It’s important to notice that the operation name reflects the valuation action for the funds, not for bonds or anything else. This is how an operation type can be specified for service reuse via extension. The operation is associated with request, response, and failure messages and with corresponding message XML Schemas.

The design goal of the interface is to loosely couple message XML Schemas with the interface operation. As Listing 2 shows, each message has its own schema and namespace defined in different files.

Basic Message Definition
With reuse via extension, a Web Service uses the same port (end point) and port type. The port type always contains the same operation with the same basic in/out/failure messages.

The basic “in” message defines the request for fund valuation. The basic “out” message defines the response, i.e., fund valuation. Since the service anticipates potential failures in service resources and connectivity, the interface defines one failure message – serviceResourceUnavailable.

In the Listings 3, 4 and 5 we find XML Schemas for the request message, the response and the failure message. The business action of fund valuation is represented by the element “valuate.” It contains three sub-elements that detail the action by specifying a fund name and fund and requester identifiers.

Basic Message Extension
The development team has decided to implement all additional business actions – new functions – in a consistent reuse via extension manner. So, the business action “store” valuation has to be implemented as an extension of the basic message XML Schema. The extension of the schema is imported as a new namespace that defines composite business action – “store.”

Let’s discuss the implementation specifics shown in Listings 6 and 7. First, all elements related to the business actions are listed in the construct and all of them are optional. This means a service consumer isn’t obliged to specify any one of them if it’s not needed. The basic response message reserves “emptyRequest” element for such case.

Second, all of the schemas have been designed to expose the namespaces in instance documents (as directed by <elementFormDefault> with value “qualified”). This points to the fact that all related XML documents deal with different namespaces. The service consumer can choose whether to use a particular namespace or skip related elements. That is, the service consumer chooses to use the extension of the service or not with no harm to the existing code. Finally, any element related to a new business action can be added to the <all> independently of the others. For example, a service consumer can specify only the action “store” without the action “valuate” or both in any order. This is possible because the service maintains its internal state. The service is stateless as far as the consumer’s invocations go (no state is saved between consecutive calls to the valuateFund() operation) but the results of each business action are cached in the service until the response message is formed and returned. The Service Description states that all business actions in one invocation are performed for the same valuation. In the hidden service implementation, execution of any action checks if the valuation was done already and reuses it in the composed action.

As a result of such a design, a service consumer can choose to work with any available extensions when the consumer needs to and isn’t forced by the service provider to update to a new version of the service. Thus the organization can schedule and gracefully manage a transition onto new service functionality for all existing consumers in accordance with service governance policies.

Further Message Extension
At the moment the service was released into production, the business client specified a new requirement: when the valuation stores, certain business consumers and other services have to be notified about this event. Also some business consumers interested in the notification may not be necessary among existing consumers of the Valuation Service.

The development team has decided to implement the new requirement by sending notification messages using message-oriented middleware (MOM). As they agreed before, any new solution has to minimally affect existing service consumers.

Following the reuse via extension concept, the request message schema has to include new business notification action represented by the new element “notify” (see Listing 8). In the definition of “notify” (see Listing 9), the “addresseeID” stands for an identifier of the addressee to be notified. If it’s not specified (minOccurs=”0″), the notification is restricted, if its value is NULL, the notification may go to everybody as a broadcast, otherwise the notification has to go to a specified unlimited list of addressees as a multicast.

Obviously, the notification may fail while valuation succeeds. Thus the service interface has to include an additional failure message related to MOM or the existing failure message may be extended as shown in Listings 10 and 11. So FundValuationException can contain either a serviceResourceUnavailable or valuationNotificationFailure alert.

To summarize the case, we can see that the development team has implemented two new business features for the fund valuation service – “store” and “notify” – without changing the service interface. It was done by importing additional namespaces into the request message schema and changing the failure messages schema. Service consumers who need only a few features can ignore unrelated schema extensions since they’re optional and don’t interfere with the basic schema/namespace.

Entitlement Meets Reusability
Now assume that the Enterprise becomes a global organization and starts business units and clients in different countries. One possible work scenario comprises a business analyst in the U.S. who uses the Valuation Service to work with fund shares that belong to a citizen of Singapore. According to Singapore law private financial information can’t be seen by others outside of Singapore without special agreement. So, to reuse the Valuation Service, Enterprise’s compliance requires special data access control that hides some returned data in certain cases.

This is a typical data visibility or data entitlement scenario that requires an access control at the data level per service consumer and service result. Use of the service internationally (versus locally) means a change in the service execution context, i.e., in a business context for this case. Thus we may need to consider a special service response version to be used in the new execution context.

The service provider shouldn’t decide when to respond with a special message version because it’s outside the scope of the business service tasks. A service consumer also doesn’t necessary know upfront where the fund shareowner is, what the related laws are, and which response version of the data format to request. Instead, an Entitlement Service is supposed to be involved to specify whether returned data should be hidden and how.

To meet the new requirements, the development team has decided to build a response message XML Schema extension (Listings 12 and 13) that shows obfuscated valuation. Initially, this schema extension will be known only to the consumers working in the international area. Later, there would be a plan for a graceful transition of all service consumers onto the new response version.

The Entitlement service distinguishes between consumers working in local and international areas and informs the Valuation Service which response schema to use. The Entitlement service can also perform obfuscation of the returned value.

Thus the ability to offer different data visibility via a message schema extension allows for the dynamic, on-demand data access control in SOA services. The wider a service gets reused, the greater the chance different data visibility will be required.

Conclusion
This article compared traditional “as is” services reuse with an advanced mechanism of service reuse via extension of the message schemas. Both kinds of reuse are observed for utility, entity, and business services. Service interface granularity is also considered as a factor that contributes to service reuse capability.

Reuse via extension has a dual effect. A service vendor/provider can add new functionality by operating with extensions – optional XML namespaces – and without affecting existing consumers. A service consumer can decide which extension to use with which functionality and when. To upgrade to new functionality, a service consumer has only to change the message parsing procedure for dealing with a new namespace. Because the parsing mechanism of the message in the document-style Web Service can be decoupled from the service’s proxy code, the entire communication proxy code can be reused for newly added functionality with no changes.

Manipulating message details via different namespaces makes it possible to control data visibility inside the message. That is, different data can become visible to or hidden from different consumers based on their entitlement to information. Entitlement services can decide when and how to apply access control to the data and use different message extensions for different service consumers. This allows reusing the services in many execution contexts with a variety of customer audiences.

Resources

• Web Services Description Language (WSDL) 1.1. www.w3.org/TR/wsdl#_wsdl.
• A Collectively Developed Set of Schema Design Guidelines. “Multi-Schema Project: Zero, One, or Many Namespaces?” www.xfront.com/ZeroOneOrManyNamespaces.html.
• Michael Poulin. “Service Versioning for SOA.” SOA-Web Services Journal. Vol. 6 Issue 7. http://webservices.sys-con.com/read/250503.htm.
• Michael Poulin. “Entitlement to Data.” Java Developer’s Journal. Vol. 11 Issue 1. http://webservices.sys-con.com/read/163285.htm.
• Thomas Erl. “The Principles of Service – Orientation Part 2 of 6: Service Contracts and Loose Coupling.” http://searchwebservices.techtarget.com/tip/1,289483,sid26_gci1171966,00.html