[[using-declarative-services]] Using declarative services -------------------------- Declarative Services (DS) are very common to define OSGi services. The DS bundle scans all bundles (extender pattern), parses the component definition xml-file and provides services based on that information. DS may also be used to define references to other services. For instance service A may require 0:n services of type B. The DS runtime will ensure, that they are properly injected into the service A. References to other services also influence the lifecycle of a service. For instance service A requires 1:1 of service C. Thus service A will not be activated before service C is injected properly. This short overview of OSGi-DS is enough to understand the example defined below. [Error: Macro 'TableOfContents' doesn't exist] [[setup-example]] Setup example ~~~~~~~~~~~~~ To follow my explanation * clone repository from https://github.com/lunifera/lunifera-Vaadin-examples.git * use Import -> "Existing Maven Projects" in Eclipse IDE (Make sure that m2e is installed) * expand `org.lunifera.example.Vaadin.osgi.bootstrap.ds/setup` and set `targetDS.target` * `open targetDS.target` ** wait until resolved ** if error, then select all repository in target and press update button on the right side ** wait until resolved ** press "set as target platform" * Now there should be no problems. * To build the project use `mvn clean verify` You will recognize that the bundle does not contain an `Activator`. Thats not necessary since we use OSGi services managed by OSGi-DS. The component runtime of DS manages the lifecycle of the services. Instead of an activator we are using the class `ServiceComponent`. It contains all logic to wire things together properly. [[servicecomponent]] ServiceComponent ~~~~~~~~~~~~~~~~ The service component will become instantiated by OSGi DS and DS controls its lifecycle. If the bundle containing the class is stopped, the service will be deactivated by invoking `deactivate()`. If mandatory references can be resolved, the service will be activated automatically. The `bindService` and `unbindService` are invoked by DS, if a http service becomes available or unavailable. We do not need to use a `ServiceTracker` anymore to get notified about the `HttpService`-lifecycle. All that stuff is handled by OSGi-DS. [source,java] .... package org.lunifera.example.Vaadin.osgi.bootstrap.ds; import javax.servlet.ServletException; import org.osgi.framework.Bundle; import org.osgi.framework.BundleEvent; import org.osgi.framework.BundleListener; import org.osgi.service.component.ComponentContext; import org.osgi.service.http.HttpService; import org.osgi.service.http.NamespaceException; /** * The service will look for the HttpService and registers the Vaadin servlet at * it. */ public class ServiceComponent implements BundleListener { private HttpService httpService; private ResourceProvider resourceProvider; /** * Called by OSGi DS if the component is activated. * * @param context */ protected void activate(ComponentContext context) { handleStartedBundles(context); context.getBundleContext().addBundleListener(this); } /** * Called by OSGi DS if the component is deactivated. * * @param context */ protected void deactivate(ComponentContext context) { context.getBundleContext().removeBundleListener(this); resourceProvider = null; } /** * Binds the http service to this component. Called by OSGi-DS. * * @param service */ protected void bindHttpService(HttpService service) { httpService = service; try { // register the servlet at the http service httpService.registerServlet("/", new SimpleVaadinServlet(), null, getResourceProvider()); } catch (ServletException e) { e.printStackTrace(); } catch (NamespaceException e) { e.printStackTrace(); } } /** * Unbinds the http service from this component. Called by OSGi-DS. * * @param service */ protected void unbindHttpService(HttpService service) { // unregister the servlet from the http service httpService.unregister("/"); } .... If a http service is available, it becomes injected and will be used to register the Vaadin servlet at it. If it becomes unbound (bundle containing the http service stopped), the servlet will be unregistered. [[usecase-study]] Usecase study ~~~~~~~~~~~~~ Imagine the following usecase. There are 2 bundle providing http services. * `org.abc.http.jetty` * `org.abc.http.tomcat` (can be achieved using virgo for instance) [[what-you-may-do...]] What you may do... ^^^^^^^^^^^^^^^^^^ * Start the jetty bundle → then jetty-httpService will be bound to our service component and Vaadin is running on a jetty * Start the tomcat bundle → nothing will happen so far (service component requires 0:1 http services - see below) * Stop the jetty bundle → The jetty-httpService will become unbound and Vaadin stops * Some milliseconds later the tomcat-httpService will be bound automatically → Vaadin will become installed to the tomcat * Update the jetty bundle in the running OSGi environment (new bundle with latest version is installed and old uninstalled) * Start the jetty bundle (with the new version) again * Stop tomcat bundle → The tomcat-httpService will become unbound and Vaadin stops * Some milliseconds later the jetty-httpService will be bound automatically → Vaadin will become available at jetty That’s real modularity... Give it a try and play around. Indeed, you won't write your own http services. But there are a lot of other use cases too. I will blog about them later when I am talking about "Content Provider by OSGi DS". [[servicecomponent-definition]] ServiceComponent-Definition ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The service component definition is the description about the service. It defines the implementation class, the provided services and the referenced (required) services. Eclipse PDE comes with an editor to define them. Expand the `OSGI-INF` folder in the bundle and double click `VaadinComponent.xml`. Now you see the definition of the service component. [source,xml] .... .... * Line 2 defines the name of the service. Feel free to insert a unique name * Line 3 defines the class name of the service class that needs to become instantiated * Line 4 defines a reference to a required service - the HttpService * *bind* means the method that is called to bind the HttpService instance to the service instance * *unbind* means the method that is called to unbind the HttpService instance from the service instance * *cardinality* defines how many services may / must be bound - 0..1, 1..1, 0..n, 1..n * *interface* is the name of the service that should be bound A *very important* issue is an entry in the `MANIFEST.mf`. Using the manifest header `Service-Component: OSGI-INF/*.xml` all xml files from OSGI-INF are registered as component definitions to the DS runtime. If you miss to add this statement, DS will never resolve your service! [[run-example]] Run example ~~~~~~~~~~~ To run the example, we need to prepare an OSGi-launch-configuration. The following bundles are required to run the example properly. In difference to part 1, the `org.eclipse.equinox.ds` and `org.eclipse.equinox.util` bundles are required. Otherwise OSGi-DS will not become started. [cols=",,",options="header",] |============================================================ |bundle |start level |autostart |org.lunifera.example.Vaadin.osgi.bootstrap.ds |default |true |com.Vaadin.client-compiled |default |false |com.Vaadin.server |default |false |com.Vaadin.shared |default |false |com.Vaadin.shared.deps |default |false |com.Vaadin.themes |default |false |javax.annotation |default |false |javax.servlet |default |false |org.apache.felix.gogo.command |default |false |org.apache.felix.gogo.runtime |default |false |org.apache.felix.gogo.shell |default |false |org.eclipse.equinox.console |default |false |org.eclipse.equinox.ds |1 |false |org.eclipse.equinox.http.jetty |default |false |org.eclipse.equinox.http.servlet |default |false |org.eclipse.equinox.util |default |false |org.eclipse.jetty.continuation |default |false |org.eclipse.jetty.http |default |false |org.eclipse.jetty.io |default |false |org.eclipse.jetty.security |default |false |org.eclipse.jetty.server |default |false |org.eclipse.jetty.servlet |default |false |org.eclipse.jetty.util |default |false |org.eclipse.osgi |default |false |org.eclipse.osgi.services |default |false |org.json |default |false |org.jsoup |default |false |============================================================ To start a jetty server on a proper port, use the VM argument: `-Dorg.osgi.service.http.port=8082` in your launch configuration. Now you can access the Vaadin page under http://localhost:8082. Have fun! By http://de.gravatar.com/florianpi[Florian Pirchner] - based on lunifera.org - OSGi components for business applications