[UPDATE] The code sample to support this article is now available on GitHub.
The full version of this article is on InfoQ: “DIY SOA: How to build your own Simple Service Repository“.
Not being a Jedi I clearly have no use for a Lightsaber, but I did have a recurring irritation in the form of the service registries and repositories. These tools often claim to support good SOA principles and practices (like discoverability and contract-first service development) but in my view they often fail to live up to the hype.
Service Registries/Repositories fall into two basic camps. There are the commercial large vendor offerings from the usual suspects and the smaller open-source attempts.
Being a lightweight agile kind of guy (not literally, sadly) I’m constrained a strong value-vs-cost ethic. To my mind the commercial offerings are basically too bulky, too demanding and too expensive to be of any interest. That leaves the open-source offerings, which are rather thin on the ground, can have limited functionality and are not terribly well thought through in terms of the functionality that I think multi-disciplined team of users would need.
So to cut a long story short I decided to build my own ‘DIY Simple Service Repository’ using low-cost open-source tools and technologies.
What I wanted from my Simple Service Repository.
A good service repository should support the principles of good service-orientation. Specifically, a service repository should allow for a high degree of service contract standardisation, support contract versioning, promote contract-first service development and enable easy service discoverability (preferably at both design time and at compile time). Let me explain what I mean by these requirements.
Contract standardisation is the practice of supporting abstraction, loose coupling, federation and reuse in service contracts by centralising artefacts like XML Schemas, abstract WSDL‘s and WS-Policy documents. Reuse of XML Schema’s is particularly important as it is a key enabler for ‘intrinsic interoperability’ whereby services communicate using the same data model. By having all my contracts, data models and policies in one place I can reuse them easily and as often as I like.
Contract versioning can be quite a difficult process but I want a simple solution where all the decisions regarding the versioning of contracts, policies and data models are mine. I’m not going to ask much from my simple service repository, I simply want it to hold ‘releases’ in separate version controlled directories that are independent of each other. I’d like releases to be addressable via a URL and be viewable in the users browser.
Contract-first development (of SOAP based web services) is important because it ensures that the service contracts remain loosely coupled and independent from the underlying implementation technology. Contract-first often entails a service designer designing the required contracts and developers ‘importing’ them into their build as the basis for a service’s implementation code. This can often be a source of some discomfort for developers who may be used to controlling their own destiny, so making it an easy process can help to overcome any potential objections that may arise.
Finally, easy service discoverability benefits service-oriented architectures because by making services highly visible we can reuse them more readily and also prevent ‘accidental’ duplication from occurring. Duplicate, competing, unused or redundant services can confuse and dilute the effectiveness and power of your SOA, hampering its ability to serve its community. These issues can be avoided (and reuse promoted) if service contracts can be easily discovered by anyone at any time.
By creating a place to centrally store service contracts (and other design time information like WS-I BP compliance documents or human readable interface documentation) we can achieve all of these goals and add some real value to our SOA analysis, design and development practices.
Enter: The SOAGrowers ‘Simple Service Repository’.
So here is my solution. Just follow my 3 simple steps and you’ll have a simple service repository in no time…
1. Create a Java web application (the Simple Service Repository application) using Maven.
The source for this project is hosted in my SVN server. The application includes browsable folders for the WSDL, XSD and WS-Policy documents and SVN keeps everything nicely version controlled. HTML and CSS provides the basic glue that binds everything together, but you could investigate using a Wiki maybe if you don’t like HTML. I’ve included some screenshots below if you want to see what it looks like in real life.
2. Build & Deploy the Simple Service Repository application to an application server.
Jenkins is an open-source continuous integration server and sits as another application on my Glassfish server. Jenkins is configured to build and deploy my application whenever it notices a change in the SVN repository.
Glassfish 3.1 is my personal application server of choice for Java web applications other servers could work just as well. Once hosted, the Simple Service Repository’s HTML pages are instantly available via a browser and I’ve also used a specific Glassfish deployment descriptor which makes my content folders browsable by default. These features help satisfy my basic ‘discoverability at design-time’ requirement.
When Jenkins builds my service it calls Maven’s ‘install’ which places the Simple Service Repository web application [WAR] and all the service contracts it contains into my Maven repository as a versioned Maven artifact. This is very handy for the next bit…
3. Build a SOAP based Web Service from a contract hosted in the Simple Service Repository (and test it).
Maven again comes to the rescue again, using a Maven ‘copy’ plugin to extract the service contract from the WAR in the Maven artifact repository during the ‘init’ phase before using the JAX-WS plugin to create a service implementation framework in Java from the extracted WSDL contract. If I didn’t like the copy approach I could probably ask wsimport to just use the URL for the contract (pointing to the Simple Service Repository’s copy of the WSDL on the application server).
The rest is plain sailing – normal boilerplate JAX-WS service implementation code. In my build I use the Cargo plugin for Maven to deploy the service implementation to Glassfish and SoapUI’s Maven plugin to run a service integration test suite during every build.
On the build server, this service is also built by Jenkins, but this time its triggered by the Simple Service Repository application being successfully re-built. That way, if the service contract for my service changes, my application gets immediately re-built and re-tested so that I’ll know if I’ve introduced a defect into the system.
In some very simple cases, the service project is so light that it only contains a few class files. Because JAX-WS can do annotation based deployment there can be very little in the way of metadata like deployment descriptors etc.
A job well done?
So there you have it, version 0.1 of the the Simple Service Repository is complete.
It’s storing my service contracts centrally, it’s making them discoverable, it’s supporting contract-first development and it’s alerting me if I introduce changes to my contracts that destabilise my service implementations. It’s even supporting simple release based versioning of contracts and data models.
To my mind it fits the brief perfectly. It’s highly available and accessible, repeatable, manageable and provides a valuable platform that supports closer collaboration between service designers and service developers.
More importantly it was very quick and easy to create. It requires zero code (if you don’t count HTML as code), it cost me about a day in development time and it draws nicely on existing low-cost open-source tools and techniques. It also requires very little infrastructure and will run nicely on a normal laptop. I could probably even put it into the cloud without too much additional development effort.
In summary, I’m still no Jedi (unfortunately) but I’m happier with my ‘DIY’ Simple Service Repository than I have been with anyone else’s.
The sample code that supports this article is available on GitHub.
About the author.
Ben Wilcock is a freelance SOA Certified Architect with a reputation for delivering exceptional Service Oriented Architectures. You can read his blog at https://benwilcock.wordpress.com/ or contact him via his website at http://www.soagrowers.com/“.