Skip to content

Hello World part I

Jump to bottom Edit New page
Thibaud Flury edited this page Aug 20, 2013 · 2 revisions
Tutorial Level Goals Prerequisites
Beginners
  • Create a Project
  • Implements a simple POJO Class
  • Discover the ApAM Descriptor
  • Describe an ApAM Implementation
  • Use Callbacks
  • Run using ApAM Commands

In this tutorial, you will learn to create and run a very simple ApAM Component.
Now available with the new ApAM in 5 minutes video tutorial !.

Table of Contents

Step 1. Create a Maven Project

Firstly, you create a regular maven project as usual, with the basic project descriptor (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>fr.imag.adele.apam.tutorials.helloworld</groupId>
  <artifactId>HelloWorld-ApAM</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <description>A very Simple Hello World Implementation with ApAM</description>
<project>
Drawing from this, you will need to create an OSGi bundle and transform this in an ApAM component.

Creating an OSGi bundle

It is very simple thanks to Apache Felix maven bundle plugin. You need to change the packaging of you artifact : 

<project>
  ...
  <packaging>bundle</packaging>
  ...
<project>
And you also need to add the corresponding plugin from Apache : 
<project>
  ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.3.7</version>
                <extensions>true</extensions>
            </plugin>
        </plugins>
    </build>  

  ...
<project>

Creating the ApAM component

This is also a matter of plugin. As ApAM is evolving rapidly, let's add a custom property indicating the current version (please change to the latest stable) : 

<project>
  ...
  <properties>
    <apam-version>0.0.3</apam-version>
  </properties>
  ...
<project>
When can now add the apam-maven-plugin : 
<project>
  ...
    <build>
        <plugins>
           ...
            <plugin>
                <groupId>fr.imag.adele.apam</groupId>
                <artifactId>apam-maven-plugin</artifactId>
                <version>${apam-version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>apam-bundle</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>  

  ...
<project>

We need to get this particular plugin from ApAM repository : 

<project>
  ...
    <pluginRepositories>
        <pluginRepository>
            <id>apam-plugin-repository</id>
            <url>https://repository-apam.forge.cloudbees.com/release/repository/</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>
  ...
<project>

Putting it all together 

<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>fr.imag.adele.apam.tutorials.helloworld</groupId>
  <artifactId>HelloWorld-ApAM</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <description>A very Simple Hello World Implementation with ApAM</description>

  <packaging>bundle</packaging>

  
<!-- Check Latest ApAM Version -->
  <properties>
    <apam-version>0.0.4-SNAPSHOT</apam-version>
  </properties>
  
<!-- Repositories List -->
    <pluginRepositories>
        <pluginRepository>
            <id>apam-plugin-repository</id>
            <url>https://repository-apam.forge.cloudbees.com/release/repository/</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>
  
  
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.3.7</version>
                <extensions>true</extensions>
            </plugin>
            <plugin>
                <groupId>fr.imag.adele.apam</groupId>
                <artifactId>apam-maven-plugin</artifactId>
                <version>${apam-version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>apam-bundle</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>  
   
</project>

Step 2. Implements a simple POJO Class

Nothing particular with this. No ApAM dependencies or libraries. Create a class in the src/main/java directory : 

package fr.imag.adele.apam.tutorials.helloworld;

/**
 * A simple POJO implementation of Hello World with ApAM and a callback function
 *
 */
public class HelloWorldApAM {
    
    public void sayHello() {
	System.out.println("Hello World, from an ApAM component !");
    }

}
Before going further, please note :
  • The package for our component main class : fr.imag.adele.apam.tutorials.helloworld
  • The name of our component main class : HelloWorldApAM
  • The name of the function that we want to be called when our component start : public void sayHello()
We will use these elements to describe the ApAM component.

Step 3. The ApAM Descriptor

The ApAM descriptor is an XML file named metadata.xml in src/main/resources. Our first component is a java class from which we can create objects, it will the be an ApAM Implementation (from which we will create ApAM Instances). We give the name HelloWorld-ApAM to our component and we indicate the corresponding java class fr.imag.adele.apam.tutorials.helloworld.HelloWorldApAM created previously. 

<apam xmlns="fr.imag.adele.apam" xmlns:ipojo="org.apache.felix.ipojo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="fr.imag.adele.apam http://repository-apam.forge.cloudbees.com/release/schema/ApamCore.xsd" >    

    <implementation name="HelloWorld-ApAM"
        classname="fr.imag.adele.apam.tutorials.helloworld.HelloWorldApAM">
    </implementation>

</apam>
We also want a particular behavior for this component. When we create and start an instance we want to call the method sayHello(). This is done using a callback : 
      <callback onInit="sayHello"/>

Putting it all together 

<apam xmlns="fr.imag.adele.apam" xmlns:ipojo="org.apache.felix.ipojo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="fr.imag.adele.apam http://repository-apam.forge.cloudbees.com/release/schema/ApamCore.xsd" >    

    <implementation name="HelloWorld-ApAM"
        classname="fr.imag.adele.apam.tutorials.helloworld.HelloWorldApAM">
        <callback onInit="sayHello"/>
    </implementation>

</apam>

Step 4. Compile and install the source

To compile and install our component, simply use : mvn clean install The build goes through several steps : resolve dependencies -> compile -> test -> OSGi bundle packaging -> ApAM static checks (according to metadata.xml) -> Description of ApAM capabilities of the component through obr.xml file -> deployment in the local maven repository.

Check the result : 

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
Otherwise you should check the Requirements for ApAM.

Step 5. Run using ApAM Commands

According to the download of the prepackaged ApAM distribution, open a terminal at the root directory : apam-basic-distribution-VERSION. and launch : java -jar bin/felix.jar

You can check the OSGi Bundle already installed and running, just type lb in the console. It contains several utilities and the ApAM core bundles. All these bundles should be in Active state before going further. Notice that our HelloWorld-ApAM bundle isn't installed nor stated yet.

You can also check all the running ApAM Instance components, just type inst. All the core ApAM Manager are already started. OBRMAN-Instance resolves dependencies using OSGi bundle repository. By default, it uses the local maven repository.

As we have seen previously, our HelloWorld-ApAM bundle has been deployed in the local maven repository. We can try to create an instance from our implementation. Just type l HelloWorld-ApAM. (1)It will resolve using the implementation name described in the local repository, (2)install and start the bundle on the platform, (3)create the ApAM instance and (4)call the sayHello method as a callback.

Congratulation, your first ApAM component is up and running !!!

Home | About | Getting started | Tutorials | Technical Documentation | Contact us

Add a custom sidebar

Clone this wiki locally