Skip to main content

Creating a Reusable Service

Posted by manning_pubs on September 5, 2012 at 5:05 AM PDT

Creating a Reusable Service (by Jos Dirksen, Author of "SOA Governance")

August 29, 2012

Manning Publications Co.

Having a standard-based search engine as an access point to your service is a good way to improve the reusability of your service. In this article based on chapter 4 of SOA Governance in Action, author Jos Dirksen presents you with a couple of guidelines that can help you in making your service more reusable.

Many books have been written on how you can create services that can be reused by other services or applications. In this article, I won’t go into specific details of how you can design and implement a reusable service, but I’ll give you a set of guidelines and best practices that can help in creating services that are reusable.

Define the correct level of granularity

If you look at a set of services, you’ll probably notice that services provide different levels of granularity. You can have anything from services that allow you to modify a single property of an entity in your system to services that allow you to apply for a mortgage. Now why is this granularity important? The granularity of a service defines how easily it can be reused. Fine-grained services can often be more easily reused than coarse-grained services. Let’s look at the different types of services you can define:
•Process services—Process services are the coarsest-grained services. These kinds of services most often offer services or products to their consumers. For instance, you can have a process service that handles the sale of a house. In this scenario the tax system needs to be updated, the homeowner’s system needs to be updated, and a lot more systems are involved in this transaction. A process service will call other process services and business services to accomplish its task. When you’re thinking about orchestration, you’re probably talking about a process service.
•Business services—A business service provides a single, specific business function for a system. In the previous example, a business service would be a service that you can use to update information in a tax system.
•Technical services—The finest-grained services are the technical services. A technical service provides a small piece of functionality to other services. An example of this could be a service that allows you to update a Person entity in the database, send an email, or call a legacy backend.

If you want to improve the reusability of your services, you can get some quick wins by looking at the technical services. These are often services that can be easily reused by the business services or by other technical services and that are often duplicated throughout the organization. If you set up a SOA registry (like the WSO2 registry) and get all the services registered, you can quickly track any duplication in your service portfolio and perhaps remove the duplication.

Decoupling the transport layer from the logical layer

One of the best ways to make sure your services can be reused is to decouple the technical transport layer from the implementation of the business logic. Figure 1 shows a logic layer that can be accessed by multiple remoting technologies.


Figure 1 Decouple the remoting implementations from the logic of a service.

If you keep the business logic of your service separated from the technical communication details, you can create additional remoting interfaces if needed and reuse your existing business logic. In figure 2, you can see the responsibilities of these two layers.

remoting and logic layers

Figure 2 The responsibilities of the remoting layer and the logic layer

The remoting layer takes care of any protocol negotiations and message transformation and then connects to the business logic using the internally provided interface.

Service discovery

When you want other consumers to use your service, it’s important that they can easily find your service. This can be done in many different ways. You can give your consumers access to your repository and let them browse through the services registered there. That way they can quickly find what they’re looking for and manually configure their clients. There are also other options. The WSO2 service registry provides a simple-to-use client that your consumers can use to access the repository programmatically.

Imagine you created documentation for a PermitService and added this along with the service to the repository. In the next few pages I’ll show you how you can search for this resource using two different methods:
•Searching for specific tags—When you have a lot of services and resources and you’re interested in a specific kind of resource, it’s useful to search based on tags. For this example, you’ll tag the PermitService and its documentation and we’ll show you how you can locate these resources.
•Finding services that are linked—In this example, I’ll show you how you can follow this link through the WSO2 client.

Before you can start searching on specific tags, you first need to add a tag to the service and the documentation. To do this, open the WSO2 registry console (https://localhost:9443) and use the Resources > Browse functionality to navigate to the HTML documentation.

On the lower right-hand side you have the option to add tags. For this example add a tag with the name Example- Tag. This is shown in figure 3.


Figure 3 Add a tag with the name ExampleTag to a resource.

After you’ve added this tag, browse to the PermitService (or follow the association) and also tag the service with this tag. You now have two resources in your repository with the tag ExampleTag. Using the WSO2 client you can now locate these resources. The interesting part of this example is shown in the following listing.

Listing 1 Use the WSO2 client to search for tagged resources

WSRegistryServiceClient client = initialize(); #1
TaggedResourcePath[] resources = #2
client.getResourcePathsWithTag("ExampleTag"); #2
for (int i = 0; i < resources.length; i++) {
String resourcePath = resources[i].getResourcePath(); #3
Resource foundResource = client.get(resourcePath); #4
// Do stuff with your resource

#1 Get the client
#2 Search for tag
#3 Get the found resource path
#4 Get the resource

In listing 1 you search for a specific resource based on tags. To do this you need to get a reference to a client (#1), and with that client you can use the getResource-PathWithTag method to search, case insensitive, for resources with a certain tag (#2). With the full resourcePath (#3) you can retrieve the resource (#4) and, for instance, automatically create a client or show the documentation. Another nice feature of the WSO2 registry is that it’s easy to follow any associations made from one resource to another. In a previous example you created an association between a service and its documentation. The code in the next listing shows how you can follow this association.

Listing 2 Use the WSO2 client to follow a resource association

Association[] associations = client.getAllAssociations #1
for (Association association : associations) { #2

System.out.println("Type: " + association.getAssociationType());
System.out.println("To: " + association.getDestinationPath());
System.out.println("From: " + association.getSourcePath());

#1 Get associations #2 Show associations

You use the getAllAssociations operation (#1) to retrieve all the associations for a specific resource. You can now easily iterate over these associations to show them (#2). If you run the previous example you’ll see output similar to this:
Type: Documents
To: /
From: /...governance/Documentation/PermitService.wsdl.html

These are two of the large number of operations provided by this client. An overview of the available operations can be found in the Javadocs for this client, which you can find at

Versioning, documentation, and using standards

If you want to create a reusable service, the other policies we’ve talked about in this chapter already help you with this. Let’s look a bit closer at these policies and how they help with reusability:
•Create self-documenting services—When you want your service to be reused, people need to be able to find this service and easily understand what it does. For this, good documentation is important. If you combine this documentation with a central SOA repository, it will be easy for consumers to find out what your service does.
•Support multiple versions of services—It’s not just important to get new consumers to use your service. It’s also important to keep these consumers using your service.
•If you change too much in your service and break the service of your existing consumers, there’s a good chance—especially after this happens a couple of times—that they’ll try to find another service or workaround. If you apply good versioning practices, you can minimize the impact on your consumers and inform them beforehand if a chance of breaking is coming.
•Reuse existing message standards—When consumers start looking for a service to use, there’s a much better chance they’ll use your service if that service follows the standards models used in your organization. This avoids the need for specific model transformations and minimizes the integration effort.


As you’ve seen in this article, you can make your service more reusable by applying a set of simple practices. One thing we skipped here is that besides these technical efforts, service reusability is affected by how your organization is organized. If other departments use your service, you’ll need to be able to bill them accordingly; they might expect specific uptimes for which you might need to buy additional hardware. If your organization doesn’t have processes in place for these kinds of requirements, service reusability is hard to set up.

Here are some other Manning titles you might be interested in:

Open Source SOA

Open Source SOA
Jeff Davis

SOA Patterns

SOA Patterns
Arnon Rotem-Gal-Oz, Eric Bruno, and Udi Dahan

SOA Security

SOA Security
Ramarao Kanneganti and Prasad A. Chodavarapu

soa04b01.jpg11.03 KB
soa04b04.jpg1.53 KB
soa04b05.jpg9.53 KB
soa04b06.png21.46 KB
soacover.png37.31 KB
soa04b02.gif14.8 KB
soa04b03.gif12.82 KB
SOAGovernanceinActionCH04B.txt11.77 KB
SOAGovernanceinActionCH04B.zip114.8 KB