Skip to main content
Jump to: navigation, search

Difference between revisions of "Gyrex/Learning Material/Develop JAX-RS"

(New page: {{Gyrex}} in progress...)
 
Line 1: Line 1:
{{Gyrex}}
+
{{Gyrex}}  
  
in progress...
+
This tutorial guides you throug the development of JAX-RS application using Gyrex. In the tutorial [http://http://wiki.eclipse.org/Gyrex/Develop_OSGi_DS ''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 now placed in a new bundle ''sample.jaxrs''. Both bundles with all containing manifests and classes you can find [[Media:JaxrsApplication-DevelopJAX-RS.zip| here (zip-file).]]
 +
 
 +
=== Requirements  ===
 +
 
 +
OSGi Declarative Services requires a target plattform has been set up as well as Java 6 runtime environment. <br>
 +
It is recommend to work through the tutorial [http://http://wiki.eclipse.org/Gyrex/Develop_OSGi_DS ''Develop OSGi Declarative Service''] first.
 +
''This tutorial was created using eclipse Indigo Service Release 2.'' <br>
 +
 
 +
=== Tutorial  ===
 +
 
 +
[[Image:Create_Project_2.jpg|thumb|Give additional properties and deselect the ''Activator'']]
 +
Create a new plug-in project and name it like '''"sample.jaxrs"'''. As target platform we will use an '''"Equinox"''' OSGi framework. The option for an ''Activator'' you can deselect, we don't need it. A template we don't need, either. To import required packages open the ''MANIFEST.MF'' and switch to the register ''MANIFEST.MF'' and add the following lines:
 +
<pre>
 +
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)"
 +
</pre>
 +
This line has to be added, too:
 +
<pre>
 +
Bundle-ActivationPolicy: lazy
 +
</pre>
 +
Remember the space line at the bottom of the text. <br>
 +
Further packages have to be added in the register ''Dependencies''. In section ''Automated Management of Dependencies'' click ''Add'' and add this packages one-by-one: [[Image:AddedPackages-SampleJaxrs-DevelopJAX-RS.jpg|thumb|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 he name '''"OSGI-INF"'''. In this folder add a new OSGi DS component (''Plug-In Development -&gt; Component Definition'') called '''"jaxrs-application.xml"''' with this properties:
 +
 
 +
*parnet folder: sample.jaxrs/OSGI-INF
 +
*filename: jaxrs-application.xml
 +
*name: hello.jaxrs.application.component
 +
*class: org.eclipse.gyrex.http.jaxrs.JaxRsApplicationProviderComponent
 +
 
 +
After creating this file open it and set following parameters:
 +
 
 +
*Activate: activate
 +
*Deactivate: deactivate
 +
*Provided Service: org.eclipse.gyrex.http.application.provider.ApplicationProvider
 +
*Property: "service.description" type="String" value="JAX-RS Application"
 +
 
 +
Now your ''jaxrs-application.xml'' should looks like this: [[Image:JaxrsApplicationXml-SampleJaxrs-DevelopJAX-RS.jpg|border|center|jaxrs-application.xml]]
 +
 
 +
At the end 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 add following line if it isn't allready done:
 +
<pre>
 +
Service Component: OSGI-INF/jaxrs-application.xml
 +
</pre>
 +
[[Image:ManifestMf-SampleJaxrs-DevelopJAX-RS.jpg|thumb|MANIFEST.mf with all added lines]]
 +
In this bundle ''sample.jaxrs'' the provided interface ''GreetingService'' will be placed. The service you implemented in the tutorial [http://http://wiki.eclipse.org/Gyrex/Develop_OSGi_DS ''Develop OSGi Declarative Service''] will use it. Therfore the package '''sample.service''' has to be created containig 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 line:
 +
<pre>
 +
Export-Package: sample.service
 +
</pre>
 +
''Sample.service'' has to be the name of the package containing the interface. <br>
 +
 
 +
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 allready 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 following lines:
 +
<pre>
 +
Export-Package: sample_imp.service
 +
Require-Bundle: sample.jaxrs
 +
</pre>
 +
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. Where it is placed tells the '''Require-Bundle''' line. Note that ''sample.jaxrs'' is the hole bundle you have implemented at the beginning. <br>
 +
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 ''&lt;scr: ...&gt;'' and ''&lt;/scr:component&gt;'' add following line:
 +
<pre>
 +
<reference bind="setEnvironment" cardinality="1..1" interface="org.gyrex.cloud.environment.INodeEnvironment"
 +
name="INodeEnvironment" policy="static"/>
 +
</pre>
 +
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 mendatory ('''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'' mehtod 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 first when you start this application later caused by the ''@path'' parameter. It just says hello to you and tells you the current time. When you expand the url-path the ''GreetingResource'' will be startet to. There you have the possibility to "send" greetings. Of course with this tutorial it's enough just to show the greetings sorted by time of post. The implementation of this classes you will find in the uploaded file-system.
 +
 
 +
With finishing this implementation you are able to start the server and create an instance of this application to mount 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 -&gt; Debug Configurations...'' . The next right-click on ''Eclipse Application -&gt; 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 ''Argmuents'' add '''"-console"''' in the frame ''Program arguments''. With clicks 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. <br>
 +
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. [[Image:AddNewApplication-DevelopJAX-RS.jpg|thumb|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'' there has to be entered a '''"/"'''. Howecer, this should be the root of your application. The JAX-RS HTTP application itself is now registered and is able to scann the bundle for all its root sesources, no other JAX-RS resource needs to be registered. Furthermore you have to add a new mount. This URL you will need 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/". [[Image:GreetingsWindow-DevelopJAX-RS.jpg|thumb|left|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 the greetings will be shown and every older greeting 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 an bind them with an interface, too.

Revision as of 11:19, 12 June 2012

Gyrex
Website
Download
Community
Mailing ListForumsIRCmattermost
Bugzilla
OpenHelp WantedBug Day
Contribute
Browse SourceProject Set File

This tutorial guides you throug the development of JAX-RS application 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 now placed in a new bundle sample.jaxrs. Both bundles with all containing manifests and classes you can find here (zip-file).

Requirements

OSGi Declarative Services requires a target plattform has been set up as well as Java 6 runtime environment.
It is recommend to work through the tutorial Develop OSGi Declarative Service first. 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 like "sample.jaxrs". As target platform we will use an "Equinox" OSGi framework. The option for an Activator you can deselect, we don't need it. A template we don't need, either. To import required packages open the MANIFEST.MF and switch to the register MANIFEST.MF and 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

Remember the space 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 this 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 he name "OSGI-INF". In this folder add a new OSGi DS component (Plug-In Development -> Component Definition) called "jaxrs-application.xml" with this properties:

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

After creating this file open it and set following parameters:

  • Activate: activate
  • Deactivate: deactivate
  • Provided Service: org.eclipse.gyrex.http.application.provider.ApplicationProvider
  • Property: "service.description" type="String" value="JAX-RS Application"
Now your jaxrs-application.xml should looks like this:
jaxrs-application.xml

At the end 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 add following line if it isn't allready done:

Service Component: OSGI-INF/jaxrs-application.xml 
MANIFEST.mf with all added lines

In this bundle sample.jaxrs the provided interface GreetingService will be placed. The service you implemented in the tutorial Develop OSGi Declarative Service will use it. Therfore the package sample.service has to be created containig 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 line:

Export-Package: sample.service

Sample.service has to 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 allready 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 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. Where it is placed tells the Require-Bundle line. Note that sample.jaxrs is the hole bundle you have 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.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 mendatory (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 mehtod 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 first when you start this application later caused by the @path parameter. It just says hello to you and tells you the current time. When you expand the url-path the GreetingResource will be startet to. There you have the possibility to "send" greetings. Of course with this tutorial it's enough just to show the greetings sorted by time of post. The implementation of this classes you will find in the uploaded file-system.

With finishing this implementation you are able to start the server and create an instance of this application to mount 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 Argmuents add "-console" in the frame Program arguments. With clicks 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 there has to be entered a "/". Howecer, this should be the root of your application. The JAX-RS HTTP application itself is now registered and is able to scann the bundle for all its root sesources, no other JAX-RS resource needs to be registered. Furthermore you have to add a new mount. This URL you will need 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 the greetings will be shown and every older greeting 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 an bind them with an interface, too.

Back to the top