Implementing Entity Services using NoSQL – Part 2: Contract-first

It’s time to begin the coding of my SOA entity service with NoSQL project, and as promised I’m starting with the web service’s contract.

This technique of starting with a web service contract definition is at the heart of the ‘contract-first’ approach to service-oriented architecture implementation and has numerous technical benefits including…

Book Review: RESTful Java Web Services

Introduction.

RESTful web services have been with us for a while now, and initially I, like many others, was put-off by the general lack of information on how to design and implement a RESTful web services correctly. However, a number of books are now available that attempt to guide the way by documenting the RESTful standard, its principals, and the Java implementation frameworks available to help.

Packt Publishing have teamed up with Jose Sandoval to publish their offering: “RESTful Java Web Services” — a short-format & developer-focused book that attempts to quickly tutor the reader on the RESTful standard and illustrate how to code RESTful services with a number of popular REST frameworks.

Review.

RESTful Java Web Services begins with a discussion on the principals of RESTful applications and how RESTful Web Services can play a part in a well designed Service Oriented Architecture (SOA). The core concept at the heart of REST is the provision of web-accessible ‘resources’ or entities that can be created, edited and deleted by users issuing standard HTTP requests. These resources are presented to users via ‘representations’ in the users chosen format (often with multiple format’s available for the same resource). This combination of existing technologies, flexible formats and fixed interaction types is attractive because of its simplicity and flexibility — something you don’t often hear when evaluating other SOA technologies.

Before moving on to discuss the details of RESTful service implementation with Java, the book first deals with how to successfully access a RESTful resource using a number of different HTTP client API’s such as Commons HTTP. It’s a useful introduction but unfortunately no TDD related RESTful client API’s or SOA testing tools are offered for consideration — an omission that you should be aware of if you buy the book.

The books core chapters cover the coding of RESTful services using four freely available Java based implementation frameworks; Jersey, RESTEasy, RESTlet and the Struts Rest plugin. Full source code is provided on the Packt website to support the text, and this allows the reader to get involved without too much effort. Download locations for each of the open source components are also provided at the start of each technical chapter.

The Jersey JAX-RS framework is first up, and the author uses this opportunity to create a simple 3-tier RESTful web service (a Twitter like Application Programming Interface or API) that’s based on a bunch of reusable Java classes for business logic and data storage. The service API and classes are re-used later on with all the other frameworks in order to keep coding to a minimum and to allow the reader to focus on the salient points of RESTful service development with each framework. Techniques for RESTful API analysis and design are illustrated, demystifying how to correctly select the ‘resources’ that the service API will manipulate and the format of the service’s endpoints that clients will call to communicate with the service. Representation formats are also covered, with the author opting for the commonplace XML/JSON over HTTP. The sample service is developed using the JAX-RS annotations implemented by Jersey, with the HTTP GET, PUT, DELETE and POST methods all being adequately documented and explained.

Because of the distance covered, this first section is quite meaty, but you are left with a sense of just how easy implementing RESTul services can be, especially when you acknowledge that the majority of the code samples given are for the supporting application tiers rather than the RESTful service implementation.

RESTlet is next to be used, with version 1.1 and version 2.0 both being covered at the same time. As the same sample Twitter-like service is being implemented each time, the common code is re-used allowing the focus to remain on the specifics of the RESTlet framework. Version 1.1 of RESTlet appears fairly old-school in its approach, requiring the overriding of methods, while version 2 adopts a more modern annotation based approach. For me, the code samples now started to get a bit repetitive, and experienced readers may find themselves skipping forwards as they start to grasp the basics of each framework. The reuse of the sample code does help, and the author’s highlighting of the relevant bits ensures you don’t miss something important.

The RESTEasy framework presents the author with a dilemma because it implements the same JAX-RS specification as the Jersey framework covered earlier. The result is that the sample code is practically identical to the earlier Jersey example. The author chooses to deal with this problem by simply getting through the required information quickly and sticking to the defined scope of the book. This may please most readers, but its another missed opportunity as more could have been said about RESTEasy’s additional features like its support for ATOM feeds or EJB’s.

The Struts Rest Plugin is the last framework discussed in the book, and its a bit of an odd man out. Implementing the sample service API as specified presents a challenge to Struts as it doesn’t cope quite so well with RESTful concepts like content-negotiation. It also restricts the HTTP methods available to GET and POST. Therefore, the author explains how to work around these issues so that you can still implement a workable RESTful API even when your framework choice is restricted to Struts.

Finally, some ideas are offered on how to create embedded RESTful web applications where the web service is bundled in such a way that it can be started without the need for extensive installations or large web application containers. Basic security and performance strategies are also discussed in order to give the reader some ideas on how requirements like these can be achieved using REST.

Conclusions.

I enjoyed this book very much and it definitely delivers on its promise. The standard of the writing is very high throughout, and the content is well thought out, accurate and coherent. As ever, Packt’s short book format works a treat and allows the reader to get a good quality high level overview of RESTful service implementation very quickly in a way that it accessible to most Java developers. I really liked the fast pace but I still felt like I had had a good introduction to the principals of RESTful applications and how they differ from other Web Services technologies like SOAP. It also helped me to better understand the role that RESTful services can play in the wider SOA marketplace.

I do have a few small criticisms. I was disappointed that no indication was given as to which framework the author prefers and why, or which frameworks are best for implementing web services that best conform to the constraints of RESTful applications. My personal conclusion would be that either of the two JAX-RS frameworks would be the best choice, but I’d have liked to have had the benefit of the author’s experience.

I was also disappointed that some features and tools that I think are important failed to get a mention in the book, even though most readers would probably have benefited from having them brought to their attention. For example, no mention was made of WADL (the Web Application Description Language), which can document RESTful services in a way that can be very useful for clients and developers. Testing tools like SoapUI were also left out in the cold even though they are particularly useful thanks to their ability to act as generic service clients and assure service quality. Jersey’s ability to automatically marshal and un-marshal XML or JSON into JAXB Java objectswould also have saved a great deal of coding effort and String concatenation had it been used in the sample.

These are fairly small gripes, and they didn’t spoil my enjoyment of the book. If you are new to REST, be sure to familiarise yourself with these tools and techniques once you have understood the basics. However, in order to get that initial understanding, RESTful Java Web Services comes highly recommended.

About the reviewer:

Ben Wilcock is a freelance SOA Architect with a reputation for delivering good quality Service Oriented Architectures. You can read his blog at http://benwilcock.wordpress.com/ or contact him via his website at http://www.benwilcock.net/“

RESTful service with HyperJaxb3 (Part 5 – CI with Mike)

I’m a big fan of CI (Continuous Integration) in the workplace but early on in my RESTful ‘Spike’ project I took the decision that I couldn’t be bothered creating a CI at home. From past experience I felt that the DIY-CI option takes up too much time and adds little value to a lone developer. What’s more, CI requires regular maintenance to remain effective.

However, as my project was coming to an end I remembered that my old colleagues at MikeCI.com have recently launched their hosted CI service that can automate Maven builds. Seeing as I was keen to avoid the hassle of CI, but appreciate the benefits it can bring – I thought I would give MikeCI a go.

Within minutes of using MikeCI, it became very apparent that it’s an astonishingly simple and very effective hosted service that can add a lot of value to any project, big or small.

Using Unfuddle as my SVN repository, within a few clicks I had MikeCI checking out my source code and completing simple builds. I needed a tiny bit of help from the guys at MikeCI.com to allow my build to access to some of the more obscure Maven repositories in my POM, but they handle these requests all the time and the service from the support team was top-notch.

Within a few hours (and very little effort on my part) I had a Maven build up and running and fully automated with a schedule.

Considering my project’s build includes starting and stopping an embedded Glassfish container and running SoapUI integration tests – I was amazed at just how easy it actually was!

Talking to the guys over at MikeCI, it sounds like the technical architecture behind the service is very cool. MikeCI uses Amazon’s EC2 elastic computing cloud to create a clean and secure virtual environment for every build, so there is no danger of them running out of infrastructure, or having multiple client’s builds interfere with each other.

If you’re looking to simplify your build infrastructure you should definitely evaluate MikeCI.com.

RESTful service with HyperJaxb3 (Part 4 – Architecture)

What does the basic architecture look like?

Architecture diagram

The service itself is a WAR packaged JEE6 deployable web application. The client can be anything. For the purposes of this project I used SoapUI as my client so that I could avoid messing about creating a custom UI. As I have already mentioned in other posts, the package only contains 8 or so files but delivers basic XML CRUD via a RESTful web-service.

The reason the package can be so light is because Glassfish, JavaDB, Jersey, JAXB and Eclipselink do most of the work. Deployment of the service is very fast – mere milliseconds on my PC.

RESTful service with HyperJaxb3 (Part 3 – Benefits)

What advantages does this RESTful XML based CRUD have over conventional methods like AL DSP or SOAP/WSDL?

First and foremost, it’s really, really, really simple. But also…

• Having the XSD at the core of the project makes the data model very easy to control.
• HyperJaxB3 makes the generation of marshal-able Java sources and JPA entities really easy.
• REST’s flexibility around content formats opens the application up for use by many different clients.
• Using JEE6′s simplified WAR packaging model makes the application project small and easy to package and deploy.
• JPA takes the effort out of entity persistence code and opens up lots of vendor choice.

Overall the service I have created here does basic XML based ‘CRUD’ persistence over HTTP using RESTful web-services in just 1 XSD, 2 Java classes and 4 xml configuration files. Very simple.

Finally REST with XML gives you the benefits of having a structured symantic model without the costs of using WSDL’s to define the service interface. Not using WSDL precludes you from using WS-* standards, but many people get on just fine without them.

RESTful service with HyperJaxb3 (Part 2 – Build)

In this post I’ll cover how my HyperJaxb3 based RESTful web-service gets built, tested and deployed.

What did I want the project’s build to demonstrate?

Fully automated end-to-end build, test and deployment with integration testing of JEE6 applications.

I chose Maven to handle the build because it’s well supported and perfect for this type of requirement. By choosing Maven I get the consistency of a prescribed build lifecycle and fully automated dependency management.

I also wanted an opportunity to use Glassfish V3 and JEE6. I prefer Glassfish to JBoss these days because of its great Admin console.

What frameworks does the project use?

The project is a JEE6 WAR packaged web-application containing stateless EJB’s (which is a new feature of JEE6). The jax-rs implementation I’m using is Jersey from Sun which also takes care of marshalling data in either JSON or XML format into Java objects and vice versa. The JPA implementation is Eclipselink, previously known as Oracle Toplink. The application depends on the default datasource provided in Glassfish which is based on the JavaDB database.

What happens during the Maven build?

In Maven I use the ‘verify‘ goal which sits towards the end of the Maven build lifecycle. This causes the following steps to occur during each build…

1. Generate sources. The HyperJaxb3 Maven Plugin picks up my ‘Item.xsd’ in the generate-sources stage and creates a set of Java objects that are annotated as using both JPA for persistence and JAXB for XML marshalling. It also generates the container persistence configuration file used by Glassfish.
2. Compile. The code is then compiled as usual using the generated sources from step 1.
3. Test. The JUnit tests are then run using Mockito to mock out the JPA framework and the EJB used for CRUD operations.
4. Package. The application is then packaged into a WAR archive.
5. Start-domain. The Glassfish Maven Plugin starts an embedded Glassfish V3 instance using a customised configuration.
6. The WAR archive is then deployed to the embedded server instance.
7. Integration test. The SoapUI Maven Plugin then starts a SoapUI v3 test that tests the REST interface and ensures all the integrated components are working correctly together.
8. The application WAR is undeployed.
9. Stop-domain. Finally, the embedded Glassfish instance is shut-down.

This process ensures that everything can be built, tested, deployed and integration tested in one fully automated process. If this were handled by a CI server like Hudson or Mike, then you would get a full end-to-end test every time the build is triggered.

I enjoyed putting this project together and figured this was a pretty useful build process that I could use again and again. What do you think? Send me a comment.

RESTful service with HyperJaxb3 (Part 1 – Goals)

Since my last post, lots of people have been asking me what exactly I’ve been doing with HyperJaxb3 and REST (jax-rs). In this post I’ll try and explain what I wanted to get out of this RESTful service prototype…

What was I trying to achieve?

1. I wanted to learn how use the power of RESTful services, JAXB and JPA to create a very simple prototype service that can be used to Create, Read, Update, and Delete a simple XSD structure.
2. I wanted an XSD based data model to sit right at the core of this project. The XSD would describe all the entities used by the application and govern all communications between the client and the service. The XSD would preferably also control the Java data model and the JPA database structure (DDL) in order to keep things simple.
3. I wanted to create something quickly. I’m doing this prototype in my limited personal-time and I get bored with long drawn out projects when I’m working alone like this.

Why did I want to build this prototype?

In the past I have designed WSDL first SOAP services that have used proprietary products like BEA AquaLogic Data Services Platform (a.k.a. ‘Oracle Data Service Integrator’) to hande CRUD operations on an XSD document via a SOAP/WSDL interface.

Having used these products, I felt that they were a bit bloated, clunky, expensive and not particularly user friendly. Developers generally did not like these products and gave me some grief for towing the company line. That experience left me with a desire to ‘explore other options’.

If I could find an alternative to these products that was cheaper, simpler, faster and easier to work with – I’d be onto a winner.

What ‘User Story’ does my prototype implement?

Many companies need a Product Information Management system to keep track of product data. At the heart of these products is a simple CRUD mechanism for storing details about Products or Items. As I have some exposure to these systems it seemed like a logical place to start.

Was HyperJaxb in the frame from the start?

No. I discovered HyperJaxb3 during my ‘spike’ phase when I was looking for ways to combine JPA and JAXB. Of course once I’d found HyperJaxb3 I really wanted to make it work because it makes things so much simpler.

In my next post I’ll cover some details about the project’s build which does full integration testing using an embedded JEE server. Subscribe now to get an alert when I post…