PART 2. GETTING STARTED
Hello World Using the ESF Logger

 

Overview

·         Prerequisites

Hello World Using the ESF Logger

·         Create Hello World Plug-in

·         Add Dependencies to Manifest

·         Create Java Class

·         Resolve Dependencies

·         Create Component Class

Deploying the Plug-in

·         Export the OSGi Bundle

·         Create a Deployment Package

 

Overview

This section provides a simple example showing how to create an ESF “Hello World” OSGi project from scratch using Eclipse.  In this example, you will learn how to

 

·         Create a plugin project

·         Consume the ESF Logger service

·         Write an OSGi Activator

·         Export a single OSGi bundle (plug-in)

·         Create a Deployment Package

 

Prerequisites

·         Setting up ESF Development Environment

 

Hello World Using the ESF Logger

Create Hello World Plug-in

In Eclipse, create a new Plug-in project by selecting File | New | Project.  Select Plug-in Development | Plug-in Project and click Next.

 

 

Your screen should display the New Plug-in Project dialog box as shown in the following screen capture.  Give your project a name, such as “com.eurotech.example.hello_osgi”.  Under Target Platform, ensure that the an OSGi framework option button is selected and set to standard as shown in the following screen capture.  You can also (optionally) add projects to a working set.  To continue, click Next.

 

 

In the next menu, change the Name field to something more descriptive, such as “Hello World Example with ESF Logger”.  Make sure the Execution Environment list is set to match the Java JVM version running on the target device (JavaSE-1.6 or JavaSE-1.7).  To determine the JVM version running on the target device, log in to its administrative console and enter the command

 

java –version

 

Also, uncheck the Generate an activator, a Java class that controls the plug-in’s life cycle option button.  In this example, we will just have a single class.  We will not create an Activator class because we will use OSGi Declarative Services to start and stop the bundle.

 

Finally, click Finish.

 

 

You should see the new project in the My Projects working set in the Package Explorer (or Project Explorer).  Also, you will see the MANIFEST.MF was automatically opened in the Manifest Editor.  An OSGi bundle is really just a regular Java .jar file containing Java code and resources, along with a custom Manifest and an Activator.

 

Add Dependencies to Manifest

First, you will use the Manifest Editor in Eclipse to add some dependencies.  Click the Dependencies tab at the bottom and then click the Automated Management of Dependencies heading to expand it.

 

 

Under Automated Management of Dependencies, click Add.  In the Select a Plug-in field, enter org.eclipse.osgi.services.  Select the plug-in name and click OK.

 

 

Note this is very much like adding standalone jars to the buildpath by including the ‘-cp’ argument to javac.  However, in this case you are telling Eclipse where to find these dependencies the “OSGi way”, so it is aware of them at compile time.  Click Add again and use the same procedure to add the following dependency:

 

·         slf4j.api

 

You should now see the list of dependencies.  Save changes to the Manifest.

 

 

 

Create Java Class

Now you are ready to start writing a simple Java class.  Right-click the com.eurotech.example.hello_osgi project.  Select New | Class.  Set the Package field to com.eurotech.example.hello_osgi, set the Name field to HelloOsgi, and then click Finish.

 

 

Write the following code for the new class.  You can copy and paste this code into your newly created Java class file.

 

package com.eurotech.example.hello_osgi;   public class HelloOsgi {         private static final Logger s_logger = LoggerFactory.getLogger(HelloOsgi.class);       private static final String APP_ID = "com.eurotech.example.hello_osgi";         protected void activate(ComponentContext componentContext) {             s_logger.info("Bundle " + APP_ID + " has started!");             s_logger.debug(APP_ID + ": This is a debug message.");       }       protected void deactivate(ComponentContext componentContext) {             s_logger.info("Bundle " + APP_ID + " has stopped!");       } }

 

The activate() method is the entry point when the bundle in started.  The deactivate() method is the entry point when the bundle is stopped.

 

Notice the use of the private LoggerFactory.getLogger() method.  If the LoggerFactory method is present (running) in the OSGi framework and your hello_osgi bundle is started, your activate method is called, and you can simply access the service by calling the getLogger() method.

 

One convenient feature of Eclipse, auto-completion, is worth mentioning here.  If you type ‘s_logger.’ (instance name of the “LoggerFactory.getLogger” method) and stop after the period, it will show you a list of methods implemented in that class.  The examples above show two different methods used for logging messages.  Logger methods include: “error”, “warn”, “info”, “debug”, and “trace”, which represent increasingly lower (more detailed) levels of log information.  Logger levels should generally be used to represent

 

·         ERROR - A serious problem has occurred that requires attention from the system administrator.

·         WARNING - An action occurred or a condition was discovered that should be reviewed and may require action before an error occurs.  It may also be used for transient issues.

·         INFO - A report of a normal action or event.  This could be a user operation, such as "login completed", or an automatic operation, such as a log file rotation.

·         DEBUG - A debug message used for troubleshooting or performance monitoring.  It typically contains detailed event data including things an application developer would need to know.

·         TRACE - A fairly detailed output of diagnostic logging, such as actual bytes of a particular message being examined.

 

 

 

Resolve Dependencies

At this point, there will be errors in your code because of unresolved imports. 

 

Select the menu Source | Organize Imports to resolve these errors.  Because you added the “org.slf4j” to your dependency list, you will be prompted to choose one of two potential sources for importing the “Logger” class.  Select org.slf4j.Logger and click Finish.

 

 

Now the errors in the class should have been resolved.  Save the HelloOsgi class.

 

 

The complete set of code (with import statements) is shown below.

 

package com.eurotech.example.hello_osgi;   import org.osgi.service.component.ComponentContext; import org.slf4j.Logger; import org.slf4j.LoggerFactory;   public class HelloOsgi {         private static final Logger s_logger = LoggerFactory.getLogger(HelloOsgi.class);       private static final String APP_ID = "com.eurotech.example.hello_osgi";         protected void activate(ComponentContext componentContext) {             s_logger.info("Bundle " + APP_ID + " has started!");             s_logger.debug(APP_ID + ": This is a debug message.");       }       protected void deactivate(ComponentContext componentContext) {             s_logger.info("Bundle " + APP_ID + " has stopped!");       } }

 

For more information on using the Simple Logging Facade for Java (slf4j), see the Logger API.

 

 

Switch back to the Manifest Editor.  Under Automated Management of Dependencies, ensure the Import-Package option button is selected.  Click the add dependencies link to automatically add packages to the dependencies list based on the “import” statements in your example code.  Save changes to the Manifest again.

 

 

 

Create Component Class

Right-click the example project and select New | Other.  From the wizard, select Plug-in Development | Component Definition and click Next.

 

 

Next to the Class field, click Browse and type the name of your newly created class in the Select entries field.  In this case, type the word “hello”, and you will see a list of matching items.  Select the HelloOsgi class and click OK.

 

 

In the Enter or select the parent folder field, add "/OSGI-INF" to the existing entry (e.g., com.eurotech.example.hello_osgi/OSGI-INF).  Then click Finish.

 

 

After the Component class has been created, it will open in the Workspace.  In the Overview tab, the Name and Class point to our Java class.  Set the Activate field to activate and set the Deactivate field to deactivate.  This tells the component where these OSGi activation methods are located.  Then save the Component class definition file.

 

 

 

 

Deploying the Plug-in

The next few sections describe how to create a stand-alone JAR file as a deployable OSGI plug-in and how to create an installable Deployment Package.

 

An OSGi bundle is a Java archive file containing Java code, resources, and a Manifest.

 

A Deployment Package is a set of resources grouped into a single package file that may be deployed in the OSGi framework through the Deployment Admin service and may contain one or more bundles, configuration objects, etc.

 

 

Export the OSGi Bundle

Your bundle can be built as a stand-alone OSGi plug-in.

 

To do this step, right-click the project and select the Export menu.  This is equivalent to running javac on your project.  From the wizard, select Plug-in Development | Deployable plug-ins and fragments and click Next.

 

 

Under Available Plug-ins and Fragments, ensure the newly created plug-in is selected.  Under Destination, select the Directory option button and use the Browse button to select an appropriate place to save the JAR file on the local file system.  During the deployment process, described in the following section, you will need to remember the location where this file is saved.  Click Finish.

 

 

This will create a JAR file in the selected directory (e.g., /home/joe/myPlugins/plugins/com.eurotech.example.hello_osgi_1.0.0.jar).

 

 

Create a Deployment Package

Rather than creating a stand-alone plug-in, you can also create a Deployment Package that contains multiple bundles, configuration elements, etc. that can be deployed into an OSGi framework.  In this example, we will simply create a Deployment Package containing the “hello_osgi” bundle.  This step requires mToolkit to be installed.  (See ESF Setup for instructions on setting up the Eclipse development environment.)

 

Right-click the project and select New | Folder.  Select the com.eurotech.example.hello_osgi project and enter a folder named “resources”.  Then repeat this to create a folder named “dp” under the resources folder.  The resources/dp folder will be used to store the Deployment Package.

 

 

Select File | New | Other.  Select OSGi | Deployment Package Definition and click Next.

 

 

Ensure that the Target folder field is set to the /[project_name]/resources/dp folder.  In the File name field, enter the name for the new Deployment Package file to create, such as “hello_osgi”.  A version number can also be entered in the Version field.

 

 

Then click Finish.  Under the resources/dp folder in your project, verify that the [filename].dpp file was created.  This is a Deployment Package Project, which provides information needed to create the Deployment Package, such as its output directory, ant build file, etc.

 

 

Select the Bundles tab and then click New.  In the Bundle Path column, select the browse icon.  Browse to either the bundle’s project file ([filesystem_path]/.project file in the Workspace) or to the bundle’s JAR file created earlier.  Select the file and click Open.  This should populate the remaining columns as needed. 

 

 

Then save changes to the deployment package file.

 

In the resources/dp folder, right-click the .dpp file.  Select Quick Build.  This will create a new [filename].dp file in the same directory.  This is the final Deployment Package that can be installed on a remote target system.

 

 

 

In conclusion, you were able to create a new bundle from scratch, write the Java code and Activator, modify the Manifest, and build the plug-in and/or Deployment Package that can be used in an ESF environment.

 

The next steps will be to test your code in an Emulation mode and/or to deploy your code to a target system running ESF.  See Testing and Deploying Bundles to continue with those steps.