Gyrex/Learning Material/Develop JAX-RS

• Administrator Guide
• Developer Guide
• Contributor Guide
• FAQ
• Learning
• Internals

Gyrex
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source • Project Set File

This tutorial guides you through the development of JAX-RS applications using Gyrex. In the tutorial Develop OSGi Declarative Service a GreetingService was implemented which will be used now. As it was said in the tutorial Devlop OSGi DS, an interface will be separated from the re-implementations. Therefore the interface GreetingService will be removed from the sample.service and placed in a new bundle sample.jaxrs. You can find here (zip-file) both bundles with all containing manifests and classes.

Requirements

OSGi Declarative Services requires a configured target platform as well as a Java 7 runtime environment. However, it is recommend to work first on the tutorial Develop OSGi Declarative Service.

This tutorial was created using eclipse Indigo Service Release 2.

Tutorial

Give additional properties and deselect the Activator

Create a new plug-in project and name it "sample.jaxrs". As target platform we will use an "Equinox" OSGi framework. You can deselect the option for an Activator, we don't need it. We don't need any template neither. To import required packages open the MANIFEST.MF and switch to the register MANIFEST.MF, then add the following lines:

Import-Package: javax.inject;version="[1.0.0,2.0.0)", 
                javax.ws.rs;version="[1.1.0,2.0.0)",
                javax.ws.rs.core;version="[1.1.0,2.0.0)",
                org.apache.commons.lang;version="[2.4.0,3.0.0)",
                org.apache.commons.lang.exception;version="[2.4.0,3.0.0)",
                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)"

This line has to be added, too:

Bundle-ActivationPolicy: lazy

Don't forget to add the empty line at the bottom of the text.

Further packages have to be added in the register Dependencies. In section Automated Management of Dependencies click Add and add these packages one-by-one:

Added Packages

• javax.ws.rs
• org.eclipse.gyrex.http
• org.eclipse.gyrex.http.jersey
• org.apache.commons.lang

It's time to create a new folder in your project with the name "OSGI-INF". In this folder, add a new OSGi DS component (Plug-In Development -> Component Definition) called "jaxrs-application.xml" with the following properties:

• parnet folder: sample.jaxrs/OSGI-INF
• filename: jaxrs-application.xml
• name: sample.jaxrs.application.component
• class: org.eclipse.gyrex.http.jaxrs.JaxRsApplicationProviderComponent

After creating this file, open it and set the following parameters:

• activate: activate
• deactivate: deactivate
• Provided Service: org.eclipse.gyrex.http.application.provider.ApplicationProvider
• Property: name="service.description" type="String" value="JAX-RS Application"

Now your jaxrs-application.xml should look like this:

Finally, you have to say your MANIFEST.MF that there is a service-component. Open the MANIFEST.MF and switch to the register MANIFEST.MF, and then add the following line if it isn't allready there:

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

MANIFEST.mf with all added lines

In this sample.jaxrs bundle, the provided interface GreetingService will be placed. The service that you implemented in the tutorial Develop OSGi Declarative Service will use it. Therefore, the package sample.service has to be created containing the GreetingService.java. You implemented it in the last tutorial, so just copy it from there and paste it in this package. To inform the framework that there is such a interface, add in the MANIFEST.MF (register MANIFEST.MF) the following line:

Export-Package: sample.service

Sample.service must be the name of the package containing the interface.

Assuming you use the service bundle from last tutorial, now you have to make changes there too. First delete the interface GreetingService. We placed it already in the sample.jaxrs bundle. Now open the MANIFEST.MF of this sample_imp.service bundle (the name was changed to sample_imp.service to higlight the different bundles). Add the following lines:

Export-Package: sample_imp.service
Require-Bundle: sample.jaxrs

Exporting the package you provide the implementation of the GreetingService interface. This is a re-implementation of an interface, so the interface-implementation is required. The Require-Bundle line indicates where it is placed. Note that sample.jaxrs is the whole bundle that you implemented at the beginning.
In this example we still need another interface to get information about the client (node) who is running the application right now. Open the greeting-service.xml and switch to register Source. Between the tags <scr: ...> and </scr:component> add following line:

<reference bind="setEnvironment" cardinality="1..1" interface="org.eclipse.gyrex.cloud.environment.INodeEnvironment" 
name="INodeEnvironment" policy="static"/> 

This is a reference to a service with the interface INodeEnvironment. Only one instance of this service may be assigned to the sample.service component, and the instance is mandatory (cardinality=1..1). With the methode setEnvironment, implemented in GreetingServiceComponent our component calls this interface. If you open the GreetingServiceComponent, you see that the setEnvironment method calls the getNodeID() method of the interface, returning the current nodeid. By the way, this is how you call and use interfaces in a OSGi framework with declarative services.

In this tutorial we just want to use our interface in the same bundle. To do this, create a new package in the sample.jaxrs bundle. We will name it sample.jaxrs. This application at the end shows "greetings". In order to do this, we need the two classes HelloResource and GreetingResource. HelloResource will be started when you start this application later caused by the @path parameter. It just says hello and shows the current time. When you expand the url-path, the GreetingResource will be started. You have there the possibility to "send" greetings. For this tutorial, it is enough to show the greetings sorted by time of post. You can find the implementation of these classes in the uploaded filesystem.

After finishing this implementation, you can start the server and create an instance of this application, to mount it to an URL. Either you use the debug configurations from the tutorial Develope OSGi Declarative Services or you have to setup a new one. To setup a new one, right-click on your project and choose Debug As -> Debug Configurations... . The next right-click on Eclipse Application -> New opens the page to set up the configuration. In the box Name type in a name. In the section Program to Run select Run an application and org.eclipse.gyrex.boot.server. In the register Arguments add "-console" in the frame Program arguments. With click on Apply and Debug the server will start. In the console view the known commands to check the components states( 'ss'+name, 'start'+id, 'stop'+id, 'ls' ) are available.

In order to start the application in a browser open your favorite one. Be sure your server is started and type in the location bar: "http://localhost:3110/". The Gyrex Admin UI will open now. Open the "General" menu on the left. With a click on Applications a window opens where you can mount the application to an URL. Click on Add in the right.

Add new Application

In the new dialog you have to enter an Id, maybe the name of your application, select an Provider, choose your JAX-RS Application (in this example sample.jaxrs.application.component) and enter the Context. If you use the sample-implementation of HelloResource and GreetingResource, you must enter "/". However, this should be the root of your application. The JAX-RS HTTP application itself is now registered and is able to scan the bundle for all its root resources. No other JAX-RS resource needs to be registered. Furthermore you have to add a new mount. You will need this URL to access your application in the browser. This sample will have the mount "http:/sample". Once you have added everything, you can open a new tab and enter in the location bar "http://localhost:8080/sample/".

Http application

This will open a window saying hello and showing the current time, build by the HelloResource class. Now check in eclipse in the console view whether the greeting service is active by typing in: "ss sample". If both bundles state is ACTIVE, everything is fine. If not, just start the service bundle by typing in "'Start '+the bundleId". Now switch back to your browser and append your URL with greetings to have an URL like this "http://localhost:8080/sample/greetings". Now you will see the blank to type in your greetings. They will be shown underneath the headline Greetings. If you type in some greetings and click the submit button, all the greetings will be shown since you started the application, sorted by date of submit.

Now you should be able to create a JAX-RS application. It should be possible to create new services and bind them with an interface too.