APAM hello world components

In this lesson, you will manipulate basic apam components. We will create a simple Hello World Service with ApAM components, then we will use it

Overview

The goal of this section is to create basic components (without composite) which provide the "Hello World" service. This service receives an input string and displays "Hello, ..." message into the standard output console.

Hello World Service

A service in ApAM is realized through a three level component model: specification, implementation and instance (for more details see the APAM overview. In this section, we will implements the Hello World service using our three level component model.

Specification

The specification is the description the service. It contains the description of resources to be provided, like interfaces. the java interface corresponding to the Hello World service is as follow:

package fr.imag.adele.apam.hello.world.spec;

public interface HelloService {
    /**
     * Method printing text into the output console with "Hello, " prefix
     * @param texte the string received, 
     */
    public void sayHello(String texte);
}

Each Specification APAM must be described using the APAM DSL language. This description provide information about the resources provided and required, the specification component can be customized using definitions and properties.

<specification name="Hello-Spec" 
   interfaces="fr.imag.adele.apam.hello.world.spec.HelloService">
</specification>

Implementation

The implementation component is in charge to provide an the code implementation of the service. The Java class implementation corresponding to this implementation is as follows:

package fr.imag.adele.apam.hello.world.impl;

public class HelloImplementation implements HelloService{

    /**
     * @see HelloService#sayHello(String) 
     */
    @Override
    public void sayHello(String texte) {
        System.out.println("Hello, " + texte);
    }

    //Called by APAM when an instance of this implementation is created
    public void start(){
        System.out.println("HelloService Start");
    }
    
    // Called by APAM when an instance of this implementation is removed
    public void stop(){
        System.out.println("HelloService Stop");
    }
}

As Specification component, each implementation in APAM must be described using the APAM DSL language. This description provide information about the class implementing this component, the service provided or required.

This description is realized as follows:

<implementation name="Hello-Impl" 
      specification="Hello-Spec"      
      classname="fr.imag.adele.apam.hello.world.impl.HelloImplementation">
   <callback onInit="start" onRemove="stop"/>
</implementation>

In the description we can set callback methods to be called on instance creation and/or destruction. In our example, the method "start()" will be call at instance creation and the method "stop()" at the instance destruction.

Instance Description

APAM allows the creation of instances using a description. in our example, to create the instance of Hello-Impl the description is realized as follows:

<apam-instance name="Hello-Inst" 
   implementation="Hello-Impl">
</apam-instance>

Build (Compilation and Packaging)

For build process we use Maven as presented in the previous lesson. To launch the build of this project the command "mvn clean install" must be executed in an OS console or using a maven eclipse plugin.

mvn clean install

If the build process ends successfully the bundle "hello-world-1.0.0-SNAPSHOT.jar"; must be in the target directory of the project.

Using the Hello World Service

Next step is to create a client for our service. "TextGui" is a very simple user interface, a TextField area to input some text and a button. When the button is pressed, the Hello World Service display the text on the console.

TextGui

package fr.imag.adele.apam.text.gui.impl;

import fr.imag.adele.apam.hello.world.spec.HelloService;

public class TextGuiImplementation implements java.awt.event.ActionListener {

    private javax.swing.JFrame         frame;
    private javax.swing.JTextField     textField;
    private javax.swing.JButton        callBtn;
    private String name ="APAM Hello Service Client";
    
    private HelloService helloServiceProvider;

    public void started() {
        frame = new javax.swing.JFrame(name);
        initComponents();
        frame.setVisible(true);
    }

    public void stopped() {
        if (frame != null) {
            frame.dispose();
            frame = null;
        }
    }

    private void initComponents() {
        frame.setSize(400, 70);
        textField = new javax.swing.JTextField();
        callBtn = new javax.swing.JButton("Call Service");
        callBtn.addActionListener(this);
        frame.setLayout(new java.awt.BorderLayout());
        frame.add(textField, java.awt.BorderLayout.CENTER);
        frame.add(callBtn, java.awt.BorderLayout.EAST);
    }
    
    public void actionPerformed(java.awt.event.ActionEvent e) {
        String msg = textField.getText();
       	helloServiceProvider.sayHello(msg);
        textField.setText("");
    }
}

Pay attention to the private member of the class :

private HelloService helloServiceProvider;

This one is used only when button is pressed :

helloServiceProvider.sayHello(msg);

Resolution is a process by which a client (an instance) finds the service provider (another instance) it requires. A resolution is launched only when the client use a variable of the provider type (in our case when the button is pressed). The dependency management and resolution strategies is described accordingly to the ApAM Component descriptor (metadata.xml) :

<implementation name="text-gui"
  classname="fr.imag.adele.apam.text.gui.impl.TextGuiImplementation">
	<callback onInit="started" onRemove="stopped"/>
 	<dependency specification="Hello-Spec" field="helloServiceProvider" fail="exception" exception="java.lang.Exception"/>
</implementation>

We also need to create an instance of this client to be automatically started in the platform. This is done in the same way as our service by the descriptor.

<apam-instance name="my-text-gui-instance" implementation="text-gui"/>

Build (Compilation and Packaging)

The maven descriptor file (pom.xml) is nearly the same except for the artifact id and the compilation dependency with the Hello World Service interface :

  <artifactId>TextGui</artifactId>

[...]

  <dependencies>
    <dependency>
      <groupId>fr.imag.adele.apam</groupId>
      <artifactId>hello-world</artifactId>
      <version>1.0.0-SNAPSHOT</version>
    </dependency>
  </dependencies>

Build process is the same as Hello World Service If the build process ends successfully the bundle "TextGui-1.0.0-SNAPSHOT.jar" must be in the target directory of the project.

Run using your compiled project

• First Download APAM-Runtime
• Run the Felix platform with the preinstalled APAM Bundles

java -jar bin/felix.jar

• Inside the Felix Shell start the Hello Service and the Text Gui :

start file://<path to Hello Service target directory>/hello-world-1.0.0-SNAPSHOT.jar
start file://<path to Text Gui target directory>/TextGui-1.0.0-SNAPSHOT.jar

• Before using the APAM Hello Service Client GUI, you can check that bundles are successfully started with Felix Shell lb command.
• You can also check that the two instances were successfully created using insts APAM Shell command.

Note: if you check the instances created AFTER using the button (and therefore after the dynamic resolution of dependencies), you will see a new instance named text-gui_Appli-1. It is normal behavior as this is a default composite component (see next lesson for details).

Example Resources

List of compiled artefacts

• Hello World All in one Bundle
• Text Gui Bundle