Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Gyrex/Learning Material/Develop JAX-RS
|Mailing List • Forums • IRC • mattermost|
|Open • Help Wanted • Bug Day|
|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.
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.
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:
Don't forget to add the empty line at the bottom of the text.
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"
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
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:
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.
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.