Service Activator Toolkit

Working with Properties Files

Bundles, just like any Java code, sometimes wish to work with properties. While it is always possible to define System properties when the Java VM is started using the Java VM argument -D, this is not convenient for bundles that are loaded and unloaded without restarting the Java VM.

Another approach is for a bundle to add its properties to the System properties when it starts, and to remove its properties from the System properties when it stops. The BaseBundleActivator class does not do this for you, but does provide API that makes it easier for a bundle to do exactly this.

The BaseBundleActivator implements the hook method getPropertiesInputStream() that should be overridden by a bundle that wishes to load properties. The method getPropertiesInputStream() returns an InputStream on the bundle's properties that can then be loaded into the System properties.
The BaseBundleActivator class provides the following query methods for getting an InputStream on a properties file.
- Query API
  - InputStream getFilePropertiesInputStream() throws IOException
  - InputStream getFilePropertiesInputStream(String) throws IOException
  - InputStream getResourcePropertiesInputStream() throws IOException
  - InputStream getResourcePropertiesInputStream(String) throws IOException
The method getFilePropertiesInputStream() returns an InputStream on a properties file that resides in the Java VM's current directory and has a filename that matches the bundle's Bundle-SymbolicName. For example, if the bundle's Bundle-SymbolicName is com.ibm.navigation, this method will return an InputStream on the properties file com.ibm.navigation.properties.
The method getFilePropertiesInputStream(String) returns an InputStream on a properties file that resides in the Java VM's current directory with a name that matches the specified name.
The method getResourcePropertiesInputStream() returns an InputStream on a properties file that resides as a Java resource in the package containing the bundle's activator. Just like the file system equivalent, this method searches for a Java resource with a filename that matches the bundle's Bundle-SymbolicName.
The method getResourcePropertiesInputStream(String) returns an InputStream on a properties file that resides as a Java resource in the package containing the bundle's activator. Just like the file system equivalent, this method searches for a Java resource with a name that matches the specified name.

The following examples show how to add properties from a package resource using both the default name and a specified name.

protected InputStream getPropertiesInputStream() throws IOException {
  return getResourcePropertiesInputStream();  // Navigation.properties
}

protected InputStream getPropertiesInputStream() throws IOException {
  return getResourcePropertiesInputStream("nav.properties");
}

Once you've defined where the bundle will load its properties from, the properties are accessed using the BaseBundleActivator method getProperties(). The getProperties method lazily creates and caches the Properties() object, allowing the bundle to work with the properties however it wishes. For example, the bundle could add the properties to the System properties in its start() method and remove the properties from the System properties in its stop() method. This might be done as follows:

public class Activator extends BaseBundleActivator {
  ...
  protected InputStream getPropertiesInputStream() throws IOException {
    return getFilePropertiesInputStream();
  }

  protected void handleFailedToFindProperties(String filename) {
    // No-op: It is OK for properties to not exist.
  }

  protected void start() throws Exception {
    Properties properties = getProperties();
    Enumeration keys = properties.propertyNames();
    Map sysProps = System.getProperties();

    while (keys.hasMoreElements() == true) {
      String key = (String) keys.nextElement();
      Object value = properties.getProperty(key);
      sysProps.put(key, value);
  }

  protected void stop() throws Exception {
    Properties properties = getProperties();
    Enumeration keys = properties.propertyNames();
    Map sysProps = System.getProperties();

    while (keys.hasMoreElements() == true) {
      String key = (String) keys.nextElement();
      sysProps.remove(key);
    }
  }
}