Link to two Felix instances

Here is yet another post in Maven + Apache Felix + CXF + DOSGi series.

Here I will show how to use Apache CXF DOSGi for cosuming remote services. You may see the sources on my GitHub account.

We will have three projects dosgiRemote.service, dosgiRemote.service.api and dosgiRemote.consumer. dosgiRemote.service.api provides an interface for a service. dosgiRemote.service provides implementation for the service. dosgiRemote.consume will consume the service.
dosgiRemote.service.api has to be shared between dosgiRemote.service and dosgiRemote.consumer as both has to know which service they are publishing and consuming. dosgiRemote.service.api and dosgiRemote.service will run in one OSGi container. dosgiRemote.service.api and dosgiRemote.consumer will run in another OSGi container. You may see how to do that in Eclipse in the previous post.

dosgiRemote.service.api contains the following interface to a service:

package dk.sorokin.maksim.dosgiRemote.service.api;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("greeter")
public interface Greeter {

  @GET
  @Path("sayHello/{name}")
  @Produces(MediaType.TEXT_PLAIN)
  String sayHello(@PathParam("name") String name);
}

dosgiRemote.service provides the following implementation:

package dk.sorokin.maksim.dosgiRemote.internal.service;

import dk.sorokin.maksim.dosgiRemote.service.api.Greeter;

public class GreeterImpl implements Greeter {

  public String sayHello(String name) {
    return "Hello, " + name;
  }
}

Also, dosgiRemote.service registers a service in the following way:

package dk.sorokin.maksim.dosgiRemote.internal;

import java.util.Dictionary;
import java.util.Hashtable;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import dk.sorokin.maksim.dosgiRemote.internal.service.GreeterImpl;
import dk.sorokin.maksim.dosgiRemote.service.api.Greeter;

public class Activator implements BundleActivator {

  public void start(BundleContext context) throws Exception {
    Dictionary<String, String> restProps = new Hashtable<String, String>();

    restProps.put("service.exported.interfaces", "*");
    restProps.put("service.exported.configs", "org.apache.cxf.rs");
    restProps.put("service.exported.intents", "HTTP");
    restProps.put("org.apache.cxf.rs.address", "http://localhost:8080/");
    context.registerService(Greeter.class.getName(), new GreeterImpl(), restProps);
  }

  public void stop(BundleContext context) throws Exception {
    //
  }
}

dosgiRemote.consumer will have OSGI-INF\remote-service\remote-services.xml, according to DOSGi documentation:

<?xml version="1.0" encoding="UTF-8"?>
<service-descriptions xmlns="http://www.osgi.org/xmlns/sd/v1.0.0">
  <service-description>
    <provide interface="dk.sorokin.maksim.dosgiRemote.service.api.Greeter" />
    <property name="service.exported.interfaces">*</property>
    <property name="service.exported.configs">org.apache.cxf.rs</property>
    <property name="service.exported.intents">HTTP</property>
    <property name="org.apache.cxf.rs.address">http://localhost:8080</property>
  </service-description>
</service-descriptions>

And the Activator class for dosgiRemote.consumer will be:

package dk.sorokin.maksim.dosgiRemote.consumer.internal;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.util.tracker.ServiceTracker;

import dk.sorokin.maksim.dosgiRemote.service.api.Greeter;

public class Activator implements BundleActivator {

  @Override
  public void start(BundleContext context) throws Exception {
    ServiceTracker serviceTracker = new ServiceTracker(context, Greeter.class.getName(), null) {
      @Override
      public Object addingService(ServiceReference reference) {
        Object result = super.addingService(reference);

        Object svc = context.getService(reference);
        if (svc instanceof Greeter) {
          final Greeter greeter = (Greeter) svc;
          System.out.println(greeter.sayHello("Max"));
        }

        return result;
      }
    };
    serviceTracker.open();
  }

  public void stop(BundleContext context) throws Exception {
    //
  }
}

We will have two startup configuration for Apache Felix, as described above. The first one:

felix.auto.deploy.action=install,start
felix.log.level=1

org.osgi.framework.storage.clean=onFirstInit

felix.auto.start.1 = \
 assembly:/C:/projects/dosgiRemote/dosgiRemote.service.api/target/classes \
 assembly:/C:/projects/dosgiRemote/dosgiRemote.service/target/classes

And the second one:

felix.auto.deploy.action=install,start
felix.log.level=1

org.osgi.framework.storage.clean=onFirstInit

felix.auto.start.1 = \
 assembly:/C:/projects/dosgiRemote/dosgiRemote.service.api/target/classes \
 assembly:/C:/projects/dosgiRemote/dosgiRemote.service/target/classes

Launch the first configuration and then the second. You should see the following message in the console:

Hello, Max

You could also see the same message in the browser on http://localhost:8080/greeter/sayHello/Max.

You may pass objects as well. Refer to previous posts to do that.

You can take the sources from may GitHub account.

Sometimes in the project plain Maven dependencies has to be used. A simple strategy to use those in OSGi project handled by Maven is to have a separate module, containing all non-OSGi dependencies and converting those to OSGi bundles using Apache Felix Maven Bundle Plugin.
So one may have the following structure of the project:

project
    ...
    project.nonOsgiDependencies
        project.nonOsgiDependencies.base64
        project.nonOsgiDependencies.mysqlConnector
        project.nonOsgiDependencies.xercesImpl

This nonOsgiDependencies projects would contain just a pom.xml file, which would have a dependency on required maven dependency and would use maven-bundle-plugin to wrap it. Here is an example of such pom.xml for net.iharder:base64

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <artifactId>project.nonOsgiDependencies</artifactId>
    <groupId>dk.sorokin.maksim</groupId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>ecosystem.nonOsgiDependencies.base64</artifactId>

  <name>net.iharder:base64 Maven Dependency</name>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <executions>
          <execution>
            <id>wrap-dependency</id>
            <goals>
              <goal>bundle</goal>
            </goals>
            <configuration>
              <instructions>
                <Embed-Dependency>*</Embed-Dependency>
                <Export-Package>net.iharder</Export-Package>
              </instructions>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>net.iharder</groupId>
      <artifactId>base64</artifactId>
      <version>2.3.8</version>
    </dependency>
  </dependencies>
</project>

We will have three projects here. The first one defines an interface for a service. Another one provides implementation for it. And the third one will provide security.

dosgiSecurity
    dosgiSecurity-api
    dosgiSecurity-impl
    dosgiSecurity-security

dosgiSecurity will be just a holder project.

Our interface HelloService in bundle dosgiSecurity-api will be similar to the one we defined in previous posts:

package dk.sorokin.maksim.dosgiSecurity.api;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("helloService")
public interface HelloService {

  @GET
  @Path("sayHello/{name}")
  @Produces(MediaType.TEXT_PLAIN)
  String sayHello(@PathParam("name") String name);
}

And implementation class HelloServiceImpl in bundle dosgiSecurity-impl:

package dk.sorokin.maksim.dosgiSecurity.impl.internal.service;

import dk.sorokin.maksim.dosgiSecurity.api.HelloService;

public class HelloServiceImpl implements HelloService {

  public String sayHello(String name) {
    return "Hello " + name;
  }
}

And SecurityFilter in bundle dosgiSecurity-security, is just a servlet filter. It checks for Authorization header and verifies it:

package dk.sorokin.maksim.dosgiSecurity.impl.internal.service;

import dk.sorokin.maksim.dosgiSecurity.api.HelloService;

public class HelloServiceImpl implements HelloService {

  public String sayHello(String name) {
    return "Hello " + name;
  }
}

The service is published in an Activator in dosgiSecurity.impl:

package dk.sorokin.maksim.dosgiSecurity.impl.internal;

import java.util.Dictionary;
import java.util.Hashtable;

import javax.servlet.Filter;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import dk.sorokin.maksim.dosgiSecurity.api.HelloService;
import dk.sorokin.maksim.dosgiSecurity.impl.internal.service.HelloServiceImpl;
import dk.sorokin.maksim.dosgiSecurity.security.SecurityFilter;

public class Activator implements BundleActivator {

  public void start(BundleContext context) throws Exception {
    Dictionary<String, String> restProps = new Hashtable<String, String>();

    restProps.put("service.exported.interfaces", "*");
    restProps.put("service.exported.configs", "org.apache.cxf.rs");
    restProps.put("service.exported.intents", "HTTP");
    restProps.put("org.apache.cxf.rs.httpservice.context", "/secured");
    restProps.put("org.apache.cxf.rs.address", "http://localhost:8080/");
    context.registerService(HelloService.class.getName(), new HelloServiceImpl(), restProps);

    Dictionary<String, String> filterProps = new Hashtable<String, String>();
    filterProps.put("org.apache.cxf.httpservice.filter", Boolean.TRUE.toString());
    filterProps.put("servletNames", "none");
    context.registerService(Filter.class.getName(), new SecurityFilter(), filterProps);
  }

  public void stop(BundleContext context) throws Exception {
    //
  }
}

And a Felix Launcher (refer to the first post in series) is:

felix.auto.deploy.action=install,start
felix.log.level=1

org.osgi.framework.storage.clean=onFirstInit

felix.auto.start.1 = \
 assembly:/C:/projects/dosgiSecurity/dosgiSecurity.security/target/classes \
 assembly:/C:/projects/dosgiSecurity/dosgiSecurity.api/target/classes \
 assembly:/C:/projects/dosgiSecurity/dosgiSecurity.impl/target/classes

Now build all that with Maven using mvn clean install and run it (assuming that you have DOSGi Single Bundle Distribution in Felix, as we discussed in previous posts). When Felix is launched, go to http://localhost:8080/secured/helloService/sayHello/Max. You should see:

HTTP ERROR: 403

FORBIDDEN
RequestURI=/secured/helloService/sayHello/Max

Powered by Jetty://

Now launch Fiddler2 (or similar program) and build custom request with Request Builder with the same url as shown above. And add the following line in "Request Headers":

Authorization: Basic U3V6eTpyb2NrZXQ=

You should get:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Tue, 02 Aug 2011 15:15:43 GMT
Content-Length: 9
Server: Jetty(6.1.x)

Hello max

Source files can be found here

In this post I showed you how to create a RESTful webservice consuming and creating a String. However, the example was using @GET method. Here I will show, what changes need to be done in order to consume input from @POST. As usual, sources are available in the end of the post.

Simply change @GET to @POST and remove @PathParam("name") from MyService webservice interface:

package test.bundle;

import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("myService")
public interface MyService {

  @POST
  @Path("sayHello")
  @Produces(MediaType.TEXT_PLAIN)
  String sayHello(String name);
}

Then you can make POST requests to http://localhost:8080/myService/sayHello with request body. I suggest using Fiddler2 tool for debugging.

If you want to consume object (well, XML and then convert it into object), you will need to create message body reader and reference it in the Activator. An example of message body reader could be:

package dk.codeunited.ecosystem.integration.myRecord.pub.api;

import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;

import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.ext.MessageBodyReader;
import javax.ws.rs.ext.Provider;

import dk.codeunited.ecosystem.integration.myRecord.pub.api.pojos.Logbook;

@Provider
public class MyMessageReaderProvider implements MessageBodyReader<MyMessage> {

  @Override
  public boolean isReadable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mt) {
    return true;
  }

  @Override
  public MyMessage readFrom(Class<MyMessage> clazz, Type t, Annotation[] a, MediaType mt,
      MultivaluedMap<String, String> headers, InputStream is) {
    // reader an object from InputStream
  }
}

And then registration in Activator:

    restProps.put("org.apache.cxf.rs.provider", MyMessageReaderProvider.class.getName());

Here are source to POST example

You can obtain the sources from this post on my github:
https://github.com/mah01/examples/tree/master/muleHelloStandalone

I will just show the keypoints of the application and changes, that were different from "hello" application in Mule distributable.

First of all, the pom.xml file. We download all required Mule dependencies in order to run the example. Note, that we use Mule Maven repository, because for some reason Mule artifacts has transitive dependencies on OSGified versions of certain libraries, which are not contained in Maven Central:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dk.sorokin.maksim</groupId>
  <artifactId>muleHelloStandalone</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>war</packaging>

  <name>Self-Contained Standalone Mule Hello World</name>
  <description>The sources for this application were copied from Mule distributable</description>

  <properties>
    <mule.version>3.1.2</mule.version>
  </properties>

  <build>
    <resources>
      <resource>
        <directory>src/main/app</directory>
      </resource>
      <resource>
        <directory>src/main/resources</directory>
      </resource>
    </resources>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.codehaus.groovy</groupId>
      <artifactId>groovy-all</artifactId>
      <version>1.8.1</version>
    </dependency>

    <dependency>
      <groupId>org.mule</groupId>
      <artifactId>mule-core</artifactId>
      <version>${mule.version}</version>
    </dependency>

    <dependency>
      <groupId>org.mule</groupId>
      <artifactId>mule-core</artifactId>
      <version>${mule.version}</version>
      <scope>test</scope>
      <type>test-jar</type>
    </dependency>

    <dependency>
      <groupId>org.mule.modules</groupId>
      <artifactId>mule-module-builders</artifactId>
      <version>${mule.version}</version>
    </dependency>

    <dependency>
      <groupId>org.mule.modules</groupId>
      <artifactId>mule-module-scripting</artifactId>
      <version>${mule.version}</version>
    </dependency>

    <dependency>
      <groupId>org.mule.transports</groupId>
      <artifactId>mule-transport-vm</artifactId>
      <version>${mule.version}</version>
    </dependency>

    <dependency>
      <groupId>org.mule.transports</groupId>
      <artifactId>mule-transport-servlet</artifactId>
      <version>${mule.version}</version>
    </dependency>

    <dependency>
      <groupId>org.mule.transports</groupId>
      <artifactId>mule-transport-stdio</artifactId>
      <version>${mule.version}</version>
    </dependency>
  </dependencies>

  <repositories>
    <repository>
      <id>mule-deps</id>
      <name>Mule Dependencies</name>
      <url>http://dist.codehaus.org/mule/dependencies/maven2</url>
    </repository>
  </repositories>
</project>

And then we also add log4j.properties to src/main/java:

log4j.rootLogger=INFO, stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %-5p %x - %m\n

And our web.xml looks like:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  version="3.0">
  <display-name>mule.esb</display-name>

  <context-param>
    <param-name>org.mule.config</param-name>
    <param-value>mule-config.xml</param-value>
  </context-param>

  <listener>
    <listener-class>org.mule.config.builders.MuleXmlBuilderContextListener</listener-class>
  </listener>
</web-app>

All other sources are copied directly from Mule "hello" example (the whole src folder).

Build the application with maven with mvn clean install and deploy the war to Tomcat (or other container).
Then go to http://localhost:8888/?name=Max. You should see the following message:

Hello Max, how are you?

Here we continue working with RESTful webservices. In the last post I showed how to returne an Object in XML with JAXB, and this post will based on it. In this post I will show how to consume an object. The title is rather misleading, but what I meant is "consuming XML and converting it to an object". Again, it is assumed that you followed the setup from the first post in the series. You will find attached sources in the end of the post.

We will have the same Felix Launcher project as in the previous post. To remind you, we will use CXF DOSGi single bundle distribution, because it contains all the necessary dependencies inside its stomach. So here is pom.xml for the "felixLauncher" project (refer to the first post in series):

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dk.sorokin.maksim</groupId>
  <artifactId>felixLauncher</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <name>Felix Launcher</name>

  <properties>
    <felix.bundlerepository.version>1.6.4</felix.bundlerepository.version>
    <felix.gogo.version>0.8.0</felix.gogo.version>
    <felix.framework.version>3.2.2</felix.framework.version>
  </properties>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>2.4.1</version>
        <configuration>
          <filesets>
            <fileset>
              <directory>bundle</directory>
            </fileset>
          </filesets>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.2</version>
        <executions>
          <execution>
            <id>copy</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>org.apache.cxf.dosgi</groupId>
                  <artifactId>cxf-dosgi-ri-singlebundle-distribution</artifactId>
                  <version>1.2</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.apache.felix</groupId>
                  <artifactId>org.apache.felix.gogo.command</artifactId>
                  <version>${felix.gogo.version}</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.apache.felix</groupId>
                  <artifactId>org.apache.felix.gogo.runtime</artifactId>
                  <version>${felix.gogo.version}</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.apache.felix</groupId>
                  <artifactId>org.apache.felix.gogo.shell</artifactId>
                  <version>${felix.gogo.version}</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.osgi</groupId>
                  <artifactId>org.osgi.compendium</artifactId>
                  <version>4.2.0</version>
                </artifactItem>
              </artifactItems>
              <outputDirectory>bundle</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.apache.felix</groupId>
      <artifactId>org.apache.felix.main</artifactId>
      <version>${felix.framework.version}</version>
    </dependency>

    <dependency>
      <groupId>org.ops4j.pax.url</groupId>
      <artifactId>pax-url-assembly</artifactId>
      <version>1.3.3</version>
    </dependency>
  </dependencies>
</project>

Note, that we do the same workaround to downloaded CXF DOSGi single bundle as in previous post by deleting lib\org.apache.servicemix.specs.jaxb-api-2.1-1.3.0.jar jar and adding javax.xml.bind.annotation,javax.xml.bind.annotation.adapters to Import-Package in MANIFEST.MF. It is because there is a JAXB api included in single bundle distribution, which clashes with Java JAXB api (which is embedded in JRE). Otherwise you will see something like:

javax.xml.bind.JAXBException: ClassCastException: attempting to cast bundle://1.0:36/javax/xml/bind/JAXBContext.class to jar:file:/C:/Program%20Files/Java/jdk1.6.0_21/jre/lib/rt.jar!/javax/xml/bind/JAXBContext.class.  Please make sure that you are specifying the proper ClassLoader.

Our test bundle will be called test.bundle, so config.properties file will be something like:

felix.auto.deploy.action=install,start
felix.log.level=1

org.osgi.framework.storage.clean=onFirstInit

felix.auto.start.1 = \
 assembly:/C:/projects/test.bundle/target/classes

Now, let's develop our test.bundle bundle, which would be able to consume XML and automatically transform it into an object. pom.xml file will look the same as in previous post:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dk.sorokin.maksim</groupId>
  <artifactId>test.bundle</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <name>Test Bundle</name>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <executions>
          <execution>
            <id>generate-resources</id>
            <goals>
              <goal>manifest</goal>
            </goals>
            <configuration>
              <instructions>
                <Bundle-Name>${project.name}</Bundle-Name>
                <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                <Bundle-Activator>test.bundle.internal.Activator</Bundle-Activator>
                <Export-Package>test.bundle</Export-Package>
              </instructions>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.3.1</version>
        <configuration>
          <archive>
            <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.apache.felix</groupId>
      <artifactId>org.osgi.core</artifactId>
      <version>1.4.0</version>
    </dependency>

    <dependency>
      <groupId>org.apache.servicemix.specs</groupId>
      <artifactId>org.apache.servicemix.specs.jsr311-api-1.0</artifactId>
      <version>1.8.0</version>
    </dependency>
  </dependencies>
</project>

Now we create a class, an object of which we want to get. It will be test.bundle.MyMessage:

package test.bundle;

import java.io.StringReader;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class MyMessage {

  private int field;

  private String message;

  public MyMessage() {
    // needed for JAXB
  }

  // used when webservice is called with GET method
  public MyMessage(String query) {
    System.out.println(query);
    try {
      JAXBContext context = JAXBContext.newInstance(getClass());
      Unmarshaller unmarshaller = context.createUnmarshaller();
      StringReader sr = new StringReader(query);
      MyMessage request = (MyMessage) unmarshaller.unmarshal(sr);
      field = request.getField();
      message = request.getMessage();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }

  public MyMessage(int field, String message) {
    this.field = field;
    this.message = message;
  }

  @XmlElement
  public int getField() {
    return field;
  }

  // needed for JAXB
  public void setField(int field) {
    this.field = field;
  }

  @XmlElement
  public String getMessage() {
    return message;
  }

  // needed for JAXB
  public void setMessage(String message) {
    this.message = message;
  }
}

Notice MyMessage(String query) constructor. It is being called, when someone contacts a @GET webservice. If you will not have this constructor, you will see the following message, when you will call a webservice expecting to get this class:

Parameter Class test.bundle.MyMessage has no constructor with single String parameter, static valueOf(String) or fromString(String) methods

The interface for the webservice:

package test.bundle;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("myService")
public interface MyService {

  @GET
  @Path("saySomething/{name}")
  @Produces(MediaType.TEXT_PLAIN)
  String saySomething(@PathParam("name") MyMessage message);
}

And implementation for it:

package test.bundle.internal;

import test.bundle.MyMessage;
import test.bundle.MyService;

public class MyServiceImpl implements MyService {

  public String saySomething(MyMessage message) {
    System.out.println(message);
    return "I got this message: " + message.getMessage() + "  and an integer: " + message.getField();
  }
}

Activator for test.bundle:

package test.bundle.internal;

import java.util.Dictionary;
import java.util.Hashtable;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import test.bundle.MyService;

public class Activator implements BundleActivator {

  public void start(BundleContext context) throws Exception {
    Dictionary<String, String> restProps = new Hashtable<String, String>();

    restProps.put("service.exported.interfaces", "*");
    restProps.put("service.exported.configs", "org.apache.cxf.rs");
    restProps.put("service.exported.intents", "HTTP");
    restProps.put("org.apache.cxf.rs.address", "http://localhost:8080/");
    context.registerService(MyService.class.getName(), new MyServiceImpl(), restProps);
  }

  public void stop(BundleContext context) throws Exception {
    //
  }
}

Now run mvn install on test.bundle project and launch "felixLauncher". Then go to http://localhost:8080/myService/saySomething/%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%20standalone%3D%22yes%22%3F%3E%3CmyMessage%3E%3Cfield%3E1%3C%2Ffield%3E%3Cmessage%3EHello%2C%20Max%3C%2Fmessage%3E%3C%2FmyMessage%3E and you should see the following output:

I got this message: Hello, Max  and an integer: 1

Here are the sources

This example is based on a post about simple JAX-RS webservice with CXF. But this post describes a way how to return a more complex object, instead of a String.

First, we create a class in our test.bundle bundle MyMessage in package test.bundle:

package test.bundle;

public class MyMessage {

  private String message;

  public MyMessage(String message) {
    this.message = message;
  }

  public String getMessage() {
    return message;
  }
}

We will return this object in XML format to REST webservice requester. We will use JAXB, which is by default supported in CXF. We annotate the MyMessage:

package test.bundle;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class MyMessage {

  private String message;

  public MyMessage() {
    // needed for JAXB
  }

  public MyMessage(String message) {
    this.message = message;
  }

  @XmlElement
  public String getMessage() {
    return message;
  }

  // needed for JAXB
  public void setMessage(String message) {
    this.message = message;
  }
}

Then we define a web service interface class MyService in test.bundle package:

package test.bundle;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("myService")
public interface MyService {

  @GET
  @Path("sayHello/{name}")
  @Produces(MediaType.TEXT_PLAIN)
  MyMessage sayHello(@PathParam("name") String name);
}

And we define an impelmentation for it in MyServiceImpl class in test.bundle.internal package:

package test.bundle.internal;

import test.bundle.MyMessage;
import test.bundle.MyService;

public class MyServiceImpl implements MyService {

  public MyMessage sayHello(String name) {
    return new MyMessage("Hello " + name);
  }
}

Then we have to do is to register custom message body providers. You can read more on those on CXF website. Create a class MyMessageWriterProvider in package test.bundle.internal:

package test.bundle.internal;

import java.io.IOException;
import java.io.OutputStream;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;

import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.ext.MessageBodyWriter;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;

import test.bundle.MyMessage;

public class MyMessageWriterProvider implements MessageBodyWriter<MyMessage> {

  @Override
  public long getSize(MyMessage message, Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) {
    return 0;
  }

  @Override
  public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) {
    return true;
  }

  @Override
  public void writeTo(MyMessage message, Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType,
      MultivaluedMap<String, Object> headers, OutputStream os) throws IOException, WebApplicationException {
    try {
      JAXBContext context = JAXBContext.newInstance(type);
      Marshaller marshaller = context.createMarshaller();
      marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
      marshaller.marshal(message, os);
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

And the last thing is to register it in the Activator

restProps.put("service.exported.interfaces", "*");
restProps.put("service.exported.configs", "org.apache.cxf.rs");
restProps.put("service.exported.intents", "HTTP");
restProps.put("org.apache.cxf.rs.provider", MyMessageWriterProvider.class.getName());
restProps.put("org.apache.cxf.rs.address", "http://localhost:8080/");
context.registerService(MyService.class.getName(), new MyServiceImpl(), restProps);

Now run mvn clean install on "felixLauncher" and "test.bundle" projects.

The last problem is that DOSGi single bundle distribution contains JAXB api inside. And that clashes with JRE JAXB api (since it is included in JRE). So you may see the following message:

javax.xml.bind.JAXBException: ClassCastException: attempting to cast bundle://1.0:36/javax/xml/bind/JAXBContext.class to jar:file:/C:/Program%20Files/Java/jdk1.6.0_21/jre/lib/rt.jar!/javax/xml/bind/JAXBContext.class.  Please make sure that you are specifying the proper ClassLoader.
	at javax.xml.bind.ContextFinder.handleClassCastException(ContextFinder.java:96)

There are some ways around this problem. But in this case will just modify cxf distributable. Go to bundle folder in "felixLauncher" project. Open cxf-dosgi-ri-singlebundle-distribution-1.2 jar and remove lib/org.apache.servicemix.specs.jaxb-api-2.1-1.3.0.jar jar. Then modify META-INF/MANIFEST.MF inside cxf single bundle distribution and add "javax.xml.bind.annotation,javax.xml.bind.annotation.adapters" to Import-Package section.

Run "Felix Launcher" (refer to the first post).

Go to http://localhost:8080/myService/sayHello/Max. You should see the following output:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<myMessage>
    <message>Hello Max</message>
</myMessage>

Here are the zipped sources.

This is example is based on the sample application developed in previous post. Again, it is assumed here that you are using M2Eclipse plugin, if you want to run examples from Eclipse.

As usual, source is included in the end of the post.

First of, we need to download CXF DOSGi dependency in "felixLauncher" (refer to previous post) and put it to the "bundle" folder, so Apache Felix would know about CXF. Why CXF DOSGi? Because it contains all necessary dependencies inside. We will use single-bundle distribution in this case. So in artifactItems in maven-dependency-plugin (refer to previous post), define:

<artifactItem>
  <groupId>org.apache.cxf.dosgi</groupId>
  <artifactId>cxf-dosgi-ri-singlebundle-distribution</artifactId>
  <version>1.2</version>
</artifactItem>

Now we need to create a webservice code in our bundle. But first, we need to tell maven where to find JAX-RS annotations, so add this to the dependencies of test.bundle project:

<dependency>
  <groupId>org.apache.servicemix.specs</groupId>
  <artifactId>org.apache.servicemix.specs.jsr311-api-1.0</artifactId>
  <version>1.8.0</version>
</dependency>

Now create an interface MyService in test.bundle package in the test.bundle project:

package test.bundle;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("myService")
public interface MyService {

  @GET
  @Path("sayHello/{name}")
  @Produces(MediaType.TEXT_PLAIN)
  String sayHello(@PathParam("name") String name);
}

And implementation class MyServiceImpl in package test.bundle.internal:

package test.bundle.internal;

import test.bundle.MyService;

public class MyServiceImpl implements MyService {

  public String sayHello(String name) {
    return "Hello " + name;
  }
}

Actually, interface for a webservice may be even separated to a different bundle to enforce decoupling. But in this case we will just keep them together. But you may want to explicitly state, that test.bundle.internal is internal package and cannot be visible to outside. This can be done by explicitly exporting only visible packages through Export-Package in the manifest file. Since we are using Maven bundle plugin, we can also define Export-Package in manifest file generation part in pom.xml:

  <plugin>
	<groupId>org.apache.felix</groupId>
	<artifactId>maven-bundle-plugin</artifactId>
	<executions>
	  <execution>
		<id>generate-resources</id>
		<goals>
		  <goal>manifest</goal>
		</goals>
		<configuration>
		  <instructions>
			<Bundle-Name>${project.name}</Bundle-Name>
			<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
			<Bundle-Activator>test.bundle.internal.Activator</Bundle-Activator>
			<Export-Package>test.bundle</Export-Package>
		  </instructions>
		</configuration>
	  </execution>
	</executions>
  </plugin>

And also, do not worry about JAX-RS package imports in the manifest file -- they will be automatically generated by maven-bundle-plugin.

And the last changes we have to do -- is to register a webservice. This is done through the Activator. So modify Activator of test.bundle, so it would look like:

package test.bundle.internal;

import java.util.Dictionary;
import java.util.Hashtable;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import test.bundle.MyService;

public class Activator implements BundleActivator {

  public void start(BundleContext context) throws Exception {
    Dictionary<String, String> restProps = new Hashtable<String, String>();

    restProps.put("service.exported.interfaces", "*");
    restProps.put("service.exported.configs", "org.apache.cxf.rs");
    restProps.put("service.exported.intents", "HTTP");
    restProps.put("org.apache.cxf.rs.address", "http://localhost:8080/");
    context.registerService(MyService.class.getName(), new MyServiceImpl(), restProps);
  }

  public void stop(BundleContext context) throws Exception {
    //
  }
}

Then run mvn clean install on "felixLauncher" and "test.bundle" projects. Afterwards, launch "felixLauncher" (refer to the first post in series).

Then you can query the REST webservice throught a browser:

http://localhost:8080/myService/sayHello/Max

And should see the following response:

Hello Max

Here are the zipped sources.

The answer is simple -- use the power of Maven. If you have really big projects, try to split them into different parents and modules. It is import during this splitting part to preserve some sort of naming convention. For example, each child preserves parent name as a prefix. In this case it is easier to identify and operate the projects. The structure may look like this, assuming that there is a generator project:

-- generator
 |-- generator.parser
   |-- generator.parser.full
     |-- generator.parser.full.noboms
     |-- generator.parser.full.universal
   |-- generator.parser.simple
   |-- generator.parser.utils
 |-- generator.security
   |-- generator.security.basic
   |-- generator.security.ldap
 |-- generator.utility

Also, do not forget that you can exploit pluginManagement and dependencyManagement in Maven. Using it you can predefine build process routine in your parent (typically the top one) and not care about it in your parents. Example would be something like:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dk.sorokin.maksim</groupId>
  <artifactId>generator</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <name>Generator Parent</name>

  <modules>
    <module>generator.parser</module>
    <module>generator.security</module>
    <module>generator.utility</module>
  </modules>

  <properties>
    <org.apache.felix.framework.version>3.2.2</org.apache.felix.framework.version>
    <org.apache.servicemix.specs.jsr311-api-1.0>1.8.0</org.apache.servicemix.specs.jsr311-api-1.0>
    <org.osgi.core.version>1.4.0</org.osgi.core.version>
  </properties>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.3.2</version>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.3.1</version>
        <configuration>
          <archive>
            <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
          </archive>
        </configuration>
      </plugin>
    </plugins>

    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.felix</groupId>
          <artifactId>maven-bundle-plugin</artifactId>
          <version>2.3.5</version>
          <executions>
            <execution>
              <id>generate-resources</id>
              <goals>
                <goal>manifest</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.8.2</version>
        <scope>test</scope>
      </dependency>

      <dependency>
        <groupId>org.apache.felix</groupId>
        <artifactId>org.apache.felix.framework</artifactId>
        <version>${org.apache.felix.framework.version}</version>
      </dependency>

      <dependency>
        <groupId>org.apache.servicemix.specs</groupId>
        <artifactId>org.apache.servicemix.specs.jsr311-api-1.0</artifactId>
        <version>${org.apache.servicemix.specs.jsr311-api-1.0}</version>
      </dependency>

      <dependency>
        <groupId>org.apache.felix</groupId>
        <artifactId>org.osgi.core</artifactId>
        <version>${org.osgi.core.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

Also, carefully maintain Felix config.properties file. Especially, if you share it with several developers. In order not to have hardcoded path in it, you may use Maven Filtering to filtering it. Instead of paths, you have variables, which are stored in Maven Settings.

Finally, always make sure, that the whole project and Felix launcher (if you use it) can be checked, built and run immediately on the fresh machine.

The problem:

• Integrating Felix with Eclipse tutorial requires manual download and configuration of Felix distributable into workspace
• Felix allows deploying only jar bundles, which is inappropriate for easy development and debugging

We can use the power of Maven and these two resources to solve both problems.

The idea about the first one is to use Maven dependency management mechanism to download Felix dependencies and put them to required locations.The idea about the second one is to use OPS4J Pax URL to load a bundle from a folder (not a jar).

We will have two projects -- one solely for launching Felix environment and another one for a test bundle.

We start with Felix launcher felixLauncher project. We create a Maven project (if you have M2Eclipse installed, that is easier) in Eclipse. First warning is that packaging type should be "jar", not "pom" (the reason will be explained later).

To understand what is happening and what Felix framework requires, you may take a look into Felix Framework Distribution. you will see that there is a "bundle" folder which contains several jars. Also there is a "conf" folder which has "config.properties" inside it. So we will do the same for our felixLauncher project. We will dump those jars (gogo) into "bundle" folder. Also, we dump "osgi compendium" jar into "bundle" folder, because it will be needed for our projects. Since "bundle" folder is populated automatically, we also would like to clean it on the "clean" goal. Therefore, we tell Maven Clean Plugin to remove "bundle" folder.
Lastly, we specify Felix Distribution Framework as our dependency, because we want to launch Felix Framework directly from Eclipse. Since we want to use OPS4J Pax URL to launch our projects from folders, not from jars, we have to depend on that project as well to make it available for Eclipse.
So here is pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dk.sorokin.maksim</groupId>
  <artifactId>felixLauncher</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <name>Felix Launcher</name>

  <properties>
    <felix.bundlerepository.version>1.6.4</felix.bundlerepository.version>
    <felix.gogo.version>0.8.0</felix.gogo.version>
    <felix.framework.version>3.2.2</felix.framework.version>
  </properties>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>2.4.1</version>
        <configuration>
          <filesets>
            <fileset>
              <directory>bundle</directory>
            </fileset>
          </filesets>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.2</version>
        <executions>
          <execution>
            <id>copy</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>org.apache.felix</groupId>
                  <artifactId>org.apache.felix.gogo.command</artifactId>
                  <version>${felix.gogo.version}</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.apache.felix</groupId>
                  <artifactId>org.apache.felix.gogo.runtime</artifactId>
                  <version>${felix.gogo.version}</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.apache.felix</groupId>
                  <artifactId>org.apache.felix.gogo.shell</artifactId>
                  <version>${felix.gogo.version}</version>
                </artifactItem>
                <artifactItem>
                  <groupId>org.osgi</groupId>
                  <artifactId>org.osgi.compendium</artifactId>
                  <version>4.2.0</version>
                </artifactItem>
              </artifactItems>
              <outputDirectory>bundle</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.apache.felix</groupId>
      <artifactId>org.apache.felix.main</artifactId>
      <version>${felix.framework.version}</version>
    </dependency>

    <dependency>
      <groupId>org.ops4j.pax.url</groupId>
      <artifactId>pax-url-assembly</artifactId>
      <version>1.3.3</version>
    </dependency>
  </dependencies>
</project>

Next, we need to create a config.properties file, because it is mandatory for Felix. There is a way to have own location for it, but to make things simpler, we will create it in the location, where Felix expects it by default. In the "felixLauncher" project create conf folder. Then create a file config.properties with the following content:

felix.auto.deploy.action=install,start
felix.log.level=1

org.osgi.framework.storage.clean=onFirstInit

You can read about options available on Apache Felix website.

Now we have to create an Eclipse launcher. In Eclipse go to "Run - Run Configurations...". In the left menu right-click on "Java Application" and click "New". In "Name" specify "Felix Launcher". In "Project" specify "felixLauncher" (if you do not see this project, that means the project is not understood by Eclipse as "Java" project. So it is important that it has "jar" packaging type). Then click on "Search..." in the "Main class" field. Search for "org.apache.felix.main.Main". Click "OK". Lastly, switch to "Arguments" tab and in "VM arguments" specify "-Djava.protocol.handler.pkgs=org.ops4j.pax.url". Click "Apply" and "Run". You will see something like:

____________________________
Welcome to Apache Felix Gogo

g!

Now Apache Felix can be launched correctly.

Next, let's create some test project. Create a Maven project "test.bundle". Create a package test.bundle.internal in src/main/java. And create "Activator.java" class there with the following content (do not worry about compilation problems for now):

package test.bundle.internal;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {

  public void start(BundleContext arg0) throws Exception {
    System.out.println("Hello");
  }

  public void stop(BundleContext arg0) throws Exception {
    System.out.println("Bye");
  }
}

Now, the pom.xml file for the project. As you know, OSGi bundles need to have manifest files. But instead of writing them by hand, we can generate them. There is an excellent Apache Felix Maven Bundle Plugin, which we will use. We will tell Maven Jar Plugin to take that generated MANIFEST.MF file. So pom.xml will look like:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dk.sorokin.maksim</groupId>
  <artifactId>test.bundle</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <name>Test Bundle</name>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <executions>
          <execution>
            <id>generate-resources</id>
            <goals>
              <goal>manifest</goal>
            </goals>

            <configuration>
              <instructions>
                <Bundle-Name>${project.name}</Bundle-Name>
                <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                <Bundle-Activator>test.bundle.internal.Activator</Bundle-Activator>
              </instructions>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.3.1</version>
        <configuration>
          <archive>
            <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.apache.felix</groupId>
      <artifactId>org.osgi.core</artifactId>
      <version>1.4.0</version>
    </dependency>
  </dependencies>
</project>

Then you can simply run mvn clean install on the project. Actually, Eclipse will do that for you. But you need to run install goal in order to have correct MANIFEST.MF file generated.

Last thing which is left to do is to inform Apache Felix about the project. Modify config.properties and add the following:

felix.auto.start.1 = \
 assembly:/C:/projects/test.bundle/target/classes

Path to the project may be different on your machine. You should see "Hello" message in the output.

Here is the zipped version of these two projects: zip file