|
|
| Line 1: |
Line 1: |
| − | {{Gyrex}}
| |
| | | | |
| − | This tutorial will extend the functionality of the last tutorial [http://wiki.eclipse.org/Gyrex/Develop_JAX-RS Develop JAX-RS Application]. With a new bundle it is possible to generate JSON out of domain objects in combination with [http://www.eclipse.org/eclipselink/moxy.php 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 [http://wiki.eclipse.org/Gyrex/Install_JAXRS_AddOn Install JAXRS AddOn for Gyrex].
| |
| − | The whole bundle containing all classes described below you will find [[Media:JaxrsJsonApplication-ExtendJAX-RS.zip|here (zip-file)]].
| |
| − |
| |
| − | === Requirements ===
| |
| − |
| |
| − | OSGi Declarative Services require a configured target platform as well as a Java 6 runtime environment.
| |
| − | It is recommend, to process the tutorial [http://wiki.eclipse.org/Gyrex/Develop_JAX-RS Develop JAX-RS Application using Gyrex].
| |
| − |
| |
| − | ''This tutorial was created using eclipse Indigo Service Release 2.'' <br>
| |
| − |
| |
| − | === Tutorial ===
| |
| − |
| |
| − | 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:
| |
| − | <pre>
| |
| − | Bundle-ActivationPolicy: lazy
| |
| − | Import-Package: sample.service;version="1.0.0",
| |
| − | javax.ws.rs;version="[1.1.0,2.0.0)",
| |
| − | javax.ws.rs.core;version="[1.1.0,2.0.0)",
| |
| − | javax.ws.rs.ext;version="[1.1.0,2.0.0)",
| |
| − | javax.xml.bind,
| |
| − | javax.xml.bind.annotation,
| |
| − | javax.xml.transform.stream,
| |
| − | org.eclipse.gyrex.http.application.provider;version="[1.0.0,2.0.0)",
| |
| − | org.eclipse.gyrex.http.jaxrs;version="[1.0.0,2.0.0)",
| |
| − | org.eclipse.persistence.jaxb;version="[2.4.0,3.0.0)",
| |
| − | org.osgi.framework;version="[1.3.0,2.0.0)"
| |
| − | </pre>
| |
| − | [[Image:AddedPackages_SampleJaxrsJson_ExtendJAX-RS.jpg|thumb|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.
| |
| − | * javax.ws.rs
| |
| − | * org.eclipse.osgi
| |
| − | * org.eclipse.osgi.services
| |
| − |
| |
| − |
| |
| − | [[Image:JaxrsJsonApiApplicationXml_SampleJaxrsJson_ExtendJAX-RS.jpg|thumb|jaxrs-jsonapi-application.xml]]
| |
| − | 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'''
| |
| − | [[Image:ManifestMf_SampleJaxrsJson-ExtendJAX-RS.jpg|thumb|MANIFEST.MF]]
| |
| − | * Property: '''name="service.description" type="String" value="JAX-RS JSON API Application"'''
| |
| − | Check whether the line
| |
| − | <pre>
| |
| − | Service-Component: OSGI-INF/jaxrs-jsonapi-application.xml
| |
| − | </pre>
| |
| − | 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 [http://www.eclipse.org/eclipselink/moxy.php 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 '''"jaxb.properties"''' 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:
| |
| − | <pre>
| |
| − | javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory
| |
| − | </pre>
| |
| − |
| |
| − | 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. [[Image:BrowserOutputJson-ExtendJAX-RS.jpg|thumb|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 [http://www.eclipse.org/eclipselink/moxy.php EclipseLink MOXy] you will find other tutorials explainig how to convert to XML.
| |
