We make use of both the default mime type of text/plain and the more common application/json mime type so we can show a variety of responses.

In the simple case of returning a String, no work is necessary. We can see our getColor method does not specify which mime type it produces. When javax.ws.rs.Produces, the default mime type is text/plain.

Returning JSON Objects

Returning strings is a fine start, but how does one return complex objects formatted in json? The getColorObject method does exactly that by doing two things:

Specifies the formatting is json via @Produces({ APPLICATION_JSON })

Returns a class annotated with JAXB @XmlRootElement

With this our work is done and we can now return and accept complex objects using JSON. The code for our response object is quite simple.

Deploying this war file is as easy as copying it into the webapps/ directory of your Apache TomEE install. While this is incredibly easy, this can become a little tedious to repeat over and over again.

Here is where the TomEE Maven Plugin comes in handy. Simply adding the following plugin to our war project in our Maven pom.xml will allow us to not just build our war via Maven, but also to completely setup our TomEE server as well.

Our TomEE server and JAX-RS application is now running! For convenience, TomEE will print the location of all JAX-RS resource URLs and their respective Java method. To execute our getColorObject() method we can execute a simple curl command like the following.

To shut down our server, simple Control-C the window where it was launched.

Setup Arquillian and TomEE JAX-RS Embedded

At this point we’ve written, built, deployed and executed our basic JAX-RS application on TomEE. Now the hard question, how do we do this all over again and automate it in a test case?

Any experienced developer can attest that several things complicate any real testing efforts:

Starting, stopping the server

Deploying war files

Hardcoding URLs, ports and paths into our Test Case

Port conflicts when running in CI environments

Here’s where Arquillian and TomEE Embedded come in. Arquillian is a wonderful testing framework which can handle the business of starting/stopping servers, build/deploying war files
and finally running your tests. Arquillian can do a considerable amount more, but for the purposes of this tutorial that’s more than enough.

The tests themselves are still plain JUnit tests, but with the details of the server completely abstracted. Let’s take a look at our ColorServiceTest and see what Arquillian is doing for us. The first three sections are the most interesting.

At a high level, here’s what is happening behind the scenes at each of these items:

JUnit runs and fires up Arquillian which will find TomEE Embedded and start it right there in the same JVM as the test case. No separate processes.

Arquillian will find all @Deployment annotated static methods in our test case and execute them giving us a chance to decide exactly what is deployed into the server. We can of course deploy bit-fat war files or we can be a little more precise and make them on the fly, trimming out all but the most critical classes required to complete the test.

The URL of our deployed application, hosts and ports and all, will be injected back into our testcase via @ArquillianResource. We are now free to fire requests at our server using that URL as a base.

Needless to say, an experienced developer will note we’ve saved days, weeks or months of work. The result is quite powerful. We have test case completely abstracted from the server itself. The implications and benefits of that will take a while to sink in — we don’t often get the luxury of that experience.

For our purposes, it means we have a plain Java SE enabled dev environment. We can run this testcase via Maven or in our IDE without any additional fanciness. We can run and debug our service code like we would any other plain java code. This is a huge win.

For a larger enterprise or environment, it can also have the benefit of running these same tests again against other servers or other dev, test or QA environments.

Random TomEE ports via arquillian.xml

To avoid failed tests due to simple things like port conflicts, we add a src/test/resources/arquillian.xml file and tell TomEE to use random ports. Simply specifing -1 as the port for all of our Tomcat connectors will do the trick. The TomEE Arquillian Adapter will pick random available ports and report those back to Arquillian and to the test case via the @ArquillianResource above.

Omit this file and TomEE will simply use the default ports of 8080, etc.

Test JAX-RS HTTP Response

With our server up, application deployed and everything ready to go, we still have the work of writing the tests themselves. Testing JAX-RS can be quite hard if we take the common approach of using pure HTTP client libraries like Apache HttpClient. We find ourselves building a lot of URLs, checking a lot of HTTP status codes and reading a lot of InputStreams.

Using the CXF WebClient (org.apache.cxf.jaxrs.client.WebClient) we can do that and more, but save quite a bit on the usual plumbing of building HttpGet and HttpPost objects and dealing with “default” client and pool implementation details. The act of building up our URLs is also achievable quite elegantly via methods that have a very natural REST-feel.

Invoking our POST and GET methods for updating and reading colors as plain strings using text/plain as the content type is quite easy.

Test JSON Response via CXF WebClient

When it comes to testing JSON, often this is where JAX-RS testing becomes truly difficult. If one continues on the path of reading InputStreams, the road ahead gets quite rough and turns into a parsing and marshalling task that is no fun to do even once, let alone repeat. This is where WebClient shines.

Our very same Color class that was used to create the JSON response on the server side can be used via the WebClient on the client-side in our testcase. This usage is actually considerably shorter than the InputStream equivalent.

Tags:

David is a co-founder to OpenEJB (1999), Apache Geronimo (2003) and Apache TomEE (2011), 10-year member of the JCP serving in Java EE, EJB, CDI, JMS and Java EE Security JSRs, JavaOne RockStar for 2012 & 2013, 2015 inductee into the Java Champions and nominated for JCP Member of the Year 2015. He is a contributing author to Component-Based Software Engineering: “Putting the Pieces Together,” from Addison Wesley and a regular speaker at JavaOne, Devoxx, ApacheCon, OSCon, JAX and Java-focused conferences. dblevins

TomEE for the Holidays

2 Comments

Thank you for this. It will be very useful. Is there any chance of getting the equivalent using gradle? I’m currently building with ant but would like to migrate. I can build the war using gradle, but am interested in getting testing with Arquilliian working. I currently start the embedded tomee server as part of normal junit tests.