# OSGi

## Feature Overview

OSGi support was added to the Jersey version 1.2. Since then, you should be able to utilize standard OSGi means to run Jersey based web applications in OSGi runtime as described in the OSGi Service Platform Enterprise Specification. The specification could be downloaded from http://www.osgi.org/Download/Release4V42.

The two supported ways of running an OSGi web application are

- WAB (Web Application Bundle)
- Http Service

WAB is in fact just an OSGified WAR archive. Http Service feature allows you to publish Java EE Servlets in the OSGi runtime.

Two examples were added to the Jersey distribution to depict the above mentioned features and show how to use them with Jersey

- Hello world WAB

- Simple OSGi Http Service application

Both examples are multi-module maven projects and both consist of an application OSGi bundle module and a test module. The tests are based on Pax Exam framework. Both examples also include a readme file containing instructions how to manually run the application using Apache Felix framework.

The rest of the chapter describes how to run the above mentioned examples on GlassFish 3.1.2 application server. Since GlassFish utilizes Apache Felix, an OSGi runtime comes out of the box with GlassFish. However, for security reasons, the OSGi shell has been turned off. You can explicitly enable it. Either by starting GlassFish with `asadmin -Dglassfish.osgi.start.level.final=3 start-domain` or by setting `glassfish.osgi.start.level.final` property to `3` in `glassfish/config/osgi.properties` file. Presuming you have the default GlassFish instance running, after enabling shell as described above, you should now be able to connect to the Felix console with

            telnet localhost 6666

You should then see Apache Felix prompt similar to following

    Trying ::1...
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    ____________________________
    Welcome to Apache Felix Gogo

    g!

## WAB Example

As mentioned above, WAB is just an OSGified WAR archive. Besides the ususal OSGi headers it must in addition contain a special header, `Web-ContextPath`, specifying the web application context path. Our WAB has (beside some other) the following headers present in the manifest

    Web-ContextPath: helloworld
    Webapp-Context: helloworld
    Bundle-ClassPath: WEB-INF/classes

where the second one is ignored by GlassFish, but is needed by other containers not fully compliant with the OSGi Enterprise Specification mentioned above. The third manifest header worth mentioning is the `Bundle-ClassPath` specifying where to find the application Java classes within the bundle archive.

For more detailed information on the example please see the source code.

Following is the listing showing how to actually install and run the WAB on GlassFish. Be sure to replace <version> with the current Jersey version and <repository> with either snapshots or releases based on whether you depend on a snapshot or stable release version of Jersey respectively:

    g! install https://maven.java.net/service/local/artifact/maven/redirect?r=<repository>&g=com.sun.jersey.samples.helloworld-osgi-webapp&a=war-bundle&v=<version>&e=war
    Bundle ID: 246
    g! start 246

In the above listing, the number 246 represents handler to the OSGi bundle you have just installed. Bundle numbers are allocated dynamically. It means, you might be given a different handler. It is important to always use the correct bundle number as specified by the Felix runtime in the "Bundle ID:" response.

After the WAB gets installed and activated by the above mentioned commands, you should be able to access the deployed Jersey resource at http://localhost:8080/helloworld/webresources/helloworld

## Http Service Example

OSGi Http Service support currently does not come out of the box with GlassFish, but is provided with a separate OSGi bundle, http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar. You will need to enable the feature first, by installing that bundle. After that, you can install and activate the Jersey application bundle. Following is the listing showing how both bundles could be installed and activated (Be sure to replace <version> with the current Jersey version and <repository> with either snapshots or releases based on whether you depend on a snapshot or stable release version of Jersey respectively):

    g! install http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar
    Bundle ID: 247
    g! install https://maven.java.net/service/local/artifact/maven/redirect?r=<repository>&g=com.sun.jersey.samples.osgi-http-service&a=bundle&v=<version>&e=jar
    Bundle ID: 248
    g! start 247 248

Now you should be able to access the Jersey resource at http://localhost:8080/osgi/jersey-http-service/status

Finally, to close the Felix console session just press `[Ctrl]-[d]`.