Minimal OSGI Sample Documentation ================================= Introduction ------------- You may not know it but CXF actually has an OSGI bundle for JAX-RS. Unfortunately, documentation on how to use it is very hard to come by. This sample demonstrates the minimal amount of bundles necessary and code tweaks required to get a sample that uses CXF's JAX-RS implementation to work correctly in an OSGI environment. This is not necessarily the best way to achieve the above. In particular, use of CXF-specific syntax (as much as possible). However, I believe it's a good balance between code readability and simplicity. Introduction Pre-requisites Sample walkthrough Code walkthrough Deployment notes Running the sample Bundles Pre-requisites -------------- To take advantage of this sample, you should have a working knowledge of the following: JSR-311 JAX-RS * Maven * OSGI * Servlet Sample walkthrough ------------------ Code walkthrough Let's start off with a basic JSR-311 JAX-RS application that you would like to deploy in an OSGI environment: * SampleResource * SampleApplication With this sample application, if you go to a URL that looks like the following, you should get a "My Sample Text" in the browser: http://:/ To get this application running in an OSGi environment, when the HTTP OSGI service starts up, CXFNonSpringJaxrsServlet needs to be registered. This is accomplished in the code found inside the Activator. We use ServiceTracker to take care of the hard work of monitoring when the HTTP OSGI service comes up and registering ourselves to it. The big gotcha here though is our application is in one bundle but CXF is contained within another bundle. Because OSGI creates one classloader for each bundle and CXF uses reflection to discover applications, this discovery won't work in an OSGI environment. To get around this limitation, we subclass CXFNonSpringJaxrsServlet with our own SampleServlet that refers directly to our SampleApplication class. With the necessary imports inside the MANIFEST.MF, OSGI will set up the correct bundle linkage at runtime and we won't get the dreaded ClassNotFound exception. Deployment notes By default, CXF's default OSGI bundle includes a whack of dependencies that aren't necessary to get the core JAX-RS running. This sample strips away all the fluff and only includes the necessary JARs. You can check the pom.xml accompanying this example to see many of the dependencies that have been excluded. To ease deployment in different OSGI environments, we take advantage of Apache Felix's File Install bundle to use a directory-based deployment structure. With a few tweaks here and there, you can configure this sample to run in different OSGI environments. By default, it works in Eclipse Equinox but it runs sufficiently well in Apache Felix as well. Running the sample ------------------ You can run it directly from maven using the following command mvn exec:exec Note that when you run the sample this way, your input to the OSGI console will not echo. No worries, it'll still be processed! If you want to run it manually, do the following 1) mvn package 2) cd target/deliver/jax_rs_minimal_osgi--equinox/jax_rs_minimal_osgi-/ 3) java -jar org.eclipse.osgi-3.6.2.R36x_v20110210.jar If all goes well, the Eclipse Equinox environment will start up and File Install will install all the necessary bundles. If you visit the following URL in your favorite browser on the machine, you should find it returns some text from SampleApplication: http://localhost:8080/ Bundles ------- If you're using Java 6, here is a listing of the bundles that are running inside Eclipse Equinox to make this example run successfully: id State Bundle 0 ACTIVE org.eclipse.osgi_3.6.2.R36x_v20110210 ; OSGI system runtime 1 ACTIVE org.apache.felix.fileinstall_3.1.10 ; Bundle deployment system - may be removed if you have some other way to deploy 2 ACTIVE org.codehaus.jettison.jettison_1.3.0 ; CXF JAX-RS dependency for JSON 3 ACTIVE org.mortbay.jetty.util_6.1.24 ; HTTP OSGI service dependency 4 ACTIVE org.apache.cxf.bundle-jaxrs_2.5.0.SNAPSHOT ; CXF JAX-RS bundle 5 ACTIVE org.apache.neethi_3.0.1 ; CXF JAX-RS dependency 6 ACTIVE org.eclipse.osgi.services_3.2.100.v20100503 ; CXF JAX-RS dependency / HTTP OSGI service dependency 7 ACTIVE org.apache.felix.http.whiteboard_2.2.0 ; HTTP OSGI service dependency 8 ACTIVE org.mortbay.jetty.security_6.1.24 ; HTTP OSGI service dependency 9 ACTIVE org.mortbay.jetty.server_6.1.24 ; HTTP OSGI service dependency 10 ACTIVE org.apache.felix.http.bundle_2.2.0 ; HTTP OSGI service dependency 11 ACTIVE org.apache.felix.http.base_2.2.0 ; HTTP OSGI service dependency 12 ACTIVE org.apache.servicemix.specs.jsr311-api-1.1_1.8.0 ; CXF JAX-RS dependency 13 ACTIVE org.apache.felix.http.bridge_2.2.0 ; HTTP OSGI service dependency 14 ACTIVE minimalosgi_0.0.0 ; Sample application 15 ACTIVE org.apache.felix.http.api_2.2.0 ; HTTP OSGI service dependency 16 ACTIVE org.apache.felix.http.jetty_2.2.0 ; HTTP OSGI service dependency If you're using Java 5, there's a few more bundles that are added to make things run successfully id State Bundle 17 ACTIVE org.apache.geronimo.specs.geronimo-activation_1.1_spec_1.1.0 ; CXF JAX-RS dependency 18 ACTIVE org.apache.servicemix.specs.stax-api-1.0_1.9.0 ; CXF JAX-RS dependency 19 ACTIVE org.apache.servicemix.specs.activation-api-1.1_1.9.0 ; CXF JAX-RS dependency 20 ACTIVE org.apache.servicemix.specs.jaxb-api-2.2_1.9.0 ; CXF JAX-RS dependency 21 ACTIVE org.apache.geronimo.specs.geronimo-annotation_1.0_spec_1.1.1 ; CXF JAX-RS dependency