Preferences Bundle

The Preferences Bundle provides the OSGi Preferences Service which stores and provides access to the preferences properties of bundles.

Bundle Information

Bundle JAR

The JAR file of the Preferences Bundle is prefs.jar, and is located in the bundles folder.

Import

The Preferences Bundle imports the following packages:

Package Exporter Content
com.prosyst.mbs.services.db DB Bundle The DB Manager service, which is used by the Preferences Bundle to store properties in a database.
com.prosyst.util.encode ProSyst Util Bundle/
ProSyst Util Full Bundle		 The Base64 encode utility for string encoding.
com.prosyst.util.ref The log utility that forwards storage to the OSGi Log Service or to the system output.
com.prosyst.mbs.framework.event System Bundle The Event Thread utility for asynchronous event delivering and listener management.
org.osgi.service.prefs OSGi Library Bundle The interface of the OSGi Preferences Service.

Export

com.prosyst.mbs.services.prefs - Contains components intended for internal use only.

Services

Preferences Bundle registers the OSGi Preferences Service, represented by interface org.osgi.service.prefs.PreferencesService. The Preferences Bundle stores its preferences in a custom database in the DB Bundle, called "prefs_owndb".

The features of the OSGi Preferences Service are discussed in details in the OSGi Preferences Service Specification.

The figure below illustrates the usage model of the Preferences Service.

Figure 1: Preferences tree.

The code example below represents a simple bundle, that uses both interfaces, PreferencesService and Preferences. A tree like the shown above is created. The root, represents a node with the system preferences. There are two more nodes. Each of the nodes represents the preferences for a specified user. (For the example the users correspond to user1 and user2). The put(String, String) method associates the specified value with the specified key in this preference node. The string "FirstUser" is the specified value for the user1. The get(String, String)method returns the value associated with the specified key in this preference node.

By using getUsers() method, all the users could be seen, as this method returns their names as strings. 

  package test.prefs;
 
  import org.osgi.service.prefs.PreferencesService;
  import org.osgi.service.prefs.Preferences;
  import java.io.IOException;
  import org.osgi.framework.*;
 
  public class PrefsTestActivator implements BundleActivator {
    ServiceReference prefsRef;
    private static PreferencesService ps;
    
    public void start(BundleContext bc) throws BundleException {
      prefsRef = bc.getServiceReference("org.osgi.service.prefs.PreferencesService");
      PreferencesService ps = (PreferencesService) bc.getService(prefsRef);
      // creating the preferences tree 
      Preferences system = ps.getSystemPreferences();
      Preferences user1 = ps.getUserPreferences("User1");
      Preferences user2 = ps.getUserPreferences("User2");
      //specify a value and associate it with a key
      user1.put("name", "FirstUser");
      // returns the value associated with the specified key 
      user1.get("name", "user1"); 
      String [] allUsers = ps.getUsers();
      System.out.println(allUsers);
    }
 
    public void stop(BundleContext bc) {
      bc.ungetService(prefsRef);
    }
  }
Listing 1: Preferences example.

Troubleshooting

Make sure that DB Bundle is activated, before the installation the Preferences Bundle. Otherwise, a BackingStoreException will be thrown.

System Properties

The Preferences Bundle has the following system properties:

System Property Description
mbs.prefs.debug Turns on/off generation of debug information about the runtime operation of the Preferences Bundles.
mbs.prefs.console Enables printing produced debug output into the framework's text console.

To apply these properties, you should specify them in the default.prs file before framework startup. At runtime, you can use the set console command or the mConsole before the Preferences Bundle is started - otherwise, you have to restart the bundle to save the changes. For more information about using system properties, refer to the "System Properties" document from "Getting Started".

References

OSGi Bundles