1. While executing request/reply on the service interface is there a timeout value set on the call?
2. Is there code/logic to handle SOAP Faults /system exceptions when invoking the service?
3. Is building service header separated from the payload? This will facilitate reuse across services that share common header parameters
4. If there are certain error codes that the calling code can handle, is there logic for each of them?
5. Is the physical end point information (URL string for HTTP, Queue connection and name for MQ/EMS) stored in an external configuration file?
6. Is UTF-8 encoding used while sending XML requests to the service i.e. by making use of platform-specific UTF encoding objects?
7. If using form-encoding are unsafe characters such as ‘&’, ‘+’, ‘@’ escaped using appropriate %xx (hexadecimal) values?
8. While processing the service response is the logic for parsing/processing SOAP and service-specific headers decoupled from processing the business data elements?
9. Is the entire request/reply operation – invocation and response handling logic – encapsulated into its own class or method call?
10. While performing testing, is the appropriate testing environment URL/queue manager being used?
11. Is a valid correlation id being used in the service request? This is very essential for aynchronous request/reply over JMS (JMS Header) or HTTP (callback handler)

Service Design Patterns

Patterns for Fault Tolerant Software

• Data access and updates – is there a single suite of APIs for managing core data? are there redundant implementations, overlapping calls, across projects?
• Domain rules – are domain rules organized in a clear and well maintainable manner? or are they split across layers and implemented using multiple technologies/strategies?
• Processing templates – are there a common set of steps of relevance in your domain? are these steps always executed in a consistent manner? is there an opportunity to Templatize the steps?
• Config management – how are applications managing configuration properties? how do they enable properties for a particular environment? how does an application get only properties that it is entitled to?

The above isn’t exhaustive but gives you a flavor for the kinds of questions that will drive opportunities for systematic reuse

Host business process definitions and instances

• Provide a modeling and execution environment for designing and implementing business processes
• Implement a generic data structure for manipulating & orchestrating workflow state
• Provide the ability to reuse a workflow patterns across business processes. E.g. enable reuse via sub-processes, process extension points, etc.
• Provide the ability to access and orchestrate activities requiring interaction with data services and business rules, and legacy services

Act as services consumer & provider

• Host process orchestrations, while consuming persistence, validation, and security services
• Abstract legacy capabilities and reduce tight coupling between internal systems
• Publish and consume business events to reduce application to application coupling

Evolve a reusable asset catalog

• Ensure technology components and APIs have domain relevance – data, events, and relationships are fundamental abstractions need to be brought together
• Reduce learning curve for application developers to identify, evaluate, and integrate process definitions and services from a library of reusable assets

• 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?