Everyware™ Software Framework
PART 3. ESF CODE EXAMPLES
Hello World Using the ESF Logger
· Overview
· Hello World Using the ESF Logger
Example
Overview
This is 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
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’. This will open the dialog shown in figure 1. Expand ‘Plug-in Development’ and select ‘Plug-in Project’ and click ‘Next’.
Figure 1 Creating a New Plug-in Project
You should now see the ‘New Plug-in Project’ dialog box shown in Figure 2. Give your project a name ‘com.esf.example.helloworld’ and change the ‘This plug-in is targeted to run with’ to ‘an OSGi framework’ that is ‘standard’. This is also shown in Figure 2. Also, because we started the project by right clicking on our ‘My Projects’ working set you will see that this is already selected in the dialog. Now click next.
Figure 2 New Plug-in Project Dialog
Now you should see the dialog box shown in figure 3. We change the name to something more verbose ‘Hello World Example Using the ESF Logger Service’ and also 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, we need to uncheck the ‘Generate an activator, a Java class that controls the plug-in’s life cycle. Since we are going to be using the Service Activator Toolkit (SAT) we should write the Activator by hand. Finally click ‘Finish’.
Figure 3 Finalizing the New Plug-in Project
You should now 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, we need to use the Manifest editor in Eclipse to add some dependencies. Start by clicking on the ‘Dependencies’ tab on the bottom and then clicking the ‘Automated Management of Dependencies’ tab to expand it. These are both shown in figure 4.
Figure 4 Manifest Automated Dependency Management
Now make sure that ‘import package’ is selected and click the ‘Add…’ button. These are shown in figure 5.
Figure 5 Adding Dependencies
This will open the dialog in figure 6. With this Plug-in selection dialog you can select new dependencies. Since we are going to add the logger we 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 I begin by typing ‘*logger’. Note by the time I get to ‘*lo’ my desired service is the only one present. This is also shown in figure 6. Select it and click ‘OK’.
Figure 6 Adding the Logger Service Dependency
You should now see the ESF Logger Service in the list of dependencies as shown in figure 7.
Figure 7 After Adding the ESF Logger Service
Note this is very much like adding standalone jars to the buildpath by including the ‘-cp’ argument to javac. However, in this case we 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 we need to add. Use the same procedure to add these 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 one shown in figure 8.
Figure 8 Added Dependencies
Now we are ready to start writing out classes. Let’s start with the simple Java code. Right click on the ‘src’ directory of the com.esf.example.helloworld project. Now go to ‘new->class’. This will open the dialog shown in figure 9. Set the package name to ‘com.esf.example.helloworld’, the Name to ‘HelloWorld’, then click ‘Finish’.
Figure 9 HelloWorld Class Creation
Write the code for the new class. This should do:
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;
}
}
Note 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. Note 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 we added the com.esf.core.logger.service to our 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.
Now we’re ready to start writing the Activator. This contains the entry points to our bundle. Start by right clicking on the ‘src’ directory of the com.esf.example.helloworld project. Now go to ‘new->class’. This will open the dialog shown in figure 10. 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’ then click ‘Finish’.
Figure 10 Creating the Activator Class
The BaseBundleActivator is a Class in SAT that simplifies a lot of work we need to do in our Activator. Writing Activators from scratch can be very difficult and require a lot of synchronization and understand of OSGi at a low level. SAT releases us from this work. After creating the class you should now see what is shown in figure 11.
Figure 11 The Empty Activator
Now we need to add some code to the Activator to make it do something interesting. There are three main methods to focus on. 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 tells SAT what this bundle requires in order to start. Until all of these dependencies are resolved our start method will not be called. Of course we also need to tie in our HelloWorld class. This 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
};
}
}
Note the private getIEsfLoggerService() method. This is the part of the magic of OSGi. If the IEsfLoggerService is present in the framework (running) and our HelloWorld bundle is started, our activate method is called and then we ‘grab’ the service by calling the getImportedService method. Then we can just use it as needed.
Finally we need to do a bit more work on the manifest. When we added the dependencies we only told Eclipse where it could find our dependencies. We need to add them to the manifest that gets deployed with the jar file. To do so, open the manifest and go back to the ‘Dependencies’ tab. Now click the ‘add dependencies’ button as shown below. After clicking the button you will see the necessary packages appear on the right side in the ‘imported packages’ section. This is shown in figure 12.
Figure 12 Adding the Dependencies to the Manifest
Now we need to change the manifest so it knows where the Activator is. Click the ‘Overview’ tab of the manifest editor and type or browse for com.esf.example.helloworld.bundle.Activator in the Activator’ field. This is shown in figure 13.
Figure 13 Specifying the Activator
Now save the manifest and all other files if you haven’t already. At this point we are ready to ‘export’ our bundle. This is equivalent to running javac on our project. Start by right clicking on the project in the Package Explorer and select ‘Export’. This will open the Export Wizard shown in figure 14. Select ‘Plug-in Development -> Deployable plug-ins and fragments’ and then click ‘Next’.
Figure 14 Exporting the Plug-in
This will open the Deployable Plug-ins and Fragments Export Wizard. You should select a destination directory. Below you can see the Desktop was selected in figure 15. If you want to build other plug-ins you can select them now. Once done, click ‘Finish’.
Figure 15 Selecting the Plug-ins and Destination Directory
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 in our example as shown in figure 16.
Figure 16 The Built Bundle
Now we need to deploy the bundle to the target system. As described in the ESF Startup Process we have a few options for starting our bundle. In this example we will use the ‘dropins’ directory. The target has a SFTP server running on it by default. We 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 you can use command line scp to transfer the files. This 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 would be:
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 the transfer.
Transfer Files - Windows
If you are running on a Windows host Winscp is a good option. It is a free download from here. Figure 17 shows a screen shot of winscp 4.2.8. It is like a standard FTP client but uses SFTP underneath. To establish a connection you must enter in 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’. This is also shown in figure 17.
Figure 17 Connecting with Winscp
After hitting login you will likely be presented with a security warning about adding the host key to the cache. Click ‘OK’ to continue. You should now be looking at the main Winscp window as shown in figure 18. In the left pane you should navigate to the plugins directory where your built bundle is. In the right pane you should navigate to the /opt/jvm/esf/dropins/ directory. Then simply drag and drop com.esf.example.helloworld*.jar to the right.
Figure 18 Winscp After Copying the Plug-in
Now you have copied the built bundle to the target. We now 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. This 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]
This is an example
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 free one you can download. Once you have installed it 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.
Figure 19 Establishing a Putty 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 it to log into the remote device.
Run the Bundle
Now that we have copied the file to the remote target and established console sessions with the remote device we are ready to see our bundle run. We can do this by running the following commands in our ssh sessions.
cd /opt/jvm/esf/
./start_equinox.sh
In the startup process you should see a message like this from the console:
[DEBUG] 2010-07-22 15:05:38.309 - Hello World
This is from our 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 there as shown in figure 20.
Figure 10 Hello World running
Note the ‘bundle id’ is 140 in our example. We can start and stop the bundle using the start and stop commands in Equinox to see our bundle in action. This is shown in figure 21.
Figure 21 Hello Goodbye World
In conclusion we 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.
Copyright © 2010 Eurotech Inc. All rights reserved.