JAX-RS 2.0: Custom Content Handling

i tried to think of a better title, but failed to come up with one! please bear with me...

the jax-rs 2.0 specification allows us to seamlessly marshal/unmarshal jaxb objects to/from http request/response bodies. simply put, we can just work with the domain objects without being worried about the low level xml serialization within jax-rs based solutions.

before we begin, here is the github link to the source code referenced below - not much, but just in case you need to peek in.

development environment

• java ee 7 (of course!)
• jdk 8- don't get excited, there are no lambdas in there as yet!
• netbeans 8
• wildfly 8 and glassfish 4 (yes, tested on both servers) - it's just about switching servers in netbeans and takes anywhere b/w 15-30 seconds. so it's not really that big a deal ;-)

let us first go through the use cases which demonstrates the out-of-the-box capabilities of jax-rs implementations in order to deal with jaxb annotated entities/domain objects over the wire.

here is a simple example where in we try to ' get ' a representation of our domain object which happens to be jaxb annotated pojo:

the below json response is obtained when we fire a get http request. the tool being used here is postman:

similarly, the xml response can also be observed by simply toggling the accept http header to application/xml:

let's see a case where in we try to ' post ' a representation of our domain object (xml/json) over the wire:

fire post request via postman:

snippet for the stdout in the server logs (as per code above):

so, we just saw, in jaxrs, domain objects decorated with jaxb annotations allows can be exchanged over the wire in both xml and json formats without breaking a sweat!

consider a scenario where we already have rich domain java objects available to us. but:

• we do not have access to the source code
• we cannot really annotate them with jaxb annotations
• the domain entities are legacy pojos which are not jaxb compatible

here is where we can leverage customized content handling feature available in jax-rs 2.0. the messagebodywriter and messagebodyreader interfaces provide us a way to plug in our customized marshalling/unmarshalling mechanism and allow the jax-rs run time to take care of the rest!

the example which follows primarily deals with xml and json formats, but please note that these interfaces can be used for 'any' data formats - the internet is teeming with hundreds of these with new ones popping up daily!

let's see some code... again...

to begin with, in order to simulate a get scenario, let's just return an instance of a legacy pojo class from our jaxrs resource method. it's not jaxb compatible /we do not have the source code to decorate it via jaxb annotations:

how do you think this will get serialized to xml over the wire ? our custom implementation of the javax.ws.rs.ext.messagebodywriter interface will facilitate this.

this interface has 3 abstract methods which one would need to implement. the snippet showcases the writeto() method, which contains the bulk of the transformation logic.

you can read about it further in the java ee 7 javadocs

so, as usual, we ask postman to validate things for us, and this is what he had to say. no hassles! imagine if the legacy pojo representation is fetched from the persistent (db) store directly - all you need to do is return it since the on-the-wire representation has been taken care of:

now, the reverse scenario - post an xml representation from our client layer and watch it getting serialized into the legacy pojo instance. want to persist it ? sure, go ahead and fire the entity manager ;)  (don't forget @javax.ejb.stateless !)

how do you think the xml payload sent by the client get converted to our leagcy pojo instance over the wire? our custom implementation of the javax.ws.rs.ext.messagebodyreader interface will make this happen:

call upon postman, post an xml representation over the wire, and see the results:

just to ensure that our legacy pojo indeed got serialized - confirmed via the server stdout logs:

so, with the help of a trivial example, we saw how easy it is for us to define custom transformation/wrapper-like logic for handling custom domain objects/entities/pojos within jaxrs based implementations.

couple of observations before signing off:

• jaxrs implementation in glassfish4 does not support seamless json serialization/deserialization via a jaxb decorated pojo . wildfly 8 worked like a charm! kudos!
• on delegation of the marshall/unmarshall process to entity interceptors (reader/writer implementations), the seamless json support ceased to work (both in glassfish as well as wildfly). not sure why. i am guessing the the jaxrs implementation is directly fetching the payload from/writing payload to the input/output streams respectively, and somehow there is no intermediate layer to factor in the content negotiation

i hope i am not missing a trick here! if you think so, please be kind enough to give me a heads up :-)

well, that's it for now! happy coding............!