This sample app illustrates some basic OGEMA concepts, such as the start and stop methods, the resource database, and timers. The full source code is available from Github, see link at the end of the page.

Note that this app demonstrates a minmal executable OGEMA application. This app is not compatble with extended SDK functions and should thus not be used as template for any other development.

Create the project

First create a new app:

  • in the upper menu select File -> New -> Project... -> Ogema -> App.
  • the "New OGEMA App Project" dialog appears. Enter the data as in the screenshot, in particular make sure to select Project type: App without GUI. Click Finished.

wizard2.png

  • The new project will be created in your workspace. It can be found as "hello-ogema" in the project explorer. After expanding the "src/main/java" folder, it will look something like this:
    helloOgemaProjectBlownUp.png
  • Delete the lower package ("org.smartrplace.external.helloogema.config"), and the "HelloOgemaController.java" file - we don't need them for this app. Note that the class ending on Controller is required for several SDK functionalities and should thus not be deleted for any app developed by you.
  • Open the remaining Java file "HelloOgemaApp" - it should show some error warnings, because it still references the deleted fie. Remove all lines that reference the controller and the urlPath, then the source code should looks as follows:
package org.smartrplace.external.helloogema;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
import org.ogema.core.application.Application;
import org.ogema.core.application.ApplicationManager;
import org.ogema.core.logging.OgemaLogger;

/**
 * Template OGEMA application class
 */

@Component(specVersion = "1.2", immediate = true)
@Service(Application.class)
public class HelloOgemaApp implements Application {

   private OgemaLogger log;
   private ApplicationManager appMan;

   /*
     * This is the entry point to the application.
     */

   @Override
   public void start(ApplicationManager appManager) {

       // Remember framework references for later.
       appMan = appManager;
        log = appManager.getLogger();
    }

    /*
     * Callback called when the application is going to be stopped.
     */

   @Override
   public void stop(AppStopReason reason) {
        log.info("{} stopped", getClass().getName());
        appMan = null;
        log = null;
   }
}

Possibly Eclipse still shows errors at this point. If a "Building Workspace" or "Build" status is visible, wait until this is done, then press Alt+F5 to refresh the project's Maven dependencies. This should remove the warnings. For more details see Create a new Project and Run it

Create a Resource

OGEMA comes equipped with a database, whose entries are stored persistently, which means that they will be reloaded upon restart of the system. In general, Resources are accessible to all applications, although applications need to demand permissions in order to read, write, create or delete Resources, and these permissions can be granted or denied in a fine-granular way. For the time being we ignore the permissions, since this is somewhat complex subject, and in our development system we will simply disable security.
We can access the database using the ApplicationManager that is passed over in the start method. In order to create a new top level Resource, we actually need the ResourceManager - it is obtained from the ApplicationManager through the #getResourceManagement() method. It allows us to create a Resource by specifying its type and its name, as follows (add this to the start method):

final StringResource helloResource = appManager.getResourceManagement().createResource("helloOGEMA", StringResource.class);

Here we create a StringResource, which is a value-bearing resource type, in this case a value of type String. Let us set the value:

 helloResource.setValue("Hello OGEMA!");

Then we should activate it, in order to signal other applications that the Resource now contains a valid value:

helloResource.activate(false);

Create a Timer

Now let's add a Timer, in order to periodically print the content of the resource to the console.


Timer responseTimer = appMan.createTimer(10000, new TimerListener() {
  
@Override
public void timerElapsed(Timer timer) {
 // print the content of helloResource to the console
 System.out.println("Timer elapsed at " + StringFormatHelper.getFullTimeDateInLocalTimeZone(appMan.getFrameworkTime())
                       + "; message: " + helloResource.getValue());
}

});

Add missing imports

Eclipse should display a few error messages at this stage, because some imports are missing. Hover the cursor over the marked types, then the Eclipse wizard will display proposals for the imports. For the timer we need to be careful to select the class org.ogema.core.application.Timer, instead of java.util.Timer, or the like. For StringResource and StringResourceHelper only one option should be offered. Double-click the proposed classes to add the missing imports. The error warnings should disappear. (Instead of the hovering method, you can place the cursor at the end of the unknown class name, and press Ctrl + Space, to open the Import wizard.)

importWizard.png

Resolving the missing imports in Eclipse.

Build the app

Now we can build the app: right-click on the project and select Run as -> Maven install. The build process will start, and hopefully end with a "Build successful" message. In case there are errors you may want to compare your code to the one in the repository: https://github.com/ogema/tutorial/blob/master/src/hello-ogema/src/main/java/com/example/app/hello/ogema/HelloOgemaApp.java.

Start the app

That's it... our app is ready to go! So let's add it to the start configuration of the OGEMA rundir. In the workspace you should have a project called "stdRundir", with a subfolder "config", that in turn contains a file "config.xml". Open the file in Eclipse (you may need to select the "Show source" tab to see the actual file content), and add a line to the bundle configurations:

<bundle dir="bin/apps" groupId="com.example.app" artifactId="hello-ogema" version="1.0.0-SNAPSHOT" startLevel="30" />

The parameters "groupId", "artifactId" and "version" must match the ones in the pom.xml file of the application. Now start the rundir: In stdRundir right-click the file default_clean.launch -> select Run as -> default_clean. The Eclipse console should open, and display the framework log messages. After a while, you should only see new messages appearing from the hello-ogema app: 

helloMessages.png

In the OGEMA Resource view, the newly created Resource will be visible as well. Login to OGEMA in the browser as explained here, and open the Resource view at https://localhost:8443/ogema/frameworkadminindex/index.html#/resources. Our StringResource should appear as follows:

helloResourceView.png

To stop the Rundir execution, which is necessary before the Rundir can be started again, click the red Stop Icon in the Eclipse main Menu Bar or in the Console:

Eclipse_StopButton.png

For more information on Running / Managing the App with a Rundir see "Create a New Project and Run it".

Modify the Resource

Just for the sake of it, you can modify the content of the Resource via the ResourceTreeManipulator App, available at https://localhost:8443/de/iwes/tools/resource/tree/manipulator/index.html (assuming the framework is running). The console messages should adapt accordingly. In the manipulator app, first select the type "org.ogema.core.model.Resource" (which matches all Resources), and enter the resource path "helloOGEMA" in the second row. A text field should appear, that lets you modify the Resource value.

helloManipulator.png

Get the source code

The source code for this sample application can be obtained from Github: https://github.com/ogema/tutorial (folder src/hello-ogema; see Get tutorial apps from Github for instructions), or downloaded as a zip file.

Import the project into Eclipse: File -> Import -> Maven -> Existing Maven projects -> Root directory: enter path to project base folder -> Finish. 
Note: this will fail if you have already created the app as described above, because two projects cannot have the same name (hello-ogema in this case). A possible workaround is to modify the artifactId of the downloaded app to hello-ogema2 before importing it. For this purpose, open the pom.xml file with an editor of your choice, and change hello-ogema to hello-ogema2.

Next


Tags:
Created by Christoph Nölle on 2017/01/25 20:38