Amdatu

On a first quick view the Amdatu project seems to be a feature rich OSGi based server. But it is not (a server). By itself the Amdatu project is no server but delivers components and services which can also be found in Java EE application servers, like JAX-RS support. The Amdatu project provides a set of bundles which contains these components and services.

So to start exploring Amdatu first an OSGi container needs to be installed. Apache Felix seems well supported and tested from the Amdatu team.

Install Felix

Felix can be installed by downloading the main distribution file, extracting the content and running java -jar bin/felix from inside the felix directory.

A much more elaborate installation guide can be found at the Apache Felix web site.

Install Amdatu Bundles

Amdatu delivers OBRs for release and snapshot versions of their bundles. These can be found at the download page.

The easiest way to install the Amdatu bundles is to add the OBRs to the used bundle repositories of the felix installation. The repositories can be added in the config.properties file found in the conf folder of the felix installation.

obr.repository.url=http://felix.apache.org/obr/releases.xml http://repository.amdatu.org/dependencies/repository.xml http://repository.amdatu.org/release/repository.xml
Note that the repository urls are separated by a blank and not by a comma.

Now the Amdatu bundles can be installed via the deploy command. The big advantage by using this method is that all dependencies will also automatically be installed (if they are also in one of the registered repositories).

The Amdatu documentation is not up-to-date concerning the nameing of the bundles. F. e. some JAX-RS related bundles have now rest added to their bundle name, f. e. org.amdatu.web.wink ⇒ org.amdatu.web.rest.wink

Install Felix Bundles

Most of the bundles of the Apache Felix project are also available by their OBR which is preconfigured in the config.properties file.

The Apache Felix Webconsole in a version >= 4.0.0 needs the org.json package. This is not provided by the Apache Felix project. It can be installed from the SpringSource repository, see Install 3rd Party Bundles.
The component tab of the webconsole has moved from the main bundle to a separate bundle which is not registered in the Apache Felix OBR. See the download page of the separate bundles and look for Web Console DS Plugin.

Install 3rd Party Bundles

Some projects have already bundleized their jars and can be used directly by dropping them in the load folder, see Apache Felix File Install.

There is also the Enterprise Bundle Repository from SpringSource at http://ebr.springsource.com. There are many projects with OSGi headers available, f. e. json.org.

Installed Bundles

g! lb -s
START LEVEL 1
   ID|State      |Level|Symbolic name
    0|Active     |    0|org.apache.felix.framework (4.2.1)
    1|Active     |    1|com.springsource.org.apache.commons.codec (1.6.0)
    2|Active     |    1|com.springsource.org.apache.commons.collections (3.2.1)
    3|Active     |    1|com.springsource.org.apache.commons.io (1.4.0)
    4|Active     |    1|org.apache.felix.bundlerepository (1.6.6)
    5|Active     |    1|org.apache.felix.configadmin (1.6.0)
    6|Active     |    1|org.apache.felix.eventadmin (1.3.2)
    7|Active     |    1|org.apache.felix.fileinstall (3.2.6)
    8|Active     |    1|org.apache.felix.gogo.command (0.12.0)
    9|Active     |    1|org.apache.felix.gogo.runtime (0.10.0)
   10|Active     |    1|org.apache.felix.gogo.shell (0.10.0)
   11|Active     |    1|org.apache.felix.log (1.0.1)
   12|Active     |    1|org.apache.felix.metatype (1.0.6)
   13|Active     |    1|org.apache.felix.prefs (1.0.4)
   14|Active     |    1|org.kxml2 (2.3.0)
   15|Active     |    1|org.apache.felix.scr (1.6.0)
   16|Active     |    1|org.apache.felix.shell (1.4.0)
   17|Active     |    1|org.amdatu.web.rest.jaxrs (1.0.4)
   18|Active     |    1|org.apache.felix.http.bundle (2.0.4)
   19|Active     |    1|jackson-mapper-asl (1.9.8)
   20|Active     |    1|jackson-core-asl (1.9.8)
   21|Active     |    1|org.apache.felix.dependencymanager (3.0.0)
   22|Active     |    1|jackson-jaxrs (1.9.8)
   23|Active     |    1|org.amdatu.web.rest.wink (1.0.8)
   24|Active     |    1|org.amdatu.web.rest.doc (1.1.1)
   25|Active     |    1|org.amdatu.web.rest.doc.swagger (1.0.4)
   26|Active     |    1|org.amdatu.web.rest.doc.swagger.ui (1.0.3)
   27|Active     |    1|org.amdatu.web.resourcehandler (1.0.4)
   31|Active     |    1|org.apache.felix.http.jetty (2.2.2)
   32|Active     |    1|org.apache.felix.http.whiteboard (2.2.2)
   33|Active     |    1|com.springsource.org.json (1.0.0)
   34|Active     |    1|org.apache.felix.webconsole (4.0.0)
   35|Active     |    1|org.apache.commons.fileupload (1.2.2)
   37|Active     |    1|org.apache.felix.webconsole.plugins.ds (1.0.0)
   38|Active     |    1|org.apache.felix.webconsole.plugins.event (1.1.0)

Create REST Service

The Amdatu project has a good documentation about creating a REST service.

@Path("test")
public class TestResource {

    @GET
    @Path("ping")
    public Response ping() {
        return Response.ok("ping (" + System.currentTimeMillis() + ")").build();
    }
}

The REST service needs to be registered as an OSGi component. This can be done in various ways. One way is to use declarative services.

Create a folder OSGI-INF in the REST service project. Add a component definition file to it (Eclipse has an editor and a wizard for that.).

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="test.amdatu.rs.ping">
	<implementation class="test.amdatu.rs.TestResource" />
 <service>
    <provide interface="java.lang.Object"/>
 </service>
</scr:component>

Don't forget to add an interface to the component definition even if it is only java.lang.Object (it doesn't has to be java.lang.Object) or else the component won't be picked up by the Amdatu project as a REST service.

Add the component definition to the manifest (MANIFEST.MF):

Service-Component: OSGI-INF/rest-test.xml

The service will be listed in the webconsole in the HTTP Service and HTTP Whiteboard tab.

Maven

As there is no maven artifact for the Amdatu bundles yet these bundles must be imported manually into the maven repository if maven is used for dependency management.

mvn install:install-file -D file=/path/to/org.amdatu.web.rest.jaxrs-1.0.4.jar -DgroupId=org.amdatu -DartifactId=web.rest.jaxrs -Dversion=1.0.4 -Dpackaging=jar

<dependency>
  <groupId>org.amdatu</groupId>
  <artifactId>web.rest.jaxrs</artifactId>
  <version>1.0.4</version>
  <scope>provided</scope>
</dependency>

REST Documentation

Another real gem of the Amdatu project is the REST documentation. Take a look at http://localhost:8080/ui/index.html for a really nice documentation of the installed REST services.

See Self documenting REST endpoints with Swagger at http://amdatu.org/components/web.html and Swagger.