Der Umgang mit dem Preferences-API wird im Folgenden am Beispiel eines einfachen Editors beschrieben. Beim Start lädt der Editor Fensterposition, -größe und Font-Einstellungen. Der Anwender hat anschließend die Möglichkeit, diese Einstellungen zu ändern, bevor sie beim Beenden des Programms wieder zurückgeschrieben werden. Das initiale Laden der Einstellungen wird über folgenden Code realisiert:

  void setPreferences() {
    // Ermitteln des zuständigen Knotens
    Preferences prefs;
    prefs = Preferences.userNodeForPackage(getClass());
    // Setzen der Fenster-Größe (Default: 400x450)
    setSize(prefs.getInt("width", 400),
            prefs.getInt("height", 450));
    // Setzen der Position (Default: 0,0)
    setLocation(prefs.getInt("xpos", 0),
                prefs.getInt("ypos", 0));
    // Setzen des Font-Namens
    String fontName = prefs.get("font-name", "Default");
    comboFontName.setSelectedItem(fontName);
    // Setzen der Font-Größe
    int fontSize = prefs.getInt("font-size", 12);
    comboFontSize.setSelectedItem(""+fontSize);
    // Font anwenden
    editor.setFont(new Font(fontName, Font.PLAIN,
                                      fontSize));
  }

Dabei wird zunächst über die Methode userNodeForPackage(Class) ein Exemplar der Klasse Preferences ermittelt. Die Methode bekommt eine Klasse übergeben und liefert einen Einstellungsknoten zurück, in dem die Einstellungen zur übergebenen Klasse und dem gerade angemeldeten Benutzer abgelegt werden können. Durch Aufruf der Methode systemNodeForPackage(Class) kann man auf den entsprechenden Knoten im Systembereich zugreifen. Der relevante Knoten wird ausgehend vom Wurzelknoten über einen eindeutigen Pfad identifiziert. Der verwendete Pfad wird beim Aufruf der Methoden NodeForPackage(Class) automatisch aus dem vollqualifizierten Klassennamen der übergebenen Klasse ermittelt, d. h. im Beispiel wird auf den Knoten

  /de/dpunkt/prefs/SimplePrefDemo

zugegriffen, weil das Class-Exemplar der Klasse

  de.dpunkt.prefs.SimplePrefDemo

übergeben wurde. Alternativ dazu kann man einen Knoten auch direkt über seinen absoluten Pfad oder relativ zu einem anderen Knoten ermitteln. Über Preferences-Exemplare kann man anschließend Einstellungen abfragen und setzen. Im obigen Beispiel würde das bedeuten, dass man zunächst den Wurzelknoten ermittelt und anschließend über den Pfad auf den Knoten zugreifen kann. Somit würden folgende Zeilen zum selben Ergebnis führen:

  Preferences userRootNode = Preferences.userRoot();
  Preferences prefs prefs.node("/de/dpunkt/prefs/SimplePrefDemo");

Prinzipiell wird ein Knoten immer vorher angelegt, falls er zum Zeitpunkt des Zugriffs noch nicht existiert, so dass beim Aufruf stets ein Knoten zurückgeliefert wird.

Über die get()-Methode kann man anschließend auf die im Knoten gespeicherten Einstellungen zugreifen. Zusätzlich zur allgemeinen get()-Methode, die immer direkt die gespeicherte Zeichenkette zurückliefert, sind für die Rückgabe verschiedener Datentypen weitere Methoden definiert, die den Datentyp im Namen tragen. So gibt es auch die Methoden getInt(), getLong(), getFloat(), getDouble(), getBoolean() und getByteArray(). Alle diese Methoden konvertieren den gespeicherten String-Wert vor der Rückgabe in den entsprechenden Datentyp (Byte-Arrays werden hierbei intern nach Base64 codiert).

Damit ist gewährleistet, dass eine Anwendung auch dann ordnungsgemäß läuft, falls eine Einstellung noch nicht vorhanden ist, müssen bei der Abfrage Default-Werte übergeben werden. Der Default-Wert wird z. B. dann zurückgeliefert, wenn der Speicherungsmechanismus der Einstellungen nicht verfügbar ist, der Wert noch nicht angelegt wurde oder eine typisierte get()-Methode aufgerufen wird und intern ein Fehler bei der Typ-Konvertierung auftritt (z. B. Aufruf von getInt(), obwohl der gespeicherte Wert keine Zahl enthält).

Im Beispiel werden die ermittelten Einstellungen sofort in der Benutzeroberfläche eingestellt. Wenn man die Anwendung ordnungsgemäß beendet, werden die geänderten Einstellungen über einen Shutdown-Hook wieder in den Benutzerbereich zurückgeschrieben:

  void storePreferences() throws BackingStoreException {
    // Ermitteln des zuständigen Knotens
    Preferences prefs =
              Preferences.userNodeForPackage(getClass());
    // Speichern der Fenster-Position
    prefs.putInt("xpos", getLocation().x);
    prefs.putInt("ypos", getLocation().y);
    // Speichern der Fenster-Größe
    prefs.putInt("width", getSize().width);
    prefs.putInt("height", getSize().height);
    // Speichern der Font-Einstellungen
    prefs.put("font-name",
              comboFontName.getSelectedItem().toString());
    prefs.put("font-size",
              comboFontSize.getSelectedItem().toString());
    // Zur Sicherheit alles zurückschreiben
    prefs.flush();
  }

Im Prinzip wird nach demselben Schema verfahren wie beim Auslesen, statt der get() werden jedoch put()-Methoden benutzt. Zum Schluss werden die Einstellungen durch Aufruf von flush() persistent gespeichert. Dem plattformspezifischen Speicherungsmechanismus steht es frei, auch bereits vor dem Aufruf von flush() Veränderungen zu sichern, es ist jedoch nicht vorgeschrieben. Da beim Aufruf von flush() alle gepufferten Änderungen in jedem Fall zurückschrieben werden, ist man hiermit auf der sicheren Seite.

Material zum Beispiel

• Quelltexte:
  • SimplePrefDemo.java