Gyrex/Learning Material/Extend JAX-RS

From Eclipsepedia

Jump to: navigation, search
Mailing ListForumsIRC
Help Wanted
Bug Day
Browse SourceProject Set File

This tutorial will extend the functionality of the last tutorial Develop JAX-RS Application. With a new bundle it is possible to generate JSON out of domain objects in combination with EclipseLink MOXy. This bundle was made to let Java developers easily convert Java content trees into a XML format but it is possible to convert into JSON, too. The used JAXBContextFactory bundle will be already imported in your targetmachine if you have worked through the tutorial Install JAXRS AddOn for Gyrex. The whole bundle containing all classes described below you will find here (zip-file).


OSGi Declarative Services require a configured target platform as well as a Java 6 runtime environment. It is recommend, to process the tutorial Develop JAX-RS Application using Gyrex.

This tutorial was created using eclipse Indigo Service Release 2.


Assuming you use the bundles sample.service and sample.jaxrs from the tutorial Develop JAX-RS now you just have to create a new plug-in project with a name like "sample.jaxrs.json". The Activator and any templates we don't need. But a few packages have to imported again. Open the MANIFEST.MF of your new bundle, switch to the register MANIFEST.MF and add following lines:

Bundle-ActivationPolicy: lazy
Import-Package: sample.service;version="1.0.0",;version="[1.1.0,2.0.0)",;version="[1.1.0,2.0.0)",;version="[1.1.0,2.0.0)",
Added packages

Swichting back to the register Dependencies in section Automated Management of Dependencies the following packages have to be added one-by-one, too.

  • org.eclipse.osgi


Now just create the new folder "OSGI-INF" in the created bundle and add an OSGI DS component. Properties are:

  • Parent folder: sample.jaxrs.json/OSGI-INF
  • Filename: jaxrs-jsonapi-application.xml
  • Name: sample.jaxrs.json.application.component
  • Class: org.eclipse.gyrex.http.jaxrs.JaxRsApplicationProviderComponent
  • activate: activate
  • deactivate: deactivate
  • Provided Service: org.eclipse.gyrex.http.application.provider.ApplicationProvider
  • Property: name="service.description" type="String" value="JAX-RS JSON API Application"

Check whether the line

	Service-Component: OSGI-INF/jaxrs-jsonapi-application.xml

is in the MAINFEST.MF, add if necessary, and the preparations are done.

In order to convert data into JSON format it is necessary to create a JSONProvider. This provider will be located in the sample.jaxrs.json package. The application will search resources like this JSONProvider to convert into JSON. A @Provider annotation declares the class to be a provider. With @Produces(MediaType.APPLICATION_JSON) the application knows that this provider will produce JSON objects sended to the client. The @Consumes(MediaType.APPLICATION_JSON) allows only JSON as input mediatype accepted form the client. Re-implementing the two interfaces MessageBodyReader and MessageBodyWriter we will be able to write JSON format and read it. Furthermore the DomainClass and the JAXBContext is needed which you get with "getDomainClass" and "getJAXBContext". The JACBContext provides the clients entry point and convert between XML/JSON elements and the corresponding java representations. The method "readFrom" converts the JSON to java representation using the Unmarshaller and the method "writeTo" converts from java to JSON using the Marshaller. The usage of the Marshaller and Unmarshaller will be explained by EclipseLink MOXy.

In the same way the class GreetingsResource from the bundle sample.jaxrs collects and shows the greetings, we need a class in this bundle, too. Locate this class with a name like JsonGreetingResource in the package sample.jaxrs.json. The @Path("/greetings") annotation redirect you later, when starting the application to this page showing the greetings as JSON. @Produces and @Consumes ensure that only JSON is accepted. The responsible method to show the greetings later in your application should be annotate with @GET. This is the REST operation which will request information from the server. In the given example the return type will be a list of greetings. There is no explicit call of the JSONProvider, but by searching for greetings using a model Greeting which will be implemented later, the application will automatically search for providers and convert the object into a JSON format.

Now the model will be created. To do so create a new package sample.jaxrs.json.model and in this package create the class "Greeting". With the annotation @XmlRootElement the values of the class will be shown as a XML file. We want to show the greetings as JSON so this isn't necessary now, but will be needed when converting into XML files. In this class there is only a String which can be retrived and set. The usage of the EclipseLink MOXy (JAXB) has to declared in a text file called "" in the package where the domain classes (the model) are located. We need this bundle to be able to convert into JSON format. With this bundle in the provider some parameters can be setted ensuring the convertation into JSON. The content of this file is just one line:

With completion of this activity now you can start the server again as described in earlier tutorials. Then open the Gyrex Admin UI in your favorite browser an open the menu General left hand. Clicking on Applications a window opens and you can mount your application to an URL. Click on Add and the next page will open. There you have to enter an Id, select a Provider, i.e. chose your JAX-RS application and enter the Context, which should be "/" again.
JSON formated output
Choosing the provider you now have the choice. The sample.jaxrs.application.component is the application from last tutorial where you can enter greetings. The sample.jaxrs.json.application.component is the new application you have just created. When you mount this application to an URL like "http:/sample" and you enter this in your location bar, than an error will occur, because there is no service for this path. But still you add "/greetings/" the greetings you add using the sample.jaxrs.application.component will shown as JSON objects. Therfore no further greetings can be typed.

This tutorial just shows JSON conversion. Searching in EclipseLink MOXy you will find other tutorials explainig how to convert to XML.