The OSGi Lifecycle

(source: OSGi Service Platform – Core Specification)

Eclipse runs on top of the OSGi runtime, which manages the bundles (components) that make up an application. At any time, each bundle is has one of these lifecycle states:

• INSTALLED: The OSGi runtime knows the bundle is there.
• RESOLVED: The bundle is there and all it’s prerequisites (dependencies) are available. The bundle can be started (or has been stopped).
• STARTING: The bundle is being started. If it has a BundleActivator class, the BundleActivator.start() method is being executed. When done, the bundle will become ACTIVE. Note: Bundles that can be activated lazily (Bundle-ActivationPolicy: lazy) stay in this state until one of their class files is loaded.
• ACTIVE: The bundle is running.
• STOPPING: The bundle is being stopped. If it has a BundleActivator class, the BundleActivator.stop() method is being executed. When done, the bundle will become RESOLVED.
• UNINSTALLED: The bundle has been removed from the OSGi runtime.

BundleListener

The BundleListener interface provides a convenient way to track lifecycle changes. It provides a bundleChanged(BundleEvent event) method, that is called by the OSGi runtime to communicate lifecycle changes.

To receive notifications, a BundleListener is added a BundleContext object. To stop receiving notifications, a BundleListener is removed from the BundleContent. This is shown in the next code snippet:

You can get this code from my eclipse-examples repository on Github.

To see how this works, we install, start, stop and uninstall a bundle called ‘example.bundle_1.0.0.jar’ using the OSGi Console (-console launch argument). The jar file is located in the example.eclipse.bundlewatcher project. Don’t forget to use three slashes after file:///.

BundleListener restrictions and the BundleWatcher

A BundleListener the can only receive notifications after it has been started. It will miss lifecycle events related to bundles being installed as the OSGi runtime starts. The Equinox OSGi runtime will (typically) install and resolve all bundles that are initially available, before starting any of them. This happens before our BundleListener is started.

To monitor the lifecycle changes that happen during the startup of the OSGi runtime we have to hook our code into the runtime itself. The details depend on the OSGi implementation.

Eclipse Equinox has a BundleWatcher interface, that provides a watchBundle(Bundle bundle, int type) method. The framework will call this method to communicate lifecycle changes.

To install the the BundleWatcher into the startup process, we need to ‘hook’ into the runtime, using an Equinox Adaptor Hook. This requires the following steps:

1. You will need org.eclipse.osgi as source code in your workspace (this is already part of my git repository).
2. In the same parent directory, create a fragment to org.eclipse.osgi (the example.eclipse.bundlewatcher project).
3. Create a file ‘hookconfigurator.properties’ pointing to your hook configurator class(es).
   
4. The hook configurator class must implement the HookConfigurator interface and have a no-argument constructor. The framework will call the addHooks(HookRegistry method), to allow you to install your BundleWatcher (in my example the BundleWatcher and HookConfigurator are implemented in the same class).
5. In your launch configuration, make sure to include the ‘org.eclipse.osgi’ bundle from your workspace (not the Target Platform!).
   
6. Your launch configuration must have the following command line argument (when running outside the workspace, you could put this into the eclipse.ini or config.ini files):-Dosgi.framework.extensions=example.eclipse.bundlewatcher
7. Before you deploy, verify your build.properties to make sure hookconfigurator.properties is included in the .jar file.

You can get this code from my eclipse-examples repository on Github.

To see how this works, we again install, start, stop and uninstall a bundle called ‘example.bundle_1.0.0.jar’ using the OSGi Console. The BundleWatcher output is in red. You can see the bundle watcher fragment and bundle listener bundle being installed and started during startup (before the bundle listener receives any events).

If you are curious about the Equinox Adaptor framework, will find the following links useful:

• Equinox Framework: How to get Hooked
• Eclipse Wiki: Adaptor Hooks
• Eclemma.org: Instrumenting OSGi Bundles Through Equinox Adaptor Hooks

BundleTracker

Since I’ve been asked about it in the comments, I’ve added a BundleTracker example to my github repository.

I think we all agree that, in general, it is better to use a standardized API than a proprietary one. BundleTracker is a great choice for most use cases. However, there are use cases where the additional API is very useful, e.g. when you are provisioning a system. If you are already committed to using Equinox, then BundleWatcher is an interesting alternative.

Have fun,
Elias.

Follow this link for detailed information on Tabris.

Thank you Eclipse Foundation and Google for organizing this event for the fourth year now!

Recently, I developed a “user account” system for a customer’s Eclipse RAP application. Here are a few do’s and don’ts, which I learned in the process.

To provide some context: Users can perform these actions: sign-up for a new account, sign-in to an existing account, reset the password for an existing account (screenshots above).

Passwords

• Never store passwords in plain-text.
• Store passwords only in hashed form.
• Hash using a widely accepted crypto-grade hash function; never your own.
• Before hashing, add a random salt to each password. This ensures that same passwords have different hashes (making them harder to guess).
• Use a slow (i.e. iterative) hash algorithm, to make brute force attacks less effective. This is called key stretching.
• To verify a sign-in attempt: retrieve the “salt” for that user, combine “salt” with password-candidate and compute the hash. If the computed hash matches the stored hash, proceed.
• Read this excellent tutorial on secure salted password storage before you start.

Sign-up (and user-entered-data)

• Check entered data for minimum and maximum lengths.
• Sanitize entered data to prevent Cross-Site-Scripting (XSS) and SQL-Injection attacks.
• Do use PreparedStatement, if your SQL-Query contains parameters.
• Do not send the password via email.

Password Reset

• Do not allow the user to log-in through the password reset workflow.
• Do not send a new password via email.
• Do send a reset token (hyperlink) to the email address associated with the user’s account.
• Have the reset token expire within a few minutes.
• Have the reset token expire after a successful login.

Hosting

• For security over untrusted networks (public WiFi, etc.), serve sensitive data (i.e. login, sign-up) via https.
• For best security, serve the whole application over https (if you can spare the CPU cycles).

Scaling

• Implement authentication/sign-up as a networked service, so that it can be used by multiple RAP server instances. For OSGi-based software, OSGi Remote Services with ECF are an easy way to do this.
• The authentication service should only be accessible on the internal network.

If you found this useful, follow me on twitter.

Elias.

In my current work, I’m shipping an RCP application that interacts directly with hardware connected to the user’s machine. These interactions are done through drivers, written in C, that are available in binary form as shared libraries.

The use of shared libraries introduces a few problems:

1. In order to load and be accessible from Java, the shared libraries must be on the PATH (windows) / LD_LIBRARY_PATH (unix). The user should not need to manually configure these environment variables. An excellent way to solve this, is to put the .dlls into the same directory as the application’s executable (the eclipse launcher).
2. However: the .dlls are platform specific (32-bit vs 64-bit / Windows vs OS X vs Linux). This means that the right version of the library must be placed next to each executable.

The Product Export Wizard / PDE-Build, allows us to do this with minimal effort, as described below:

1. I’m assuming you have a feature-based .product configuration file for your application.
2. In your feature, create a folder for each platform that you support.
   The example below supports three platforms: os-x-64-bit, win-32-bit, win-64-bit.
3. Place the appropriate binary files in each folder.
4. Edit the build.properties file, adding a:  root.os.ws.arch=foldername  entry for each platform.
   For example, the entry ‘win32.win32.x86=win32.x86′ means if you are on a 32-bit windows, place the contents of the folder ‘win32.x86′ next to the application’s executable.
5. If needed, add permissions entries to the build.properties file. These entries can be used to set the unix permissions for individual files, when needed.
   For example, the entry ‘root.macosx.cocoa.x86_64.permissions.755=library.so’ sets the permissions of ‘library.so’ file to ’755′.

Done — the .zip files created by the ‘Product Export Wizard’ (and PDE Build) now have the correct libraries, with permissions, next to the executable.

For more details, refer to “Adding Files to the Root of a Build” in the Eclipse Help.

If you made it this far, follow me on twitter,
Elias.

The remainder of this blog explains how to fix this:

The first thing to notice is that regular RCP applications do not have this issue. After exploring the code, you will discover the org.eclipse.ui.cocoa fragment, which provides Mac-specific customizations to the org.eclipse.ui bundle.

To configure the OS-X application menu, we copy the following files from org.eclipse.ui.cocoa into our project:

• CocoaUIEnhancer.java
• CocoaUtil.java
• SWTCocoaEnhancerDelegate.java
• Messages.properties

We then modify CocoaUIEnhancer.java, to make it work with pure SWT applications (it assumes we are running a workbench, which is not the case):

1. Modify the getProductName() method to return a String when no product is found (instead of null)
2. Wrap the code in hookWorkbenchListener() in a try-catch (IllegalStateException e) block
3. Wrap the code in modifyShells() in a try-catch (IllegalStateException e) block
4. Add some code to the actionProc(...) method, to bring up an About-Dialog and Preferences-Dialog (since we aren’t using commands):

        static long actionProc(long id, long sel, long arg0) throws Exception {
		// ...
		} else if (sel == sel_preferencesMenuItemSelected_) {
			showPreferences();
		} else if (sel == sel_aboutMenuItemSelected_) {
			showAbout();
		}
		return 0;
	}

	private static void showAbout() {
		MessageDialog.openInformation(null, "About...", 
                  "Replace with a proper about text  / dialog");
	}

	private static void showPreferences() {
		System.out.println("Preferences...");
		PreferenceManager manager = new PreferenceManager();
		PreferenceDialog dialog = new PreferenceDialog(null, manager);
		dialog.open();
	}

Finally, we add the following lines to our main() method:

	public static final String APP_NAME = "MyApp";

	public static void main(String[] args) {
		Display.setAppName(APP_NAME);
		Display display = Display.getDefault();

		if (SWT.getPlatform().equals("cocoa")) {
			new CocoaUIEnhancer().earlyStartup();
		}

		Shell shell = new Shell(display);
		shell.setText(APP_NAME);
		// ...

To try it, download the complete sample project.

If you like this, follow me on twitter,
Elias.

We have an application to deliver training content to medical professionals. An important issue for us is user-interaction with images. E.g. displaying images and allowing users to draw on them.

The example below shows how to draw on a static image using our Eclipse RAP framework. It works as follows:

1. Create an image resource from a file.
2. Create a Canvas widget. This is a blank area that we can paint on, with the help of a PaintListener object.
3. We use a MouseListener to react to the user’s clicks. A left-click adds a Point. A right-click removes a Point. The click triggers a redraw operation.
4. We use a PaintListener to draw on the canvas. The listener has access to a GC object. This is our ‘brush’ for drawing on the canvas. We draw the image first and then a sequence of lines using the stored points (step 3).

If you use RAP for mobile devices you can replace Canvas with ClientCanvas for better performance (it does more work on the client-side).

You can view the java code here. A complete project is available in my ‘rap-examples’ on github.

Follow me on twitter,
Elias.

Join us tomorrow at 7am in the Hyatt Lobby (rain or shine) for the last run of the conference.

We will also having a little contest with the chance to win Eclipse.org goodies: (thank you!)

• two black Eclipse.org long-sleeve shirts
• two women’s Eclipse.org polo shirts
• Eclipse.org insulating coffee mugs — battle-tested in arctic Ottawa

38 days left until EclipseCon — Sure, you’ve registered, booked the flight and hotel, checked your passport. Next: pack your running shoes!

Continuing the annual tradition started by Darin, we are organizing another edition of the EclipseCon Exercise:  an easy 3-mile run, starting in the Hyatt Lobby at 7:00 am each morning, Monday to Thursday. The trail is flat and paved and follows the stream / bike path behind the Hyatt.

Some reasons to run with us:

• have fun and enjoy the fabulous Californian weather
• burn off  last night’s food and beverages
• network in an informal setting
• get an EclipseCon 2011 runner’s shirt courtesy of EclipseSource

If you plan to join us, please RSVP on wiki.

Here’s a picture from last year’s group. I hope to have as many join in this year.

See you in Santa Clara,
Elias.

Below some pictures and slides from the event:

1. Michael Galpin (@michaelg) from eBay opened the night with a presentation on ‘Android Development with Eclipse’. He introduced the Android platform and demoed the Eclipse-based Android Development Tools (ADT). Interesting fact: eBay’s mobile applications on Android are enjoyed by more than 3 million users. If you want to learn more about Android, Michael’s upcoming Android book should be a good place to start.

2. John Thomas from RIM continued with ‘BlackBerry Application Development Options‘. BlackBerry developers have a variety of language choices for developing apps, such as Java, HTML5/Javascript and Adobe AIR. All development tools are integrated nicely in Eclipse and Adobe’s FlashBuilder (also Eclipse based). Visit this page for details on BlackBerry app development.

3. Elias Volanakis (@evolanakis) talked about ‘iPad Development with Eclipse RAP‘. After introducing the project I demoed how to write a calculator web-app for the iPad using Java. We are optimizing RAP for mobile devices for the 1.4 release next summer. You can download the slides here.

Thanks for joining us,
Elias.

• Android Development with Eclipse
• BlackBerry Application Development Options
• iPad development with Eclipse

The event is scheduled for this Monday, Nov 8th at 6pm at the Lucky Labrador Beer Hall, 1945 NW Quimby (map).

Please RSVP on the wiki (or sent me an email). Space is limited, so sign up now.

http://wiki.eclipse.org/Eclipse_DemoCamps_November_2010/Portland

Looking forward to see you there,
Elias.