Gyrex/Learning Material/Develop OSGi DS
|Mailing List • Forums • IRC • mattermost|
|Open • Help Wanted • Bug Day|
|Browse Source • Project Set File|
This article will show you how to use OSGi Declarative Services in Gyrex. As a example the GreetingService will be implemented and can be used in later tutorials to let the consumer "greet". Using Declarative Services the GreetingService will be made available in the OSGi framework. To make this possible an OSGi DS component has to be created. A well structured pattern provides the service as an interface which will be re-implemented in a component class. This class keeps the reference to the real implementation and only delegates to it. The hole sample-project with all classes described later in the article you can find here (zip-file).
The OSGi Declarative Services Tutorial requires a already setup Gyrex target plattform as well as Java 6 or Java 7 runtime environment.
This tutorial was created using eclipse Indigo Service Release 2.
The first step is to create a new plug-in project by clicking File -> New -> Other. Typing in "Plug-In Project" and select the shown option. After clicking Next, give your project a name like "name.service". In the section Target Platform select "Equinox" as the OSGi framework. At this time we don't need an Activator so deselect it on the next page. Here you also can give a special name for your plug-in. On the next page you can choose, whether you want to create the plug-in with templates, but just remove the check mark on this page. Clicking Finish on the next page the project will be created.
Now it's required to import some packages. To do so open the MANIFEST.MF of your project. You will find this file in the folder META-INF. Switch to the register MANIFEST.MF and add following lines:
Import-Package: org.apache.commons.lang;version="[2.4.0,3.0.0)", org.apache.commons.lang.time;version="[2.4.0,3.0.0)", org.eclipse.gyrex.cloud.environment;version="[1.0.0,2.0.0)";resolution:=optional, org.osgi.service.component;version="[1.2.0,2.0.0)", org.slf4j;version="[1.6.0,2.0.0)"
Add following line to the MANIFEST.MF, too.
Bundle-ActivationPolicy: lazyNote that there has to be a space line below the text.
Furthermore you have to add dependencies in the MANIFEST. Switch to register Dependencies to section Automated Management of Dependencies. There you have to add following packages:
org.slf4j.api org.apache.commons.lang org.eclipse.gyrex.cloud org.eclipse.osgi org.eclpse.osgi.services
With this packages you will be able to start the server at the end of this tutorial with the OSGi framework in which your bundle is available. You still need to implement your service. To do this you have to create a new package with the same name as your project with a right-click on src in your project selecting New -> Package. This package will contain at least 4 classes. In this example there are:
sample.service.GreetingService sample.service.GreetingServiceImpl sample.service.GreetingServiceProvider sample.service.GreetingServiceComponent
GreetingService is an interface providing methods. This methods later will be re-implemented by several separate bundles, which can be later added dynamically to the running system. Therefore this class wouldn't be placed in the same bundle as the classes re-implementing the interface, but in a seperate bundle. In this example there are three methods to be implemented.
Colleytion<String> getGreetings() void processGreetings() void sayHello(final String greeting)
With this methods the consumer can "greet" (sayHello), get a list of all sended greetings (getGreetings) and the greetings can processed. The real implementation of the interface are in the class GreetingServiceImpl. The delegation to this methods is done by the class GreetingServiceComponent. There is a implementation of the methods, too. But only to delegate to the referenced "real" implementation. Further Methods are implemented to start/activate and stop/deactivate components. The GreetingServiceProvider provides the access to the GreetingService instance.
After you opened this file switch to the register Source. There, methods activate and deactivate have to be added.
At the end you have to tell 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/greetings-service.xml
With clicking Apply and then Debug the server will start. Now open the console view where you can monitor all necessary bundles are starting. Once you read the line: [Worker-0] INFO o.e.jetty.server.AbstractConnector - Started SelectChannelConnector@0.0.0.0:3110 first press Enter and you can issue a few console commands to check your components state. Possible commands are:
- 'ss '+name - shows all bundlesof "name", there state and ID ('ss sample')
- 'start '+id - starts the bundle called by id ('start 297')
- 'stop '+id - stops the bundle called by id ('stop 297')
- 'ls' - shows all available components
At this point this tutorial finishs. Now you have implemented a component in OSGi Declarative Services with the possibilty to change the state of it. It's the basis to implement whole OSGi frameworks. How it's said at the beginning, an interface normaly is separated in an extra bundle from which you want to access the real implementations dynamicaly according the scenario. This will be shown in a next tutorial.