Preferences API in NetBeans

NetBeans adopts Java Preferences API standard to be used in NetBeans to store preference and configuration data to be able to adapt to the needs of different users. NetBeans keeps this standard and enhances it slightly by providing its own preference tree in addition to default system and user roots. The purpose for this enhancement is to unify the way how persistent preference and configuration data are stored in NetBeans whereas all changes go into userdir which is the central place where also other configuration data are kept.This concept is convenient for developers or power users for running more instances of NetBeans, for debugging, for testing, for analysing structure or content of such files whenever any problems occures whereas running NetBeans with various userdirs means actually running NetBeans with different preferences. Running NetBeans with fresh userdir means actually running NetBeans with factory preset defaults.

The decision whether to use standard or enhanced NetBeans preference tree is left up to the developer.

Usage Notes

How to obtain NetBeans Preferences?

To get preference node there are two factory methods in Utilities API (org.openide.util):

NbPreferences.root() returns root preference node.
NbPreferences.forModule(class cls) returns preference node which absolute path depends whether class provided as a parameter was loaded as a part of any module or not. If so, then absolute path corresponds to slashified code name base of module. If not, then absolute path corresponds to class's package

How to verify that preferences work properly?

Layout of files on disk:

    config/Preferences/
    `-- org
        |-- apache
        |   `-- tools
        |       `-- ant
        |           `-- module.properties
        `-- netbeans
            `-- modules
                `-- derby.properties

prefs.properties is regular properties file. See:

#Thu Sep 28 18:15:22 CEST 2006
location=/tmp/location
systemHome=/tmp/systemHome

How to migrate from SystemOptions into Preferences API?

Remove registration from layer:

-     <folder name="Services"/>
-         <file name="org-netbeans-modules-derby-DerbyOptions.settings" url="DerbyOptions.settings"/>
-     </folder>

Add module dependency on Utilities API (org.openide.util with specification version >= 7.4) if necessary
Remove module dependency on Settings Options API (org.openide.options)

Remove registration of Node which was used to visualize original SystemOptions in Tools/Options

-     <folder name="Services">
-         <folder name="IDEConfiguration">
-             <folder name="ServerAndExternalToolSettings">
-                    <file name="org-netbeans-modules-derby-DerbyOptions.shadow">
-                        <attr name="originalFile" stringvalue="Services/org-netbeans-modules-derby-DerbyOptions.settings"/>
-                    </file>
-             </folder>
-         </folder>
-     </folder>

Rewrite the code not to extend SystemOption anymore
Ensure visualization in Tools/Options if still needed.
Ensure import from previous version into preferences storage
Delete associated BeanInfo if it isn't necessary anymore
Document usage of Preferences API like any other API in arch document
Run tests to verify that code after migration is working

Hints how to replace SystemOption

It is recommended to delete the whole settings class extending SystemOption and call directly Preferences API. This approach isn't convenient when except reading, writing from storage is necessary additional logic. Then following steps can be used as a hint:

Change your setting class not to extend SystemOption anymore

Either use static methods for getters and setters or replace factory method SharedClassObject.findObject by common singleton pattern:

-public class DerbyOptions extends SystemOption {
-
-    private static final long serialVersionUID = 1101894610105398924L;
+public class DerbyOptions  {
+    private static DerbyOptions INSTANCE = new DerbyOptions();

     public static DerbyOptions getDefault() {
-        return (DerbyOptions)SharedClassObject.findObject(DerbyOptions.class, true);
+        return INSTANCE;
     }

Replace all other SystemOption and SharedClassObject calls. E.g.:

+    protected final String putProperty(String key, String value, boolean notify) {
+        String retval = getPreferences().get(key, null);
+        if (value != null) {
+            NbPreferences.forModule(DerbyOptions.class).put(key, value);
+        } else {
+            NbPreferences.forModule(DerbyOptions.class).remove(key);
+        }
+        return retval;
+    }

+    protected final String getProperty(String key) {
+        return NbPreferences.forModule(DerbyOptions.class).get(key, null);
+    }

How to ensure visualization in Tools/Options?

If you need keep UI backward compatibility then the way is very easy: provide a node representing your settings class. See:


+    public static BeanNode createViewNode() throws IntrospectionException {
+        return new BeanNode(DerbyOptions.getDefault());
+    }

-    <file name="org-netbeans-modules-derby-DerbyOptions.shadow">
-        <attr name="originalFile" stringvalue="Services/org-netbeans-modules-derby-DerbyOptions.settings"/>
+    <file name="DerbyOptionsNode.instance">
+        <attr name="instanceCreate" methodvalue="org.netbeans.modules.derby.DerbyOptions.createViewNode"/>

The other way means to go a little more farther and provide and install custom options panels/categories to Options Dialog according to the Options Dialog API. The module development support in NetBeans can help by generating boilerplate code and registering the option into your layer.

How to document usage of Preferences API?

Answer properly arch questions like any other APIs. There was added new arch question related to preferences (resources-preferences). See example:

<answer id="resources-preferences">
  <api group="preferences" name="org.netbeans.modules.derby" type="export" category="private" url="">
      <table>
          <tbody>
              <tr>
                  <th>key</th>
                  <th>description</th>
                  <th>read</th>
                  <th>write</th>
              </tr>
              <tr>
                  <td>location</td>
                  <td>Derby location or an empty string if the Derby location is not set</td>
                  <td>x</td>
                  <td>x</td>
              </tr>
              <tr>
                  <td>systemHome</td>
                  <td>Derby system home or an empty string if the system home is not set</td>
                  <td>x</td>
                  <td>x</td>
              </tr>
          </tbody>
      </table>
  </api>
 </answer>

How to ensure import from previous version?

There is support for importing old serialized instances of SystemOptions into preferences storage in ide/launcher/upgrade module in package org.netbeans.upgrade.systemoptions. This infrastructure reads configuration file containing enumeration of settings files that should be imported. In simple cases there is actually no neeed to code anything, but this is rare case which may happen just when all the properties are primitive data types or String and if method writeExternal isn't overridden.

How to start? The best is to start with tests. But first you must have settings file that will be parsed and tested. Put this file among tests:

test/unit/src/org/netbeans/upgrade/systemoptions
|-- BasicTestForImport.java
|-- DerbyOptionsTest.java
|-- org-netbeans-modules-derby-DerbyOptions.settings

Then write simple test that should contain assertions what actually will be parsed and imported. See:

public class DerbyOptionsTest extends BasicTestForImport {
    public DerbyOptionsTest(String testName) {
        super(testName, "org-netbeans-modules-derby-DerbyOptions.settings");
    }    
    public void testPreferencesNodePath() throws Exception {
        assertPreferencesNodePath("/org/netbeans/modules/derby");
    }    
    public void testPropertyNames() throws Exception {
        assertPropertyNames(new String[] {
            "systemHome",
            "location"
        });
    }    
    public void testSystemHome() throws Exception {
        assertPropertyType("systemHome","java.lang.String");
        assertProperty("systemHome","/tmp/systemHome");
    }
    public void testLocation() throws Exception {
        assertPropertyType("location","java.lang.String");
        assertProperty("location","/tmp/location");
    }    
}

If the tests didn't pass then probably there is more complicated object graph serialized then you must subclass PropertyProcessor and put your own code in. (See as an example: TaskTagsProcessor and here is a test).

How to write tests that needs Preferences API?

Not persistent implementation of java.util.prefs.Preferences is installed in place of the platform-specific default implementation for running tests which is in spirit of unit testing because individual tests shouldn't interact. But if this behaviour isn't suitable then there is possible to reinstall platform-specific default implementation again:

+         public void run(final TestResult result) {
+             //just initialize Preferences before code NbTestCase
+             Preferences.userRoot();                        
+             super.run(result);
+         }