Hello World Example

PART 3. ESF CODE EXAMPLES
Hello World Using the ESF Logger

 

Example

·            Overview

·            Prerequisites

·            Hello World Using the ESF Logger

·            Transfer Files - Linux

·            Transfer Files - Windows

·            Target Login - Linux

·            Target Login - Windows

·            Run the Bundle

Example

Overview

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

·         Create a plugin project

·         Consume the ESF Logger Service

·         Write a SAT Activator

·         Write simple bind and unbind methods

·         Deploy the code to a running target using the ‘dropins’ directory

·         See the code run

           

Prerequisites

·         Installing the Eclipse IDE

·         Integrating ESF Tooling and Projects into Eclipse

or

·         Installing ESF Tooling into Wind River Workbench

and

·         Using Working Sets

 

Hello World Using the ESF Logger

Create a new plugin project by right-clicking on the ‘My Projects’ working set in the Package Explorer.  Then go to ‘new -> project’.  Expand ‘Plug-in Development’, select ‘Plug-in Project’, and click ‘Next’.

 

 

Your screen should display the ‘New Plug-in Project’ dialog box shown in the following screen capture.  Give your project a name ‘com.esf.example.helloworld’.  Under Target Platform, change the option called ‘This plug-in is targeted to run with:’   to   ‘an OSGi framework: standard’, as shown.  Also because you started the project by right-clicking on our ‘My Projects’ working set, you will see that this option is already selected in the dialog.  To continue, click ‘Next’.

 

 

Change the name to something more verbose ‘Hello World Example Using the ESF Logger Service’ and change the Execution Environment to OSGi/Minimum-1.1.  This is the smallest JVM profile that is supported by all Eurotech platforms.  Unless this is really not an option, you should always select this profile.  Also, uncheck the ‘Generate an activator, a Java class that controls the plug-in’s life cycle’.  Since you are going to be using the Service Activator Toolkit (SAT), you should write the Activator by hand.  Finally, click Finish.

 

 

You should see the new project in the ‘My Projects’ working set in the Package Explorer.  Also, you will see the MANIFEST.MF was automatically opened.  An OSGi bundle is really just a regular Java .jar file with a custom manifest and an Activator.  We’ll cover both of these in this tutorial.

 

First, you will use the Manifest editor in Eclipse to add some dependencies.  Click on the ‘Dependencies’ tab on the bottom and then click the ‘Automated Management of Dependencies’ tab to expand it.

 

 

Make sure that ‘import package’ is selected and click the ‘Add…’ button.

 

 

With this Plug-in selection dialog, you can select new dependencies.  Since you are going to add the logger, you can start typing in the ‘Select a Plug-in’ box.  You can use * for a wildcard.  Since not many bundles would have ‘logger’ in their name, begin by typing ‘*logger’.  Note by the time you get to ‘*lo’, the desired service is the only one present.  Select this service and click ‘OK’.

 

 

You should now see the ESF Logger Service in the list of dependencies.

 

 

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.  There are some other dependencies you need to add.  Use the same procedure to add the following dependencies:

 

org.eclipse.osgi

org.eclipse.soda.sat.core

 

Finally, save the manifest by typing ‘ctrl s’ or clicking the save icon in Eclipse.  Your dependency list should look like the figure below.

 

 

Now you are ready to start writing out classes.  Start with the simple Java code.  Right-click on the ‘src’ directory of the com.esf.example.helloworld project.  Select ‘new->class’.  Set the package name to ‘com.esf.example.helloworld’, set the Name to ‘HelloWorld’, and then click ‘Finish’.

 

 

Write the following code for the new class.

 

package com.esf.example.helloworld;

 

import com.esf.core.logger.service.IEsfLoggerService;

 

public class HelloWorld {

 

      private IEsfLoggerService esfLoggerService;

     

      public void bind(IEsfLoggerService esfLoggerService) {

            this.esfLoggerService = esfLoggerService;

            esfLoggerService.logDebug("Hello World");

      }

     

      public void unbind() {

            esfLoggerService.logDebug("Goodbye World");

            this.esfLoggerService = null;

      }

}

 

There are some important things to point out here.  The bind and unbind serve as the entry points at start up time and shutdown time for this bundle.  There is no constructor.  The bind essentially becomes the constructor of the class, and unbind acts as an explicit destructor to remove references to services.  It is important to do this in bind because the bundle should start up clean if it is restarted.

 

There are some handy tricks about writing code in Eclipse that should be pointed out.  ‘ctrl shift o’ will auto organize your imports.  Because you added the com.esf.core.logger.service to your dependency list, it is found automatically by Eclipse.  Also, auto-completion is convenient.  If you write ‘esfLoggerService.’ and stop after the period, it will show you a list of methods implemented in that class.

 

You’re ready to start writing the Activator.  This contains the entry points to your bundle.  Start by right-clicking on the ‘src’ directory of the com.esf.example.helloworld project.  Select ‘new->class’.  Set the package name to ‘com.esf.example.helloworld.bundle’, the Name to ‘Activator’, and the Superclass to ‘org.eclipse.soda.sat.core.framework.BaseBundleActivator’.  Click ‘Finish’.

 

 

The BaseBundleActivator is a Class in SAT that simplifies a lot of work you need to do in your Activator.  Writing Activators from scratch can be very difficult and require a lot of synchronization and understanding of OSGi at a low level.  SAT releases you from this work.  After creating the class, Your screen should display the following screen capture.

 

 

Next, you need to add some code to the Activator to make it do something interesting.  There are three main methods on which to focus.  The activate() method is the entry point when the bundle in started.  The deactivate() method is the entry point when the bundle is stopped.  The getImportedServiceNames() method is called by SAT.  This method tells SAT what the bundle requires in order to start.  Until all of these dependencies are resolved, your start method will not be called.  Of course, you also need to tie in your HelloWorld class.  The following is the fully implemented Activator.

 

package com.esf.example.helloworld.bundle;

 

import org.eclipse.soda.sat.core.framework.BaseBundleActivator;

 

import com.esf.core.logger.service.IEsfLoggerService;

import com.esf.example.helloworld.HelloWorld;

 

public class Activator extends BaseBundleActivator {

      private HelloWorld helloWorld;

     

      protected void activate() {

            helloWorld = new HelloWorld();

            helloWorld.bind(getIEsfLoggerService());

      }

 

      protected void deactivate() {

            helloWorld.unbind();

            helloWorld = null;

      }

 

      private IEsfLoggerService getIEsfLoggerService() {

            return (IEsfLoggerService) getImportedService(IEsfLoggerService.SERVICE_NAME);

      }

 

      protected String[] getImportedServiceNames() {

            return new String[] {

                        IEsfLoggerService.SERVICE_NAME

            };

      }

}

 

Notice the private getIEsfLoggerService() method.  This is part of the magic of OSGi.  If the IEsfLoggerService is present in the framework (running) and your HelloWorld bundle is started, your activate method is called and you ‘grab’ the service by calling the getImportedService method.  Then you can just use it as needed.

 

Finally, you need to do a bit more work on the manifest.  When you added the dependencies, you only told Eclipse where it could find your dependencies.  Add them to the manifest that gets deployed with the jar file by opening the manifest and selecting the ‘Dependencies’ tab.  Click the ‘add dependencies’ button as shown in the following screen capture.  After clicking the button, you will see the necessary packages appear on the right side in the ‘imported packages’ section.

 

 

Next, you need to change the manifest so it knows where the Activator is located.  Click the ‘Overview’ tab of the manifest editor and type or browse for com.esf.example.helloworld.bundle.Activator in the Activator’ field.

 

 

Save the manifest and all other files if you haven’t already.  At this point, you are ready to ‘export’ your bundle.  This is equivalent to running javac on your project.  Right-click on the project in the Package Explorer and select ‘Export’.  The Export Wizard will open.  Select ‘Plug-in Development -> Deployable plug-ins and fragments’ and then click ‘Next’.

 

 

The Deployable Plug-ins and Fragments Export Wizard will open.  Select a destination directory.  If you want to build other plug-ins, you can select them now.  Once done, click ‘Finish’.

 

 

Once built, you will find a ‘plugins’ directory in the destination directory you selected in the wizard.  So, the final path to the built plugin will be C:\Documents and Settings\user\Desktop\plugins\com.esf.example.helloworld*.jar.

 

 

Now you need to deploy the bundle to the target system.  As described in the ESF Startup Process, you have a few options for starting your bundle.  In this example, you will use the ‘dropins’ directory.  The target has a SFTP server running on it by default.  You need a client to connect to it.

 

The next sections have headings for Linux or Windows.  Follow the directions based on the host OS you are using.

 

Transfer Files - Linux

If you are using Linux for development, use command line scp to transfer the files.  The following is the usage for scp.

 

usage: scp [-1246BCpqrv] [-c cipher] [-F ssh_config] [-i identity_file]

           [-l limit] [-o ssh_option] [-P port] [-S program]

           [[user@]host1:]file1 ... [[user@]host2:]file2

 

An example is scp com.esf.example.helloworld*.jar root@192.168.1.20:/opt/jvm/esf/dropins/.

 

You will likely be prompted to add the host to the cache.  Select ‘yes’ to continue.  The file will transfer.

 

Transfer Files - Windows

If you are running on a Windows host, Winscp is a good option.  It is a free download from WinSCP.Net.  To establish a connection, you must enter the IP Address of the host (the ‘Host name’), the ‘User name’ (which is ‘root’), and the ‘Password’ for the system.  After setting these fields, click ‘Login’.

 

 

After clicking ‘Login’, you will likely be presented with a security warning about adding the host key to the cache.  Click ‘OK’ to continue.  Your screen should display the main Winscp window.  In the left pane, navigate to the plugins directory where your built bundle is located.  In the right pane, navigate to the /opt/jvm/esf/dropins/ directory.  Then simply drag and drop com.esf.example.helloworld*.jar to the right.

 

 

After you have copied the built bundle to the target, you need to run it.

 

Target Login - Linux

To run ESF, you need to log into the remote target.  You can use command line ssh to do this.  The following is the usage.

 

usage: ssh [-1246AaCfgKkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec]

           [-D [bind_address:]port] [-e escape_char] [-F configfile]

           [-i identity_file] [-L [bind_address:]port:host:hostport]

           [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]

           [-R [bind_address:]port:host:hostport] [-S ctl_path]

           [-w local_tun[:remote_tun]] [user@]hostname [command]

 

An example is ssh root@192.168.1.20.

 

At this point, you will be prompted to add the host to the cache (if you haven’t already) and be prompted for a password.  Enter the password to log into the remote device.

 

Target Login - Windows

You need a ssh client to be able to connect to the remote target.  Putty is a good choice that is free to download.  Once you have installed Putty, open it and enter ‘root@ip_address’ in the ‘Host Name (or IP address)’ field as shown in figure 19.  The example uses 192.168.1.20 for the IP address.  Once entered, click ‘Open’ to start the session.

 

 

Again, you will be prompted to enter the remote host into the cache if you haven’t already done so.  Accept to continue.  You will then be prompted for a password.  Enter your password to log into the remote device.

 

Run the Bundle

After you have copied the file to the remote target and established console sessions with the remote device, you are ready to see your bundle run. 

 

Run the following commands in your ssh sessions.

 

cd /opt/jvm/esf/

./start_equinox.sh

 

In the startup process, you should see a message similar to the following from the console:

 

[DEBUG] 2010-07-22 15:05:38.309 - Hello World

 

This message is from your bundle.  You can type ‘ss’ to see a list of all of the bundles running in the environment.  You should see com.esf.example.helloworld running.

 

 

Notice the ‘bundle id’ is 140 in the example.  You can start and stop the bundle using the start and stop commands in Equinox to see your bundle in action.

 

 

In conclusion, you were able to create a new bundle from scratch, write the Java code and Activator, modify the manifest, build the binary, copying to the target, and run it in ESF.

 

The code for this example can be downloaded here.