Differences

This shows you the differences between two versions of the page.

Link to this comparison view

amdatu [2014/02/20 13:42]
amdatu [2021/04/05 11:23] (current)
Line 1: Line 1:
 +====== 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 [[https://felix.apache.org/documentation/subprojects/apache-felix-framework/apache-felix-framework-usage-documentation.html | Apache Felix]] web site.
 +
 +===== Install Amdatu Bundles =====
 +Amdatu delivers OBRs for release and snapshot versions of their bundles. These can be found at the [[http://repository.amdatu.org/ | 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 important>Note that the repository urls are separated by a blank and not by a comma.</note>
 +
 +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).
 +
 +<note important>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 </note>
 +
 +===== 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.
 +
 +<note>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]].</note>
 +
 +<note>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''.</note>
 +
 +===== 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. [[http://ebr.springsource.com/repository/app/bundle/version/detail?name=com.springsource.org.json&version=1.0.0 | json.org]].
 +
 +===== Installed Bundles =====
 +<code>
 +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)
 +</code>
 +
 +===== Create REST Service =====
 +The Amdatu project has a good [[http://amdatu.org/components/web.html | documentation]] about creating a REST service. 
 +
 +<sxh java>
 +@Path("test")
 +public class TestResource {
 +
 +    @GET
 +    @Path("ping")
 +    public Response ping() {
 +        return Response.ok("ping (" + System.currentTimeMillis() + ")").build();
 +    }
 +}
 +</sxh>
 +
 +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.).
 +
 +<sxh xml>
 +<?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>
 +</sxh>
 +
 +<note>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.</note>
 +
 +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
 +
 +<sxh xml>
 +<dependency>
 +  <groupId>org.amdatu</groupId>
 +  <artifactId>web.rest.jaxrs</artifactId>
 +  <version>1.0.4</version>
 +  <scope>provided</scope>
 +</dependency>
 +</sxh>
 +
 +===== 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 [[https://helloreverb.com/developers/swagger | Swagger]].
 +
 +{{tag>osgi}}