Programming Knopflerfish

> cd knopflerfish/osgi/bundles
> mkdir mybundle
      

> cp knopflerfish/ant/build_example.xml build.xml
      

Set the impl.pattern and api.pattern properties to the packages that contains implementation and API code.

Depending on where you have put your new bundle, you might have to modify the path to bundlebuild.xml in the <import file="${proj.dir}/../../../ant/bundlebuild.xml"/> element at the end of the build-file.

For details on bundle generation, see knopflerfish/ant/bundlebuild.xml

<project name="mybundle" default="all">
...
<property name  = "impl.pattern"
          value = "example/mybundle/impl/**"/>
..
<property name  = "api.pattern"
          value = "example/mybundle/*"/>

      

> mkdir -p src/example/mybundle/impl
      

package example.mybundle.impl;

import org.osgi.framework.BundleActivator;

public class Activator implements BundleActivator {
  ...
  public void start(BundleContext bc) {
    ...
  }
  public void stop(BundleContext bc) {
    ...
  }
      

5. Compile the bundle.

The ant build system will automatically find the BundleActivator, imports and exports and generate a bundle manifest file.

The resulting file will be generated to knopflerfish/osgi/jars/mybundle/mybundle.jar

Intermediate build results will be placed in knopflerfish/osgi/out/mybundle

> ant
      

6. Install the bundle.

This can be done either by using the text console, dragging the bundle using the Swing desktop UI or by modifying the framework startup file init.xargs

The ant build has support for communicating to a running framework and install, start, stop, update and uninstall bundles.

Given that the consoletelnet bundle is running, you can simply use these built-in targets to handle the life cycle of the bundle.

The properties console.host, console.port, console.user and console.pwd controls the details of the console connection.

Note: requires netcomponents.jar in $ANT_HOME/lib. Needs to be separately downloaded from http://www.savarese.org/oro/downloads

> ant install

> ant start

> ant -projecthelp

public class Activator implements BundleActivator {
  ...
}

Do use normal package name conventions. One convention is to suffix the implementation parts of bundle with .impl

However, the implementation parts can theoretically have any package name you want, since the framework keeps separate name spaces for separate bundles.

// This is the not exported implementation part of a bundle
package com.acme.osgi.test.impl;

// from the bundle's API part
import com.acme.osgi.test.TestService;

public class Activator implements BundleActivator {
  TestService testService = ...
  ...
}

// Static bundle context
public class Activator implements BundleActivator {

   static BundleContext bc;

   public void start(BundleContext bc) {
     Activator.bc = bc;
     ...
   }

   public void stop(BundleContext bc) {
     Activator.bc = null; // allow for garbage collection
     ...
   }
}

public void stop(BundleContext bc) {
  Activator.bc = null;
}

// Cleanup up resources in stop method
public void stop(BundleContext bc) {
  Activator.bc = null;
  if(window != null) {
    window.setVisible(false);
    window = null;
  }
}

A more compact method than multiple interfaces, is to use anonymous inner classes.

import org.osgi.framework.BundleActivator;
import org.osgi.service.cm.ManagesService;

public class Activator
       implements BundleActivator, ManagedService {

  // implements BundleActivator
  public void start(BundleContext bc) {

    Hashtable props = new Hashtable();
    props.put("service.pid", "myfantasticpid");

    // We can register ourselves as a ManagedService,
    // This is formally OK, but a service
    // that can get this service (as a ManagedService),
    // can also call start() and stop() using
    // reflection trickery or casting. Which hardly
    // was the intention of the bundle programmer.
    bc.registerService(ManagedService.class.getName(),
                       this, props);

  }

  // implements BundleActivator
  public void stop(BundleContext bc) {
    ...
  }

  // implements ManagedService
  // should be avoided.
  public void updated(Dictionary conf) {
    ...
  }
}

public class Activator implements BundleActivator {

  public void start(BundleContext bc) {

    Hashtable props = new Hashtable();
    props.put("service.pid", "myfantasticpid");

    ManagedService mg = new ManagedService() {
      public void updated(Dictionary conf) {
        ...
      }
    };

    // BundleActivator methods now hidden
    // from outside access.
    bc.registerService(ManagedService.class.getName(),
                       mg, props);

  }
  ...
}

Nothing about threads is really specified or forbidden in the OSGi spec, so there is currently no need for any special, external thread service.

  public void start(BundleContext bc) {
    new Thread("longTaskName") {
      { start(); } // I like instance initializer blocks ;)
      public void run() {
         ...long operation
      }
    };
  }

Many external libraries, like most JNDI lookup services requires a correctly set thread context classloader. If this is not set, ClassNotFoundException, or similar might be thrown even if you have included all necessary libs.

To fix this, simple spawn a new thread in the activator and do the work from that thread. If you use the lib in any callback methods from the framework, as ServiceListener or BundleListener you should do a similar trick inside of these listeners.

It is not recommended to set the context class loader persistently on the startup thread, since that thread might not be unique for your bundle. Effects might vary depending on OSGi vendor. If you don't spawn a new thread, you must reset the context class loader before returning.

public class Activator implements BundleActivator {
   public void start(BundleContext bc) {

     final ClassLoader classLoader =
        getClass().getClassLoader();

     Thread thread = new Thread() {
       public void run() {
         Thread.currentThread()
           .setContextClassLoader(classLoader);
         ...
         // do any work that uses the context
         // class loader, like :
         context.lookup("QueueConnectionFactory");
       }
     };

     thread.start();
   }

Use the ServiceTracker if you are interested in using a single service.

  ServiceTracker logTracker =
    new ServiceTracker(bc,
                       LogService.class.getName(),
                       null);
  logTracker.open();

  // this might throw a NullPointerException
  // if the log is not available
  (LogService)logTracker
    .getService().log(LogService.LOG_INFO,
                      "Hello log");

  ...
  ServiceListener listener = new ServiceListener() {
    public void serviceChanged(ServiceEvent ev) {
     ServiceReference sr = ev.getServiceReference();

      switch(ev.getType()) {
        case ServiceEvent.REGISTERED:
          ...
          break;
        case ServiceEvent.UNREGISTERING:
          ...
         break;
      }
    }
  };

  String filter =
   "(objectclass=" + HttpService.class.getName() + ")";

  try {
    bc.addServiceListener(listener, filter);

    // get all already registered services.
    ServiceReference[] srl =
      bc.getServiceReferences(null, filter);

    for(int i = 0; srl != null && i < srl.length; i++) {
      listener.serviceChanged(
          new ServiceEvent(ServiceEvent.REGISTERED,
          srl[i]));
    }
  } catch (Exception e) {
     log.error("Failed to set up listener for http",
               e);
  }

// Get the bundle's manifest file using the
// bundle class loader
InputStream in =
  getClass()
   .getResourceAsStream("/META-INF/MANIFEST.MF");
..

 // Get the bundle's raw manifest file using an URL
 // Syntax: (jar number represents internal jars,
 // where 0 is the top level jar)
 //  "bundle://<bundle id>:<jar number><path>"
 String s =
   "bundle://" + bc.getBundle().getBundleId() + ":0" +
   "/META-INF/MANIFEST.MF";

 URL url = new URL(s);

 InputStream in = url.openStream();

 ..

This means that a bundle that has a wire from a provided capability (e.g., exported package) to another bundle requiring that capability needs to be explicitly refreshed before that capability (e.g., classes in the exported package) is released.

If you happen to have exported the package that your BundleActivator resides in, this could mean that the "old" class will be used and not the newly installed one.

Console:

 > /framework refresh

Desktop:
Bundles -> Refresh bundle packages
or CTRL + R
or press the refresh link in the wiring displayer on a capability that is pending removal on refresh.

Both of these methods uses the org.osgi.wiring.FrameworkWiring API to refresh bundles:

  // refresh all bundles
  frameworkWiring.refreshBundles(null)

1. Install all the .dlls and jars in the JRE runtime ext/ directory.
   Common installation directory:

   C:\Program Files\JavaSoft\JRE\1.3\lib\ext\
       

2. This is not enough, copy the file jmutils.dll to the JRE runtime bin/ directory.
   Common installation directory:

   C:\Program Files\JavaSoft\JRE\1.3\bin\
       

The "API"-variant of the bundle will only contain classes that is the result of compiling those java-source files that matches this pattern from the source tree.

The "IMPL"-variant of the bundle will contain classes that is the result of compiling those java-source files that matches any of the impl.pattern and impl-api.pattern.

The "ALL"-variant of the bundle will contain classes that matches any of the api.pattern, impl.pattern, impl-api.pattern, all.pattern and all-api.pattern.

The "ALL"-variant of the bundle will export classes in packages that are matched by one of api.pattern, impl-api.pattern and all-api.pattern. It will contain all classes that are matched by any of api.pattern, impl-api.pattern, impl-pattern, all-api.pattern and all.pattern.

Predefined values: ee.minimum, ee.foundation.
Default is unset.

This path is used to make other bundles and JAR-files that the bundle depends on availble to the compiler during the compilation of the bundle.

Example - make the log API available during compilation:

 <path id = "bundle.compile.path">
   <pathelement location="log_api-N.N.N.jar"/>
 </path>

The N.N.N notation in the file name tells the build system to look for and use the highest version available in the directory tree starting at ${jars.dir}. It is possible to ask for the highest version available with a fixed major revision by writing a pathelement like log_api-2.N.N.jar.