The sample application https://github.com/steinarb/jersey-demo demonstrates how to use Jersey to provide a REST API from a Declarative Services (DS) component registering with the Pax Web Whiteboard Extender in apache karaf.

The way Jersey works is that it initially scans a package in the classpath for classes with JAX-RS annotations (e.g. @Path, @GET, @POST), and matches @Path annotations to possible endpoints in the REST API. When Jersey receives a REST call to a endpoint that matches a resource, Jersey will instanciate the appropriate resource class, call a method on the instanciated resource and then release the resource to Java garbage collection.

To be able to do something useful in these resource objects we use HK2 to dependency inject OSGi services.

To be able to dependency inject OSGi services into Jersey resources the following is done:

1. Create a whiteboard DS component exposing a Servlet service from Jersey ServletContainer, configuring the package to scan for API resources:

   @Component(
       service=Servlet.class,
       property={"alias=/jerseyinkaraf/api",
                 HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_INIT_PARAM_PREFIX+ServerProperties.PROVIDER_PACKAGES+"=no.priv.bang.demos.jerseyinkaraf.webapi.resources"
       } )
   public class CounterServiceServlet extends ServletContainer {
       ...
   }

2. Make the DS component of ServletContainer depend on OSGi services Counter and LogService

   public class CounterServiceServlet extends ServletContainer {
       ...
       @Reference
       public void setCounter(Counter counter) {
           this.counter = counter;
       }
   
       @Reference
       public void setLogservice(LogService logservice) {
           this.logservice.setLogService(logservice);
       }
       ...
   }

3. Override the ServletContainer.init(WebConfig) method, and:
   1. Call super.init(WebConfig) to make sure that a ServletConfig containing the information set up by the http whiteboard is created (contains the servletcontext, the servlet name and the package to scan for Jersey resources)

              super.init(webConfig);

   2. Copy the ResourceConfig of the ServletContainer (because that ServletConfig is immutable after the setup, and calling ServletConfig.register() will cause an IllegalOperationException)

              ResourceConfig copyOfExistingConfig = new ResourceConfig(getConfiguration());

   3. On the ServletConfig copy, register an anonymous inner inheriting AbstractBinder that in its configure() method registers the OSGi services injected into the ServletContainer as JSR330 injections in the Jersey resources

              copyOfExistingConfig.register(new AbstractBinder() {
                      @Override
                      protected void configure() {
                          bind(logservice).to(LogService.class);
                          bind(counter).to(Counter.class);
                      }
                  });

   4. Call ServletContainer.reload(ResourceConfig) with the ResourceConfig copy as the argument

              reload(copyOfExistingConfig);

      Note: The copyOfExistingConfig object at this point contains both the initial configuration created by the ServletContainer itself, and the two added OSGi services for dependency injection.

4. In the resources use JSR330 injections of the registered services

   @Path("/counter")
   @Produces(MediaType.APPLICATION_JSON)
   public class CounterResource {
   
       @Inject
       Counter counter;
   
       @GET
       public Count currentValue() {
           return counter.currentValue();
       }
   
       @POST
       public Count increment() {
           return counter.increment();
       }
   
   }

To try out the application:

1. Clone this project and build it:

   git clone https://github.com/steinarb/jersey-demo.git
   cd jersey-demo
   mvn clean install
   

2. Install apache karaf and start it  according to the karaf quick start guide (alternatively, see Develop OSGi applications using karaf)
3. At the karaf command line give the following commands

   feature:repo-add mvn:no.priv.bang.demos.jerseyinkaraf/jerseyinkaraf/LATEST/xml/features
   feature:install jerseyinkaraf.webapi
   feature:install jerseyinkaraf.webgui

4. Open http://localhost:8181/jerseyinkaraf in a web browser and click on the button to increment the counter value

The demo consists of the following maven project and modules:

1. jerseyinkaraf The top project which in addition to containing common configuration, and the list of modules, also creates a karaf feature repository containing the features of all bundles created in the modules, and attaches the karaf feature repository to the maven artifact
2. jerseyinkaraf.servicedef which is an OSGi bundle containing the interfaces and bean defining the OSGi service for doing the counting
3. jerseinkaraf.services which is an OSGi bundle containing a DS component implementing the services
4. jerseyinkaraf.webapi which is an OSGi bundle containing a DS component that defines a REST API that plugs into the Web Whiteboard Extender and exposes the OSGi services
5. jerseyinkaraf.webgui which is an OSGi bundle containing a DS component that exposes an HTML and JavaScript application that plugs into the Web Whiteboard Extender