• Unlike stand alone applications/processes, shared services impact several consumers. Not every consumer might be okay with your service being unavailable for an extended period of time. The same service might be in the critical path for some and not so much for others
• For some service capabilities, running them in a partial mode might be acceptable – e.g.  operating out of a cached copy of data rather than fetching it from a live database, or servicing only read only operations during an unexpected outage, etc.
• Some consumers might have regulatory processes that are dependent on services being available – a service being unavailable might cause SLA breaches

Finally, consumer trust is key for systematic reuse – if they perceive service availability as a limiting factor, it will be harder to convince them to use services – including current and upcoming integrations

• allows the team to evolve consistent set of data interfaces across integration efforts – if multiple systems need to integrate with yours, can you define a generic data model for your domain-specific concepts? This could be file layout(s), service interface schemas, or platform specific APIs
• enables common interfaces for domain specific services and business processes
• integration points often need cross-cutting concerns such as logging, transaction management, exception handling, etc. that can be reused
• reusable utilities can help with support and testing tools – for instance,  reply failed messages, drain message queues/topics, generate high volume test data, etc.

Question is – are your teams taking advantage of integration points? or is each integration point implementing identical or similar functionality in an inconsistent fashion?

Happy new year 2012

What is one key reason developers have a difficult time finding and evaluating existing assets? Lack of robust documentation including what the reusable asset isn’t meant to do. Though it is a critical success factor, maintaining documentation manually is a time consuming task and is the first item that gets left out when the development team is racing to meet a deadline. It will be useful to generate documentation on service clients or library client code snippets alongside the provider code. Automate documentation as much as possible – this will come in handy when fixing bugs, integrating new consumers, as well as integrating documentation within IDEs. Here are a few examples of doing this:

• Maven javadoc plugin for example can generate javadoc style HTML documentation for various java and web modules
• Maven site deploy can be used to publish generated artifacts to a remote host
• XSL stylesheets can be used to generate HTML documentation from XML schemas (XSDs) – this can be handy when exposing reusable services (e.g. using XS3P)

Got iTunes?

New episode added to the Software Reuse Podcast Series on service governance covering design, implementation, testing, and provisioning and how they enable reuse.

Like this post? Subscribe to RSS feed or get blog updates via email.

The key is to go back to the basics of good design: identify what varies and encapsulate it.

The myth that you can somehow create this masterpiece that is infinitely reusable and should never be touched is just that – it is a myth and is divorced from reality. Reusable doesn’t imply:

• that you invest a lot in big up front design effort
• you account for everything that will vary in the design – the critical factor is to understand the domain – well enough, deep enough, so you can identify the sub-set of variability that truly matters

In the same vein, reusablility strives for separating concerns that should be kept distinct. Ask repeatedly:

• Are there multiple integration points accessing the core domain logic?
• Is there a requirement to support more than one client and if so, how will multiple clients use the same interface?
• What interfaces do your consumers need? is there a need to support more than one?
• What are the common input parameters and what are those that vary across the consumer base?

These are the key questions that will lead the designer to anticipate the appropriate places where reuse is likely to happen.  Finally, it is important that we don’t build for unknown needs in the future – so the asset is likely to solve a particular problem, solve it well, solve it for more than one or two consumers, and finally has potential to be used beyond the original intent. At each step there are design decisions made, discarded, continuous refactoring, refinements to the domain model – if not re-definition altogether.

Don’t set out trying to get to the end state or you will run the risk of adding needless complexity and significant schedule risk.

• Total number of service operations reused in a time period
• Total effort saved due to systematic reuse in a time period
• Number of new service consumers in a time period
• Number of new consumer integrations in a time period (this includes integrations from both new and existing consumer
• Service integrations across transports/interface points (for instance, the service operation could be accessed SOAP over HTTP, or as SOAP over JMS, or REST, etc.)

What metrics do your teams track?

1. Manage a common set of domain objects that are leveraged across service capabilities. This could be a library of objects (e.g. Plain Old Java Objects) or XML Schema definitions or both. Depending on the number of service consumers and the complexity in the domain, there will be need for supporting multiple concurrent versions of these objects.
2. Provide common utilities for not only service development but WSDL generation, integration and performance testing, and ensure interoperability issues are addressed
3. Appropriate functional experts are driving the service’s requirements and common capabilities across business processes are identified early in the software development lifecycle
4. Governance model guidelines are clearly documented and communicated  – for example, there are a class of changes that can be made to a public interface such as a WSDL that don’t impact existing service clients and there are some that do.
5. Performance testing needs to be done not only during development but during service provisioning – i.e. integrating a new service consumer. If your teams aren’t careful, one heavy volume consumer, can overwhelm a service impacting both new and existing consumers. Execute performance testing in an automated fashion – every time you integrate with a new client to reduce risks of breaching required SLAs

What additional practices do your teams follow?

• Common messaging architecture & utilities for facilitating the development and maintenance of stateful business processes & stateless services.
• Support business process orchestrations that join across multiple services (data services, business services, legacy services, etc.). This is essential for orchestrating complex 
• Handle workflow and system business process events via a configuration driven Event Handler Service, enabling reuse of event handler processes
• Provide  ability to reuse sub-processes across larger business processes.
• Runtime metrics including reporting and the ability to perform diagnostic troubleshooting
• Reusable schemas for request dispatching, event handling, generic transport listeners, metrics, and error handling
• Supports synchronous and asynchronous request/reply & fire/forget message exchange patterns
• Provides the ability to create reusable components for assembling new business processes
• Standard client interfaces across multiple transports such as HTTP and EMS
• Ability to query various data sources, rules engine, as well as write custom java code to integrate with existing functionality
• Provides interface for executing administrative functions
• Provides developer tools for WSDL generation, unit testing, deployment, & viewing metrics

1. Service contracts are modeled for a specific consumer, and/or exposes technical implementation details (e.g. service interfaces that force the client to set ‘default’ values on legacy system attributes).
2. New clients are integrated to services without doing performance testing – this increases the likelihood of sudden spike in volume and consequently the risk of breaching SLAs
3. Each service is implemented using an ad-hoc set of technologies, design patterns, and idioms – if you are starting to see the same functionality over and over being implemented across modules that’s a sure sign!
4. Service dependencies are not captured and managed – each service uses a rat’s nest of dependencies causing classpath conflicts and maintenance burden when updating versions.
5. Deployments are manual – binaries and configurations are assembled and made available via manual steps – automated deployment scripts either don’t exist or they are out of date
6. Exceptions are not handled consistently – depending on the nature of the exception your service might need manual support intervention, adjustment to resources, and/or targeted alerts.
7. Services are not reusing business object definitions and introduce redundant definitions instead
8. WSDLs don’t import schemas and instead define them in-line – this might be easier to implement to start with but will cause a maintenance burden over time.
9. Context information is not shared when implementing service to service interactions – as more reuse happens across services, it becomes essential to share context data among them. It will make authorization, logging, and integration much simpler
10. Service business logic is in end point classes and not encapsulated well – if your service endpoints contain any logic beyond data transformation, question it to make sure that it really belongs there. Don’t implement validation rules, defaulting logic, or complex domain rules in them

In the upcoming post, I will elaborate on each of these above to provide concrete examples. Are there other signs you can think of?

• Ensure all service interfaces are URL accessible – e.g. WSDL, associated XSD schemas etc. are hosted in a consistent structure that tools like WSDL2Java or wsdl.exe can point to and generate client side code
• Templatize the WSDL and XSD to capture client-specific information such as application identifier and name (e.g. if your service interface mandates these values, you can default them to use the appropriate client-specific value).
• Capture authentication and authorization requirements and similar to above point, generate code to set appropriate message headers (e.g. SOAP Header or JMS Header as appropriate) – this will be common to most clients except the exact credentials will vary
• Keep documentation up to date as part of the build and deployment process – e.g. if you are deploying services to a client facing environment (e.g. integration testing), deploy documentation as well as part of the exercise. For instance, generate javadoc style XML schema documentation and maven site-deploy target can be leveraged to upload the generated artifacts to a web application.
• Capture and maintain service metadata – this metadata should not only cover functional aspects but non-functional attributes as well. For instance, if your service cannot honor a response time requirement, it is critical to know that during the integration effort and not after the client has migrated their code to a production environment. This could translate to a service enhancement or an alternate integration approach altogether

This is by no means an exhaustive list but meant to give a window into the opportunities and benefits that self-service can provide.