I attended a tutorial at EclipseCon 2009 on ReSTful OSGi Web Applications which was based on the Ensemble project at NASA and Restlet 1.x.  I recently started looking at Restlet 2.0 and updated the Ensemble code to work with the new API, cleaned up a possible threading issue, and added an OSGi service for extensibility.  I was hoping to share these changes in this post, but the open source license under which the Ensemble code was released is too prohibitive (private, non-comercial, use only) for my use.  I had assumed that it was released under EPL, and I was wrong.

The functionality provided by the Ensemble code is rather simple.  It provides an Eclipse extension point for registering a Restlet representation.  It also has the ability to handle the dynamic nature of OSGi bundles allowing extensions to come and go during runtime.  It’s too bad my work was for not.  Fortunately, a colleague has agreed to attempt to reproduce this functionality, and since he has not seen the Ensemble source code, nor discussed it with me, he will be able to release his code under EPL.

Lesson learned: Always check the license before looking at the source code.

There are a lot of tools available for building software, each with it’s own strengths and weaknesses. They all fundamentally do the same job – they convert source code into an application that can be delivered to a customer. Building an application generally involves multiple steps, and it seems natural that those steps could be described as a workflow. I will demonstrate how to model a build process using my EMF workflow model.

Let’s define a build process with more than one task.  We will compile a Java source file into a class file, jar the class file, and finally zip the jar file.  I started by creating domain specific extensions (Figure 1) to the EMF workflow model.  Remember that the workflow model is a framework and domain specific tasks are developed as extensions to the model.

Figure 1

I start by creating an Empty EMF Project and then a new Ecore Model.  Next, load the EMF workflow model as a resource of the ecore extension model.  Create three new classes: JavaCompiler, JavaJar, and ZipFile each extending WorkflowUnitOfWork. Finally, create non-containment references to WorkflowParameter as follows:

JavaCompiler

• classNameParameter
• classpathParameter
• workingDirectoryParameter

JavaJar

• classNameParameter
• workingDirectoryParameter
• outputFileParameter

ZipFile

• workingDirectoryParameter
• inputFileParameter
• outputFileParameter

These con-containment references are created for convenience which will be apparent when the workflow is constructed.  Now that the model extensions have been defined, the model and edit code can be generated.  Remember to set Child Creation Extenders and Extensible Provider Factory to true.

The last piece of the development is to provide the executable functionality of each of the tasks.  Here are the implementations of each of the run() functions:

JavaCompiler

@Override
public WorkflowState run(WorkflowContext context) throws WorkflowRuntimeException
{
	File workingDirectory = new File((String) workingDirectoryParameter.getValue(context));
	String[] command = {"javac", "-cp", (String) classpathParameter.getValue(context), (String) classNameParameter.getValue(context) + ".java"};
	int rc = 0;

	try
	{
		logDebug(context, "Executing command: javac -cp " + command[2] + " " + command[3]);
		Process process = Runtime.getRuntime().exec(command, null, workingDirectory);
		rc = process.waitFor();
	}
	catch (Exception e)
	{
		logException(context, e);
		return StateFactory.eINSTANCE.createWorkflowErrorState();
	}

	return rc == 0 ? StateFactory.eINSTANCE.createWorkflowSuccessState() : StateFactory.eINSTANCE.createWorkflowFailedState();
}

JavaJar

@Override
public WorkflowState run(WorkflowContext context) throws WorkflowRuntimeException
{
	File workingDirectory = new File((String) workingDirectoryParameter.getValue(context));
	String[] command = {"jar", "-cf", (String) outputFileParameter.getValue(context), (String) classNameParameter.getValue(context) + ".class"};
	int rc = 0;

	try
	{
		logDebug(context, "Executing command: jar -cf " + command[2] + " " + command[3]);
		Process process = Runtime.getRuntime().exec(command, null, workingDirectory);
		rc = process.waitFor();
	}
	catch (Exception e)
	{
		logException(context, e);
		return StateFactory.eINSTANCE.createWorkflowErrorState();
	}

	return rc == 0 ? StateFactory.eINSTANCE.createWorkflowSuccessState() : StateFactory.eINSTANCE.createWorkflowFailedState();
}

ZipFile

@Override
public WorkflowState run(WorkflowContext context) throws WorkflowRuntimeException
{
	File workingDirectory = new File((String) workingDirectoryParameter.getValue(context));
	String[] command = {"zip", (String) outputFileParameter.getValue(context), (String) inputFileParameter.getValue(context)};
	int rc = 0;

	try
	{
		logDebug(context, "Executing command: zip " + command[1] + " " + command[2]);
		Process process = Runtime.getRuntime().exec(command, null, workingDirectory);
		rc = process.waitFor();
	}
	catch (Exception e)
	{
		logException(context, e);
		return StateFactory.eINSTANCE.createWorkflowErrorState();
	}

	return rc == 0 ? StateFactory.eINSTANCE.createWorkflowSuccessState() : StateFactory.eINSTANCE.createWorkflowFailedState();
}

Now that we have domain specific tasks that can do actual work, we can assemble them into a build process / workflow. Launch the runtime workbench, create a new project, and create a new ecore model. Here are the results:

After the build workflow has been created, we can create a runtime model that contains the parameter values for the build.

I’ve set up this example runtime to build Hello.java in the working directory /tmp/build. When you run the workflow, it will generate Hello.class, hello.jar, and finally hello.zip. You may have noticed that not all modeled parameters have values in the runtime model. I created parameter connections in the workflow model for those parameters that share values. For this example, I also created a second runtime to build Bye.java using the same build process. This complete example is available in CVS at dev.eclipse.org /cvsroot/modeling/org.eclipse.emf/org.eclipse.emf.mwe/examples.

There is a screencast available until I need the disk space.

I have been working on an EMF Workflow Model for some time now, and the documentation on how to use the model has been lacking.  In this post, I will show you how to extend and use the model with a complete example.  The EMF Workflow Model is a framework for modeling workflows.  Developers must extend the model by creating objects that do useful work.  Once the model has been extended, users may then assemble workflows from the components provided.  The core of the model is a composite pattern that allows a workflow to be constructed as an arbitrary tree forming a directed graph.  The framework supports executing nodes of the model in serial, parallel, loops, and conditionally.  Each node can be parameterized, and provides execution state that can be persisted.

There are two major parts to the workflow model:  a design model, and a runtime model.  The design model specifies which tasks to execute and the order they are executed.  The runtime model specifies the parameter values and state of the running workflow.  Separating the design model from the runtime model allows you to have a single workflow that can be executed with different permutations by choosing a different runtime model.

Workflow Design Model

The design model is based on a composite pattern (Figure 1).  The composite pattern allows for the construction of arbitrarily complex workflows.  Workflows can be a simple sequence of steps or a complicated tree of sub-workflows.  The flow of execution, or orchestration, is modeled as a strategy pattern (Figure 2). This allows custom flow control strategies to be plugged into the workflow providing a rich framework for executing workflows.  The framework includes strategies for executing workflow tasks in serial, parallel, conditionally, and in a loop.

Figure 1

• WorkflowComponent – the abstract root of the composite
• CompositeWorkflowComponent – the branches of the tree
• WorkflowUnitOfWork – the abstract leaves of the tree (you must extend this class)
• WorkflowParameter – the keys of the runtime parameter map
• WorkflowParameterConnection – connect an output parameter to one or more input parameters

Figure 2

• WorkflowCompositeOrchestrationStrategy – abstract base class that controls the execution of children of a composite
• WorkflowParallelOrchestrationStrategy – executes the children of a composite in parallel
• WorkflowSerialOrchestrationStrategy – executes the children of a composite in serial
• WorkflowComponentOrchestrationStrategy – base class that controls the execution of a component
• WorkflowLoopComponentOrchestrationStrategy – executes a component in a loop
• WorkflowExecutionPredicate – abstract base class for conditional predicates
• WorkflowPredicateAND – logical AND of the child predicates
• WorkflowPredicateOR – logical OR of the child predicates
• WorkflowRerunPredicate – predicate based on the state of the last run
• WorkflowParameterPredicate – predicate based on a parameter
• WorkflowLoopCountPredicate – predicate based on a parameter value count

Workflow Runtime Model

The runtime model holds the dynamic information used by the workflow during execution.  This includes parameter values, execution state, and logging (Figure 3).  Parameter values are stored as instances of EObject allowing you to pass any modeled object to a workflow task.  Simple values such as String, Integer, etc can be wrapped in an instance of SimpleAnyType.  Since tasks can be executed in parallel, the runtime model makes use of EMF Transaction for thread safe access to the workflow data.  Workflow states are modeled using the state pattern (Figure 4).  You may extend a state if your task needs state granularity not currently provided.  You should not access the data in the WorkflowContext directly while the workflow is running, but instead use the convenience functions in the various design model classes.

Figure 3

• WorkflowContext – the root container for all runtime data
• WorkflowStateMap – maps a WorkflowComponent to a WorlflowState
• WorkflowComponentExecutionInfoMap – maps a WorkflowComponent to a WorkflowComponentExecutionInfo
• WorkflowParameterMap – maps a WorkflowParameter to its value
• WorkflowLogMap – maps a WorkflowComponent to a WorkflowLog

Figure 4

• WorkflowState – abstract base class for all workflow states
• WorkflowIdleState – the task has not been executed
• WorkflowDoneState – the task has finished executing
• WorkflowRunningState – the task is currently running
• WorkflowSuccessState – the task has finished successfully
• WorkflowFailedState – the task has finished with a failure
• WorkflowErrorState – the task has finished with an exception

Getting The Workflow Model

The model is contributed to the MWE sub-project under EMFT at Eclipse.org.  My contribution is not currently part of the MWE build, so you will have to start by extracting the model from CVS.  Start Eclipse and open the CVS Perspective.  Use the following connection:

• Host: dev.eclipse.org
• Path: /cvsroot/modeling
• User: anonymous
• Connection type: pserver

Expand the path: HEAD -> org.eclipse.emf -> org.eclipse.emf.mwe -> plugins and checkout the bundles org.eclipse.emf.mwe.ewm.*.  The org.eclipse.emf.mwe.core bundle contains the EMF model that you will extend.  The other bundles are primarily for convenience of experimenting with the workflow model.

Target Platform

The EMF workflow model requires the following projects in your target platform:

• Eclipse SDK for your platform
• EMF
• EMF Transaction

Extending The Workflow Model

Workflow tasks are domain specific and the EMF workflow model provides a framework for assembling and executing your domain specific tasks.  To use the EMF workflow model, you must extend WorkflowUnitOfWork to provide domain specific functionality in the run() function.  Use the following steps to create an extension to the workflow model:

1. Create a new Empty EMF Project named org.example.workflow
2. Create a new Ecore Model
3. Load Resource… platform:/resource/org.eclipse.emf.mwe.ewm.core/model/workflow.ecore
4. Create a new EClass
5. Name: ExampleTask
6. ESuperTypes: WorkflowUnitOfWork

Next, we need to create a genmodel and generate our code:

1. Create a new EMF Generator Model
2. Import from Ecore model
3. Add org.eclipse.emf.mwe.ewm.core/model/workflow.genmodel as a referenced generator model
4. Select both org.eclipse.emf.ecore and org.eclipse.emf.mwe.ewm.workflow as referenced generator models
5. Suppress Interfaces: true
6. Base Package: org.example.workflow
7. Child Creation Extenders: true
8. Extensible Provider Factory: true
9. Generate Model Code
10. Generate Edit Code

You will notice that ExampleTask does not compile.  The run() function in WorkflowUnitOfWork is abstract and where you need to add your domain specific business logic.  Open ExampleTask in the editor and choose the quickfix: Add unimplemented methods.  Go to the run() function and provide the following implementation:

@Override
public WorkflowState run(WorkflowContext context) throws WorkflowRuntimeException
{
	System.out.println("Hello world");
	return StateFactory.eINSTANCE.createWorkflowSuccessState();
}

Composing A Workflow

Now that you have a domain specific task that does useful work (“hello world” is arguably not useful – just envision a useful task), your task can be assembled into a workflow.  To do this, we will use the EMF generated editor to create an instance of the workflow model:

1. Create a new Eclipse Application launch configuration
2. Launch the runtime workbench
3. Create a new General -> Project
4. Create a new Workflow Model
5. Select the root model object: Composite Component
6. Set the name of the composite to Root
7. Create a New Child of Composite Component: Workflow Serial Orchestration Strategy
8. Create a New Child of Composite Component: Workflow Component Orchestration Strategy
9. Create a New Child of Composite Component: Workflow State Resolution Strategy
10. Create a New Child of Composite Component: Task
11. Set the name of the task to Task
12. Create a New Child of Task: Workflow Component Orchestration Strategy

Every component must have an orchestration strategy.  In this model, there are two components: the root composite, and your example task.  Each of these components has a WorkflowComponentOrchestrationStrategy.  This strategy, by default, simply runs the component.  Every composite must have a composite orchestration strategy, and a state resolution strategy.  In this model, the composite orchestration strategy is WorkflowSerialOrchestrationStrategy which executes the children of the composite serially.  The WorkflowStateResolutionStrategy determines the state of the composite based on the state of the children after all of the children have executed.

Running A Workflow

To run the workflow you just assembled, you will need a runtime model and a launch configuration:

1. Create a new Runtime Model
2. Select the root model object: WorkflowContext
3. Create a new EMF Workflow launch configuration
4. Set Workflfow: platform:/resource/test/My.workflow
5. Set Context: platform:/resource/test/My.runtime
6. Launch the workflow

As your workflow executes, it will print “Hello world” to the console.  Don’t forget that the output will go to the Console view in the host workbench and not the runtime workbench.  There is an alternate way to run your workflow by right-clicking the workflow model and selecting Run Workflow.  You will be prompted to select the runtime model, the workflow will execute, and the runtime will be saved back to the workspace.  Note that the launcher will not save the runtime after execution.  After your workflow has terminated, you can view the contents of the runtime by right-clicking on the runtime model and selecting View Workflow Status.  You can reset the workflow runtime information by right-clicking on the runtime model and selecting Reset Workflow State.

Parameterizing A Workflow

Let’s make the workflow example task a bit more interesting by giving it a parameter for the message to print to the console instead of the hard-coded “Hello world”.  Change ExampleTask.run() to:

@Override
public WorkflowState run(WorkflowContext context) throws WorkflowRuntimeException
{
	System.out.println(getParameters().get(0).getValue(context));
	return StateFactory.eINSTANCE.createWorkflowSuccessState();
}

This will print the value of the first parameter assigned to the task. Before you can run the workflow, you must model the parameter, and give it a value in the runtime model.

1. Launch the runtime workbench
2. Open the workflow model in the ecore editor
3. Create a new Workflow Parameter as a child of Task
4. Set the parameter name to Message
5. Set the parameter type to EString
6. Create a new Parameter Simple Value Strategy as a child of the Workflow Parameter
7. Open the runtime model in the ecore editor
8. Load Resource … platform:/resource/test/My.workflow
9. Create a new Workflow Parameter Map as a child of WorkflowContext
10. Select Parameter Message as the key
11. Create a new Simple Any Type as a child of the workflow parameter map
12. Set the Instance Type to EString
13. Set the Value to “That was easy”
14. Run the workflow and “That was easy” will print to the host Console

Future Direction

This tutorial will eventually be moved into on-line documentation as part of the project.  The workflow model uses an explicit visitor pattern for some utility functions.  The switch object generated by EMF can be used as a visitor and I will probably look at using the switch object instead of the explicit visitor.  There is a need for the ability to run the tasks of a workflow on a distributed system.  I will be looking at adding the ability to suspend a workflow execution and transfer it to another machine for continued execution.  Finally, as you have seen from this tutorial, composing a workflow with the generated EMF editor is painful and a custom, structured, editor would make this easier.  Ultimately, I would like to have a graphical editor for visualizing and composing a workflow.  If there is any interest in contributing to this project, please contact me.

I’ve been learning how to render graphics in an Eclipse view using OpenGL by putting together (hacking) bits and pieces from various articles I’ve found on the web.  I have enough working to share what I’ve learned and show you how to natively draw basic 2D graphics.  The end result will look like this …

SWT provides a GLCanvas widget for displaying graphics rendered using OpenGL but does not provide the JNI code that interfaces to the OpenGL library to actually draw the graphics.  LWJGL is a JNI library that interfaces to OpenGL and can be installed as an Eclipse bundle from the LWJGL update site.  Another option is to write your own JNI to interface to OpenGL and do the rendering natively.  I have chosen the later path since LWJGL is not available for all platforms and I had a use-case where I needed to interface to an existing C library to retrieve the data to be rendered.  Writing the JNI is not all that hard as there are only a couple of functions that are needed to do basic rendering.

Let’s start by creating a new C++ project called com.example.opengl.native.  Set the Project type to Shared Library -> Empty Project and Toolchains to MacOSX GCC.

After the project is created, bring up the project properties.  We need to tell the linker where to fine the OpenGL library, and the compiler where to find the JNI and OpenGL headers.  Navigate to the C/C++ Build -> Settings section and under MacOS X C++ Linker -> Miscellaneous settings, add -framework OpenGL to the Linker flags.  The -framework option is a OS X specific GCC option that tells the linker which OS X frameworks (shared libraries) to link against.  If you are not using OS X, then add the appropriate -L and -l settings for your platform under the Libraries section.

Next, in the GCC C++ Compiler -> Directories settings add /System/Library/Frameworks/JavaVM.framework/Headers and /System/Library/Frameworks/OpenGL.framework as part of the include paths.  For other platforms add the appropriate directories containing the JRE and OpenGL header files.

Finally, switch to the Build Artifact tab and change the Artifact name to opengl and the Artifact extension to jnilib.  Shared libraries in OS X typically have the extension .dylib; however, JNI libraries have a special .jnilib extension.  For other platforms, the default shared library extension is probably fine for JNI (.so for Linux as an example).

Now, let’s create a plug-in project called com.example.opengl.  You do not need to create an activator for this bundle.  First, we are going to create a class to hold the native functions that interface to OpenGL.

package com.example.opengl;

public class OpenGL
{
	static
	{
		System.loadLibrary("opengl");
	}

	public static native void glClearColor(float red, float green, float blue, float alpha);
	public static native void glOrtho(double left, double right, double bottom, double top, double near, double far);
	public static native void glTranslatef(float x, float y, float z);
	public static native void glViewport(int x, int y, int width, int height);

	public static native void init2D();
}

Once we have the native functions declared, we need to create the corresponding header (.h) file in the C++ project using the javah program that comes with the JDK.  You can do this right from Eclipse by creating an external program launch configuration.  Set up the launch configuration on the Main tab as follows:

• Name: OpenGL JNI
• Location: ${system_path:javah}
• Working directory: ${workspace_loc:com.example.opengl.native}
• Arguments: -classpath ${workspace_loc:com.example.opengl/bin} com.example.opengl.OpenGL

On the Refresh tab, select Specific resources, click Specify Resources… and check com.example.opengl.native.  This will cause the C++ project to be refreshed after the header file is created.

Finally, click Run to execute javah and place the header file in the C++ project.  If you expand the C++ project in the Project Explorer, you will see that the header file com_example_opengl_OpenGL.h was created.  In the C++ project create a source file named com_example_opengl_OpenGL.cpp.

#include "com_example_opengl_OpenGL.h"
#include "gl.h"

void JNICALL Java_com_example_opengl_OpenGL_glClearColor(JNIEnv* env, jclass clazz, jfloat red, jfloat green, jfloat blue, jfloat alpha)
{
  glClearColor(red, green, blue, alpha);
}

void JNICALL Java_com_example_opengl_OpenGL_glOrtho(JNIEnv* env, jclass clazz, jdouble left, jdouble right, jdouble bottom, jdouble top, jdouble near, jdouble far)
{
  glMatrixMode (GL_PROJECTION);
  glLoadIdentity();
  glOrtho(left, right, bottom, top, near, far);
  glMatrixMode (GL_MODELVIEW);
  glLoadIdentity();
}

void JNICALL Java_com_example_opengl_OpenGL_glTranslatef(JNIEnv* env, jclass clazz, jfloat x, jfloat y, jfloat z)
{
  glTranslatef(x, y, z);
}

void JNICALL Java_com_example_opengl_OpenGL_glViewport(JNIEnv* env, jclass clazz, jint x, jint y, jint width, jint height)
{
  glViewport(x, y, width, height);
}

void JNICALL Java_com_example_opengl_OpenGL_init2D(JNIEnv* env, jclass clazz)
{
  glDisable(GL_DEPTH_TEST);
}

As you can see, the implementation of the JNI is almost a 1:1 mapping to the OpenGL API. I did a little extra work in glOrtho() which you could break out into separate functions if you prefer.  Now, let’s create the native rendering engine to draw a rectangle in OpenGL.

package com.example.opengl;

public class RenderEngine
{
	public native void draw();
}

Just like you did for the OpenGL class, create an external program launch configuration to run javah and create the header file in the C++ project.  Set up the launch configuration on the Main tab as follows:

• Name: RenderEngine JNI
• Location: ${system_path:javah}
• Working directory: ${workspace_loc:com.example.opengl.native}
• Arguments: -classpath ${workspace_loc:com.example.opengl/bin} com.example.opengl.RenderEngine

Click Run and the com_example_opengl_RenderEngine.h header file will be generated in the C++ project.  Switch to the C++ project and implement the draw() function by creating the source file com_example_opengl_RenderEngine.cpp. The implementation draws a series of lines to form a rectangle. I’ll explain the negative y axis in a minute.  This is all of the native code so you can build the C++ project which will result in a libopengl.jnilib in the Debug folder.

#include "com_example_opengl_RenderEngine.h"
#include "gl.h"

void JNICALL Java_com_example_opengl_RenderEngine_draw(JNIEnv* env, jobject object)
{
  glClear(GL_COLOR_BUFFER_BIT);
  glColor3ub(255, 255, 255);
  glBegin(GL_LINE_LOOP);
  {
    glVertex2d(10, -10);
    glVertex2d(150, -10);
    glVertex2d(150, -40);
    glVertex2d(10, -40);
  }
  glEnd();
}

Now that we have code that interfaces to OpenGL and draws a rectangle, let’s put it all together in an Eclipse view. In the Java plug-in project, create a new extension selecting org.eclipse.ui.views as the extension point. Set the following fields in the extension:

• id: com.example.opengl.view
• class: com.example.opengl.OpenGLView
• name: OpenGL

Implement the OpenGLView as:

package com.example.opengl;

import org.eclipse.swt.SWT;
import org.eclipse.swt.events.ControlAdapter;
import org.eclipse.swt.events.ControlEvent;
import org.eclipse.swt.events.SelectionAdapter;
import org.eclipse.swt.events.SelectionEvent;
import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.opengl.GLCanvas;
import org.eclipse.swt.opengl.GLData;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Display;
import org.eclipse.ui.part.ViewPart;

public class OpenGLView extends ViewPart
{
	@Override
	public void createPartControl(Composite parent)
	{
		parent.setLayout(new FillLayout());
		GLData glData = new GLData();
		glData.doubleBuffer = true;
		canvas = new GLCanvas(parent, SWT.H_SCROLL | SWT.V_SCROLL, glData);
		canvas.getHorizontalBar().setMaximum(2000);
		canvas.getVerticalBar().setMaximum(2000);

		renderEngine = new RenderEngine();

		Display.getDefault().asyncExec(new Runnable()
		{
			public void run()
			{
				canvas.setCurrent();
				OpenGL.init2D();
				OpenGL.glClearColor(0.0f, 0.0f, 0.0f, 0.0f);
			}
		});

		canvas.addControlListener(new ControlAdapter()
		{

			@Override
			public void controlResized(ControlEvent e)
			{
				redraw();
			}
		});

		canvas.getHorizontalBar().addSelectionListener(new SelectionAdapter()
		{
			@Override
			public void widgetSelected(SelectionEvent e)
			{
				redraw();
			}
		});

		canvas.getVerticalBar().addSelectionListener(new SelectionAdapter()
		{
			@Override
			public void widgetSelected(SelectionEvent e)
			{
				redraw();
			}
		});
	}

	@Override
	public void setFocus()
	{
		canvas.setFocus();
	}

	private void redraw()
	{
		Display.getDefault().asyncExec(new Runnable()
		{
			public void run()
			{
				Rectangle bounds = canvas.getClientArea();
				canvas.setCurrent();
				int xOffset = canvas.getHorizontalBar().getSelection();
				int yOffset = canvas.getVerticalBar().getSelection();
				OpenGL.glViewport(bounds.x, bounds.y, bounds.width, bounds.height);
				OpenGL.glOrtho(bounds.x + xOffset, bounds.width + xOffset, -bounds.height - yOffset, bounds.y - yOffset, 0.0, 1.0);
				OpenGL.glTranslatef(0.375f, 0.375f, 0.0f);
				renderEngine.draw();
				canvas.swapBuffers();
			}
		});
	}

	private GLCanvas canvas;
	private RenderEngine renderEngine;
}

Notice that all of the calls to OpenGL are made inside a Display.getDefault().asyncExec() call. Why is this necessary when the code is already running in the UI thread? This is the one thing that I don’t understand in this example. If anyone has an explanation, please comment and I’ll update the entry. The call to OpenGL.glViewport() is only necessary when the view is resized – it was just easier to have one redraw() function.  The call to OpenGL.glOrtho() does most of the interesting work.  It sets the orthographic projection of the 3D space into 2D space which translates to pan, zoom, and the axes origin and orientation in 2D.  The arguments to the function are: left, right, bottom, top, near, and far.  I will discuss each of the arguments in detail, but first, a word on the axes origin and orientation.

OpenGL by default orients the axes with positive x to the right, negative x to the left, positive y up, negative y down, positive z out of the display, and negative z into the display.  By specifying positive or negative values for the arguments to glOrtho(), you can change the orientation of the axes.  The absolute values of the arguments specify the location of the origin.  I’ve set the axes origin to be the upper left corder of the canvas (view), and it is oriented such that positive x is to the right and negative y is down.  It is possible to orient the axes such that positive y is down making 2D drawing match what you are used to but when I tried this, text rendered using GLUT was upside down.  Rather than trying to figure out if there was a way to flip the text, I found it much easier to draw in negative y.  I set the scale to be 1:1 in pixels, meaning that if the canvas is 1000 pixels wide, drawing at x = 1000 will draw on the right edge of the canvas.  Now, let’s look at the glOrtho() arguments:

Left: bounds.x + xOffset

This argument sets the left clipping plane which effectively sets the origin of the x axis relative to the left edge of the viewport.  The xOffset takes into account the position of the horizontal scrollbar.  If the scrollbar is all the way to the left, then you will see what was drawn starting at x = 0 and extending into positive x.

Right: bounds.width + xOffset

This argument sets the right clipping plane which effectively sets the x scale relative to the viewport.  The xOffset takes into account the position of the horizontal scrollbar so that the scale doesn’t change when you pan.  If the scrollbar is all the way to the left, then you will see what was drawn from x = 0 to x = bounds.width.

Bottom: -bounds.height – yOffset

This argument sets the bottom clipping plane which effectively sets the y scale relative to the viewport.  The yOffset takes into account the position of the vertical scrollbar so that the scale doesn’t change when you pan.  If the scrollbar is all the way to the top, then you will see what was drawn from y = 0 to y = -bounds.height.

Top: bounds.y – yOffset

This argument sets the top clipping plane which effectively sets the origin of the y axis relative to the top edge of the viewport.  The yOffset takes into account the position of the vertical scrollbar.  If the scrollbar is all the way to the top, then you will see what was drawn starting at y = 0 and extending into negative y.

Near: 0.0

Far: 1.0

These arguments set the values of the near and far clipping planes.  Since the z axis is not used in 2D, the examples I found all set the near clipping plane to 0.0, and the fat clipping plane to 1.0.

As you move the scrollbar to the right, both the left and right clipping planes move which pans the drawn area in the x axis.  As you move the scrollbar to the bottom, both the top and bottom clipping planes move which pans the drawn area in the y axis.  One thing I have not done in this example is to take into account the size of the scrollbar thumb.  You may have to adjust the right and bottom arguments to glOrtho() taking into account scrollbar.getThumb().

The call to OpenGL.glTranslatef(0.375f, 0.375f, 0.0f) is a “trick” necessary to make your drawing pixel accurate.  Try drawing a line from (0, -10) to (10, -10) and a line from (0, -20) to (0, -30) without the call to glTranslate().  The result will not be what you expect.

Before we can launch the Eclipse runtime workbench, we need to hook the JNI library into the plug-in.  We are going to bundle the native library with the plug-in so that it can be delivered as a single unit. In the plug-in project, create a lib folder at the root of the project.  Copy the libopengl.jnilib file from the Debug folder in the C++ project to the lib folder in the plug-in project.  Edit the build.properties to include the newly created lib folder along with its contents.  Finally, edit the MANIFEST.MF of the plug-in project and using the source tab of the editor, add the line:

Bundle-NativeCode: lib/libopengl.jnilib; osname=macosx; processor=x86

This tells the class loader where to find the native library when System.loadLibrary() is called.  Now, we can create an Eclipse Application launch configuration to run the runtime workbench.  You can use the defaults for the launch configuration.  After you launch the runtime workbench, select Window -> Show View -> Other… and under the Other category, select the OpenGL view and click OK.  You should see the view with a white rectangle drawn on a black background just like the first screenshot above.

Rational Team Concert 2.0 has been released. With a little work, you can get the client running on Eclipse 3.5 and the server running on Mac OS X.

Server

The Jazz team does not officially support running the server on OS X, and a download that runs on OS X out-of-the-box is not available.  With a couple of minor modifications, the Linux server download will run on OS X just fine.

1. Download the Express C Server for Linux.
2. Unzip the download
3. Launch the Terminal
4. cd jazz/server
5. rm -rf jre (the Linux JRE is obviously not needed on OS X)
6. Edit tomcat/conf/server.xml.  You need to modify the Connector specification for port 9443.  Search for SSL_TLS and change it to TLS.  Also change the next line from IbmX509 to SunX509.  The resulting Connector specification should look like:

<Connector port="9443"
               connectionTimeout="20000"
               maxHttpHeaderSize="8192"
               maxThreads="150"
               minSpareThreads="25"
               maxSpareThreads="75"
               enableLookups="false"
               disableUploadTimeout="true"
               acceptCount="100"
               scheme="https"
               secure="true"
               clientAuth="false"
               keystoreFile="ibm-team-ssl.keystore"
               keystorePass="ibm-team"
               sslProtocol="TLS"
			   algorithm="SunX509"
			   URIEncoding="UTF-8" />

7. Edit server.startup and server.shutdown changing JRE_HOME from `pwd`/jre to /System/Library/Frameworks/JavaVM.framework/Home
8. While editing server.startup add -XX:MaxPermSize=256m to JAVA_OPTS
9. Launch the server ./server.startup

If you want to make sure the server started correctly, you can tail -f tomcat/logs/catalina.out and watch the server startup.  If you see any exceptions thrown, something went wrong.  If all goes well, the last message you see in the log should be:

INFO: Server startup in xxxxx ms

To get started right away, launch Safari and point it to https://localhost:9443/jazz login with User: ADMIN and Password: ADMIN.  You can use this admin account to create a personalized account.  Don’t forget to give yourself a Developer license.

Client

These instructions are not specific to Mac OS X – they should work for any OS.

The Jazz team does support a Mac OS X Client as an incubator project, but the client is based on Eclipse 3.4.  You can download the client and get the jazz bundles to work in an Eclipse 3.5 environment.   The Jazz client has dependencies on the following features:

• EMF, XSD, SDO
• GEF
• DTP

With the exception of SDO, all of the features can be installed from the Galileo update site.  To get SDO, add the EMF releases update site and install the SDO runtime from the EMF 2.4.2 release.

From the downloaded client, move all of the sub-folders in jazz/client/eclipse/jazz to your Eclipse 3.5 dropins folder.  You could use P2 to install the contents of those sub-folders; however, you must manually check every bundle to be installed.  I’d rather spend 10 seconds doing a drag-and-drop rather than 15 minutes checking checkboxes.

After you launch the client, you should be able to open the Team Artifacts view and create a connection to the repository at https://localhost:9443/jazz

Next Steps

See the Jazz web site for tutorials on getting started.

Update: Added -XX:MaxPermSize=256m to the server instructions

My last post on OSGi services showed how you can dynamically configure OSGi services using the ConfigurationAdmin service.  I used an example where I configured a service to create a JDBC connection.  JDBC connections are often made on a server, and it would be nice to be able to do your configuration remotely.  This post will show you how you can use RFC 119 to make remote OSGi service calls to configure the JDBC connection on a server.

There are two implementations of RFC 119: Apache CXF, and ECF.  I’m using ECF for this example.  This example also uses Bonjour (Zeroconf) for service discovery.  This means that the client and server must be running on the same local subnet for the client to discover the services advertised by the server.  ECF also supports SLP for service discovery, but like Bonjour is limited to the local subnet.  ECF allows you to plug in your own discovery provider, and I have done just that to support discovery across a WAN.  Look for a future blog post describing how to create your own ECF discovery provider.

Service Interface

Lets start by creating our remote service interface:

1. Create a new plug-in project com.example.database.admin
2. Create a new interface IDatabaseAdminService

package com.example.database.admin;

import java.util.Dictionary;

public interface IDatabaseAdminService
{
	public void createConnection(Dictionary<String, String> connectionConfig);
}

Service Implementation

Create an implementation of IDatabaseAdminService. The implementation creates a Configuration using the ConfigurationAdmin service.

package com.example.database;

import java.io.IOException;
import java.util.Dictionary;

import org.osgi.service.cm.Configuration;
import org.osgi.service.cm.ConfigurationAdmin;

import com.example.database.admin.IDatabaseAdminService;

public class DatabaseAdminService implements IDatabaseAdminService
{
	public synchronized void createConnection(Dictionary<String, String> connectionConfig)
	{
		try
		{
			Configuration config = null;

			if (configAdmin != null)
				config = configAdmin.createFactoryConfiguration("com.example.database.connection", null);

			if (config != null)
				config.update(connectionConfig);
		}
		catch (IOException e)
		{
			e.printStackTrace();
		}
	}

	protected synchronized void bind(ConfigurationAdmin configAdmin)
	{
		this.configAdmin = configAdmin;
	}

	protected synchronized void unbind(ConfigurationAdmin configAdmin)
	{
		if (this.configAdmin == configAdmin)
			this.configAdmin = null;
	}

	private ConfigurationAdmin configAdmin;
}

Declare the Admin Service

Now that we have a service, let’s declare it:

1. Create a new Component Definition
2. Set File name: admin.xml
3. Set name: com.example.database.admin
4. Set Class: com.example.database.DatabaseAdminService

Using the Component Definition editor, we need to set a service property osgi.remote.interfaces=*.  This property tells the RFC 119 implementation to make all declared interfaces available remotely.

Next, on the services tab, add a dependency on the ConfigurationAdmin service, and declare the IDatabaseAdminService.  Don’t for get to set the bind and unbind functions on the referenced ConfigurationAdmin service.

Initialize the ECF Container

ECF does much more than implement RFC 119, so in order to use distributed services, you must create an instance of the ecf.r_osgi.peer container.  This should be done in its own bundle since it is necessary on both the client and server.

1. Create a new Plug-in Project
2. Create an Activator for the bundle

package com.example.services.init;

import org.eclipse.ecf.core.ContainerCreateException;
import org.eclipse.ecf.core.IContainer;
import org.eclipse.ecf.core.IContainerManager;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.util.tracker.ServiceTracker;
import org.osgi.util.tracker.ServiceTrackerCustomizer;

/**
 * The activator class controls the plug-in life cycle
 */
public class Activator implements BundleActivator
{
	public void start(final BundleContext context) throws Exception
	{
		containerManagerTracker = new ServiceTracker(context, IContainerManager.class.getName(), new ServiceTrackerCustomizer()
		{
			public void removedService(ServiceReference reference, Object service)
			{
				if (container != null)
					container.disconnect();

				container = null;
			}

			public void modifiedService(ServiceReference reference, Object service)
			{}

			public Object addingService(ServiceReference reference)
			{
				try
				{
					IContainerManager containerManager = (IContainerManager) context.getService(reference);
					container = containerManager.getContainerFactory().createContainer("ecf.r_osgi.peer");
					return containerManager;
				}
				catch (ContainerCreateException e)
				{
					e.printStackTrace();
					return null;
				}
			}
		});

		containerManagerTracker.open();
	}

	public void stop(BundleContext context) throws Exception
	{
		containerManagerTracker.close();

		if (container != null)
			container.dispose();
	}

	private ServiceTracker containerManagerTracker;
	private IContainer container;
}

Launch Server

You can launch the server now, or wait until you have written the client code.  To launch the server:

1. Create a new OSGi Framework launch configuration
2. Click Deselect All
3. Uncheck Include optional dependencies when computing required bundles
4. Uncheck Add new workspace bundles to this launch configuratin automatically
5. Check com.example.database
6. Check com.example.database.admin
7. Check com.example.services.init
8. Check ch.ethz.iks.r_osgi.remote
9. Check org.eclipse.ecf.discovery
10. Check org.eclipse.ecf.osgi.services
11. Check org.eclipse.ecf.osgi.services.discovery
12. Check org.eclipse.ecf.osgi.services.distribution
13. Check org.eclipse.ecf.provider
14. Check org.eclipse.ecf.provider.jmdns
15. Check org.eclipse.ecf.provider.r_osgi
16. Check org.eclipse.ecf.remoteservice
17. Check org.eclipse.equinox.cm
18. Check org.eclipse.equinox.ds
19. Click Add Required Bundles
20. Set the Start Level of org.eclipse.equinox.ds to 5
21. Set Auto-Start to true on org.eclipse.ecf.osgi.*
22. Set Auto-Start to true on org.eclipse.ecf.provider.jmdns
23. Set Auto-Start to true on org.eclipse.equinox.cm
24. Set Auto-Start to true on org.eclipse.equinox.ds

You normally should not set the start level of org.eclipse.equinox.ds.  However, there is a start order dependency bug in ECF that requires your services to be registered after the ecf.r_osgi.peer container, and a bug in declarative services that requires DS to start after CM, so the easiest workaround is to set the start level of DS to 5 with a default start level of 4.  Your launch configuration should look something like:

After you launch the server, issue the command services (objectClass=com.example.database.admin.IDatabaseService).  You should see the service listed twice.  Note that there are not really two instances of the service running.  One is a proxy created by ECF to handle the remote calls.

Client

Now we need to create the client code that will call the remote service.  To illustrate the power of RFC 119, let’s create the client code as a declared service itself that dynamically binds to the remote service.

1. Create a new plug-in project com.example.database.client
2. Check Activate this plug-in when one of its classes is loaded
3. Create a new folder OSGI-INF
4. Create a new Component Definition
5. Create a new ClientAdmin class
6. Declare a dependency on IDatabaseAdminService

Don’t forget to specify the bind and unbind functions for the referenced service.

Here is the AdminClient:

package com.example.database.client;

import java.util.Hashtable;

import org.osgi.service.component.ComponentContext;

import com.example.database.admin.IDatabaseAdminService;

public class AdminClient
{
	protected synchronized void activate(ComponentContext context)
	{
		if(adminService == null)
			return;

		Hashtable<String, String> properties = new Hashtable<String, String>();
		properties.put("database.id", "example");
		properties.put("database", "junit");
		properties.put("user", "");
		properties.put("password", "");
		properties.put("create", "create");

		adminService.createConnection(properties);
		System.out.println("Database connection created");
	}

	protected synchronized void bind(IDatabaseAdminService adminService)
	{
		this.adminService = adminService;
	}

	protected synchronized void unbind(IDatabaseAdminService adminService)
	{
		if(this.adminService == adminService)
			this.adminService = null;
	}

	private IDatabaseAdminService adminService;
}

Launch Client

We can now launch the client:

1. Clone the Server launch configuration
2. Uncheck com.example.database
3. Check com.example.database.client

After launching the client and seeing “Database connection created” print to the console, switch over to the server console and type: services (objectClass=com.example.database.IDatabaseConnectionService) and you will see that the service was configured by the client and started.

What has happened here?  When the client started, ECF discovered the service advertised by the server and registered a proxy as if it were a local OSGi service.  The declarative services bundle saw the service and recognized that it was required by the client component.  The service proxy was dynamically bound to the client component by calling bind(IDatabaseAdminService).  The client service was then activated by the declarative services bundle by calling activate(ComponentContext).  The client then created a configuration and called IDatabaseService.createConnection(Dictionary<String, String>) which made a remote call to the service running on the server.  The server side service created a Configuration using the ConfigurationAdmin service.  The configuration of the service then caused the declarative services bundle on the server to create an instance of the IDatabaseConnectionService.  Pretty cool!

Update: fixed a cut/paste problem with the source code.

Update 8/23/09: There is a bug in ECF 3.0 that prevents more than one remote service from being discovered.  You may still use ECF 3.0, but will need to check out org.eclipse.ecf.provider.r_osgi from CVS to pick up the fix.  This fix will be released in ECF 3.1

My EMF Workflow Model is starting to take shape.  One of the next features I’d like to add is to make it easier to create and configure a workflow.  I was thinking it would be nice if the configuration editor was configurable without having to write a lot (if any) code.

I started playing around with the idea of modeling SWT with EMF, and it actually seems to work nicely.  I’ve modeled about half of the SWT widgets and all of the layouts in EMF.  This screencast shows an Eclipse view in which the contents are created from an EMF model, then I change the model and refresh the view to reflect the updated model.  The next step will be to figure out how to model databindings and connect them to a EMF Workflow Model.

If you haven’t seen the Google Wave announcement, you need to crawl out of your cave and watch the demo.  This is by far the most impressive communication and collaboration tool I have ever seen.  Say good-bye to email, instant messaging, newsgroups, forums, wikis, and blogs as we know them.  All of these technologies are fundamentally a way to communicate and collaborate with others, and all have their strengths and weaknesses.  Wave seems to take all of the strengths of these tools and combines them into a seamless system.

One Wave to rule them all, One Wave to find them, One Wave to bring them all and in the darkness bind them.

Two questions came to mind as I watched the demo in awe:

1. How can the Eclipse community use wave to better collaborate?
2. How can we integrate Wave into Eclipse?

Imagine if the Eclipse documentation were a collaborative wave document.  Developers could contribute additional documentation, code examples, etc, and that information would be updated live for other developers.  Questions on newsgroups could be easily incorporated into the documentation, or into a FAQ.  Bugs could be opened from a newsgroup question by simply highlighting text and clicking a button.  I think the Wave protocols should be integrated into ECF, and Eclipse views and editors could be used to display and edit the Wave content.  The possibilities seem endless.

Most of all, I’d like to see some lively discussion by the Eclipse community on your ideas.

I’m creating OSGi services and found the need to create one or more instances of a service that was registered with user configured parameters.  It’s fairly straightforward to do this with the ConfigurationAdmin service, a ManagedServiceFactory and context.registerService(), but I’ve recently become a declarative services convert and wanted to do all of this with declarative services.  It turns out that you still use the ConfigurationAdmin service, just not the ManagedServiceFactory. In this post, I will demonstrate how to create a dynamically configured declarative service.

Example Use-case

Let’s say you are deploying an OSGi based server at multiple sites and your bundles need to access one or more databases using JDBC.  You create an OSGi service called DatabaseConnectionService that returns a JDBC Connection.  To create the connection to the database, you need configuration information typically consisting of: hostname, port number, database, user id, and password.  Since this information can change, and will vary from site to site where your server is deployed, the configuration information needs to be dynamically updatable and persistable.

Development Environment

You will need Eclipse 3.5, Equinox, and Apache Derby if you want to try this example on your own.  Create a target folder somewhere in your filesystem.  Extract the contents of the Equinox zip file into the target directory.  Create a derby folder as a child of target and extract the contents of the Derby zip into the derby folder.  The directory structure should look like:

Target platform directory structure

Launch Eclipse 3.5 and select Preferences -> Plug-in Development -> Target Platform.  We need to add Equinox and Derby to our target platform.  Select Running Platform and click Edit… Add the Equinox and Derby folders to your target platform.  Your target platform should look like:

Target Definition

Unit Test

Create a new plug-in project and make sure the option is checked to generate an Activator.  In the Manifest editor, check Activate this plug-in when one of its classes is loaded.  Add org.junit4 to your required bundles and org.osgi.service.cm to your imported packages.  [Let's not debate require bundle vs import package ... just set up your dependencies however you like to get the junit tests to build.]

The unit test first gets the ConfigurationAdmin service from the bundle context.  I’ve taken a short-cut with my unit test for this example, and I’m relying on the fact that the ConfigurationAdmin service will be started before the unit test.  You should not rely on bundle start order in your production code.  Once you have the ConfigurationAdmin service, create a configuration and set the properties for your declarative service.  After you update the properties on the configuration, you will then have to wait for the service to be created.  Make sure you include a timeout so your unit test doesn’t hang forever in the event that the service is not started.  Your unit test will contain a compile error until you create the service interface.

package com.example.database.junit;

import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.CoreMatchers.notNullValue;
import static org.junit.Assert.assertThat;

import java.io.IOException;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.Hashtable;

import org.junit.Test;
import org.osgi.framework.BundleContext;
import org.osgi.framework.InvalidSyntaxException;
import org.osgi.framework.ServiceReference;
import org.osgi.service.cm.Configuration;
import org.osgi.service.cm.ConfigurationAdmin;
import org.osgi.util.tracker.ServiceTracker;

import com.example.database.IDatabaseConnectionService;

public class TestDatabaseConnectionService
{
	@Test
	public void testCreateConnection() throws SQLException, IOException, InvalidSyntaxException, InterruptedException
	{
		BundleContext context = Activator.getDefault().getBundle().getBundleContext();

		ServiceReference configAdminReference = context.getServiceReference(ConfigurationAdmin.class.getName());
		assertThat(configAdminReference, is(notNullValue()));
		ConfigurationAdmin configAdmin = (ConfigurationAdmin) context.getService(configAdminReference);
		assertThat(configAdmin, is(notNullValue()));

		Configuration config = configAdmin.createFactoryConfiguration("com.example.database.connection", null);
		assertThat(config, is(notNullValue()));

		Hashtable<String, Object> properties = new Hashtable<String, Object>();
		properties.put("database.id", "example");
		properties.put("database", "junit");
		properties.put("user", "");
		properties.put("password", "");
		properties.put("create", "create");
		config.update(properties);

		ServiceTracker connectionServiceTracker = new ServiceTracker(context, IDatabaseConnectionService.class.getName(), null);
		connectionServiceTracker.open();
		IDatabaseConnectionService connectionService = (IDatabaseConnectionService) connectionServiceTracker.waitForService(1000);
		assertThat(connectionService, is(notNullValue()));
		Connection connection = connectionService.createConnection();
		assertThat(connection, is(notNullValue()));
		connection.close();
	}
}

Service Interface

Create a new plug-in project com.example.database and add the following interface:

package com.example.database;

import java.sql.Connection;
import java.sql.SQLException;

public interface IDatabaseConnectionService
{
	Connection createConnection() throws SQLException;
}

Edit your junit plug-in manifest to include a dependency on com.example.database.

Launch Configuration

Create a JUnit Plug-in Test launch configuration.  Make sure your test is selected, and that the Test runner is set to JUnit 4.

Launch Configuration (Test tab)

You will also need to set up the included plug-ins.

1. Select the Plug-ins tab
2. Select Launch with: plug-ins selected below only
3. Click Deselect All
4. Uncheck Include optional dependencies when computing required plug-ins
5. Uncheck Add new workspace plug-ins to this launch configuration automatically
6. Check com.example.database
7. Check com.example.database.junit
8. Check org.eclipse.equinox.cm
9. Check org.eclipse.equinox.ds
10. Click Add Required Plug-ins
11. Set the Start Level on org.eclipse.equinox.cm to 3 and Auto Start to true

Launch Configuration (Plug-ins tab)

The start level of the ConfigurationAdmin bundle must be set to something lower than the declarative services bundle because of bug 276003.  Run your junit test, and it should fail on line 62.

Service Implementation

Now, lets create a real service that constructs a JDBC connection to derby.

package com.example.database;

import java.sql.Connection;
import java.sql.SQLException;
import java.util.Dictionary;

import org.apache.derby.jdbc.EmbeddedDataSource;
import org.osgi.service.component.ComponentContext;

public class DatabaseConnectionService implements IDatabaseConnectionService
{
	public Connection createConnection() throws SQLException
	{
		EmbeddedDataSource dataSource = new EmbeddedDataSource();
		dataSource.setDataSourceName(id);
		dataSource.setDatabaseName(database);
		dataSource.setUser(user);
		dataSource.setPassword(password);
		dataSource.setCreateDatabase(create);
		return dataSource.getConnection();
	}

	@SuppressWarnings("unchecked")
	protected void activate(ComponentContext context)
	{
		Dictionary<String, Object> properties = context.getProperties();
		id = (String) properties.get("database.id");
		database = (String) properties.get("database");
		user = (String) properties.get("user");
		password = (String) properties.get("password");
		create = (String) properties.get("create");
	}

	private String id;
	private String database;
	private String user;
	private String password;
	private String create;
}

Declare The Service

You are now ready to declare your service. Eclipse 3.5 contains new tooling for declarative services that makes this a snap.

1. Right-click on your project and select New -> Folder
2. Create a folder called OSGI-INF
3. Right-click on the OSGI-INF folder and select New -> Other
4. Select Plug-in Development -> Component Declaration
5. Click Next
6. Choose a file name such as component.xml
7. Give your component a globally unique name such as com.example.database.connection
8. For the Class, click Browse
9. Choose DatabaseConnectionService
10. Click Finish

The component definition editor will appear allowing you to set additional parameters and options. Set the Configuration Policy to require. This policy tells the service manager to not start the service component until it has a configuration from the ConfigurationAdmin service.  Check the options: This component is enabled when started and This component is immediately activated.

Component Options

On the Services tab of the component editor, add the service interface as a provided service:

Component Services

If you re-run your junit test, it should now pass.  If you want to dig a little deeper, set a breakpoint on line 55 of TestDatabaseConnectionService.java and run under the debugger.  When your breakpoint is triggered, switch to the console view and type in services (objectClass=com.example.database.IDatabaseConnectionService) and you will get information on your registered service including it’s configuration parameters.

OSGi Console

That’s how you dynamically configure a declarative service!

Update: Simplified the unit test by using ServiceTracker.waitForService().