CXF – Validating JAX-RS WADL files in unit tests

What’s the best way to stop developers breaking the WADLs generated by CXF for Java-first JAX-RS services? Make breaking the WADLs break the build of course.

I have waxed lyrical previously about my fondness for CXF’s automatically generated WADLs for Java-first JAX-RS services.  For service consumers they provide a service contract which can jump-start their client code development with a WADL code generator. As for myself, it makes it really straightforward to hit a service with ad hoc requests as I can point a GUI tool like SoapUI at the WADL, generate template request payloads with a single click, and invoke those requests with ease.

A usable auto-generated WADL depends on a set of model objects that are JAXB friendly though, and herein lies a problem if your services are JSON based and your JSON processor, like Jackson, isn’t particularly tightly bound to JAXB. If you’re not otherwise exercising your model objects via XML they can easily become JAXB unfriendly and stay that way until the next time someone actually tries to use the service WADL.

Having recently tackled a CXF upgrade and found over half the service’s WADLs broken in this manner, and having painfully trawled through the code to find the breaks, I was keen to find a way of getting an early heads-up when it happens again. Automated, WADL-driven integration tests would be an ideal solution but neither trivial to write nor easy to justify when the WADLs are for internal use only.  What I was looking for was a lightweight way of breaking the build when a change is made which breaks the WADLs, forcing the guilty developer to clean up their code there and then.

Unbreak my WADL

There are two distinct parts to automated WADL generation. The first is the creation of a JAXB schema from the value objects used by the service. The second is the assembly of the schema and endpoint information into a single XML document by CXF’s WadlGenerator class.

Both parts of this process can be derailed by underlying code issues. The former will yield a WADL with no grammar information in it, whilst the latter will yield an apparently valid and complete WADL which throws errors when imported into a client tool.

I’m going to look at both types of break and how to trap them in unit tests by way of an example User Registration service:-

This service accepts a PUT of a UserDetails model object in a JSON payload:-

This is enough to spin-up a CXF JAX-RS service with an auto-generated WADL that imports successfully into SoapUI. SoapUI in turn will generate template JSON requests matching the UserDetails object and PUT them to the service.

In the remainder of this post I’ll break the model to reproduce both types of problem and provide lightweight unit test cases to trap them.

The code for this post is available on GitHub.


One Small WADL

First, and easiest, we’ll modify the model objects in a way that violates JAXB’s rules. We’ll extend UserDetails to include a set of UserNote objects:-

And we’ll define UserNote in a way that breaks the JAXB context by having public properties with the same name as getter/setter based properties:-

The WADL returned for this version of the service is a shadow of its former self, denuded of XML schema information:-

On the server side we also get a stack trace helpfully explaining why:-

The stack trace also suggests a unit-test solution; simply generate a JAXB context for our model objects in a unit test case:-

This is a reasonable, quick and simple approach but has the drawback of requiring developers to keep the jaxb.index files up-to-date with a list of all relevant objects, and also keep the package list in the test-case up-to-date too. Remember we’re not using JAXB elsewhere in this service so nothing is going to make them do this; it isn’t therefore an awful lot more reliable than expecting them to manually test the WADL when making code changes.

An alternative which doesn’t depend on developer diligence is to request the complete WADL from within a unit test case and check for the presence of XML schema elements in its <grammar/> section-

This test case presumes an embedded instance of the service has been launched in a Jetty container as part of the test run. To make it Continuous Integration Server Safe it has been started on port 0 rather than a hard-coded port, so the first thing we do is find the actual port being used in order to build the full HTTP URL of the WADL.

We then simply feed that WADL into a DOM parser, use XPath to generate a list of <schema/> nodes in the grammar section and fail the test if the count is 0.

Either test case fails with the above, invalid model object and making the fields private gets both tests to pass:-

Something’s gotten hold of my WADL

Now for the slightly trickier case, an essentially valid JAXB model that nonetheless yields an invalid WADL.

Let’s change our UserNote object and make it an XML root element within the same namespace:-

Our JAXB tests still pass, but if we try to feed the WADL for this version of the service into SoapUI we get a stream of error messages in the log and the nifty “recreate a default representation from the schema” button on the request dialog is disabled.

Comparing the WADL with the version generated without the additional @XmlRootElement annotation shows a small but subtle difference in how the generated schema are cross-referenced.

A good test here isn’t one that digs into this specific scenario, but one that asserts that the overall WADL is valid. The easiest way for us to do this, as test developers, would be to feed the WADL into a dynamic client like SoapUI and at a minimum verify that no errors occurred when it was imported.

My search for easily embeddable Java WADL consumers did not turn up too many options, however the Wadl2Java class underpinning the Glassfish wadl2java Maven plugin is pretty painless to drive from a unit test.

We just need to add it to our project POM:-

And then we can script it in a unit test case:-

This test case configures the parameters for a Wadl2Java run using a scratch directory in our Maven build’s target/ folder to output the generated Java source code. The key is the MessageListener implementation which adds any encountered errors to a collection which we can assert at the end must be empty for a run to be considered successful.

Don’t go breaking my WADL

Unfortunately a WADL with no grammar information is still technically valid so this latter test won’t trap the former issue. To completely cover both error scenarios we need both the wadl2java based test and one of the JAXB model tests.

These are not exhaustive by any means, but then they aren’t meant to be. They provide a lightweight pair of test cases that can be added to the unit tests for a JAX-RS CXF service that will trap most (if probably not all) cases of developers making code changes that break the auto-generated WADL.



Leave a Reply

Your email address will not be published. Required fields are marked *