java.lang.Object
   |
   +--java.util.prefs.Preferences

Deklaration

Beschreibung

Einstellungen werden durch die Java-Laufzeitumgebung auf einen Speicherungsmechanismus innerhalb des verwendeten Betriebssystems abgebildet. So werden Einstellungen auf Windows in der Windows-Registrierung, auf Unix in Dateien abgelegt. Der voreingestellte Speicherungsmechanismus kann durch einen Eigenen ersetzt werden, der z. B. auf eine Datenbank oder einen Verzeichnisdienst zur Speicherung zurückgreift.

Die Knoten sind in einer Hierarchie angeordnet und besitzen einen Namen, sowie keinen bis Schlüssel-Wert-Paare. In letzteren werden die eigentlichen Einstellungs-Daten gespeichert. Die Hierarchie, in der die Knoten angeordnet sind, bilden lediglich den Kontext ab, dem die gespeicherten Einstellungen zugeordnet sind. In der voreingestellten Implementierung werden alle Werte intern als Zeichenketten gespeichert. Es existieren jedoch auch Methoden, die zum Setzen von numerischen und binären Daten benutzt werden können. Diese Methoden führen intern eine entsprechende Konvertierung der Daten in Zeichenketten durch.

Innerhalb der Hierarchie wird ein Einstellungs-Knoten eindeutig durch seinen Pfad identifiziert. Der Pfad besteht aus den Namen der Knoten, die durch einen Schrägstrich getrennt werden. Der Schrägstrich alleine stellt den Pfad zum Wurzel-Knoten der Hierarchie dar.

Alle Methoden, die auf Einstellungen lesen bzw. schreiben lösen eine BackingStoreException, wenn der zugrundeliegende Speicherungs-Mechanismus aktuell nicht verfügbar ist.

Einstellungen können über eine XML-basierte Export-/Import-Schnittstelle zwischen verschiedenen Speicherungsmechanismen auszutauschen.

Datenelemente im Detail

public final static int MAX_KEY_LENGTH

Maximale Länge, die als Schlüssel-Name erlaubt ist (80 Zeichen).

public final static int MAX_NAME_LENGTH

Maximale Länge des Namen eines Knotens (80 Zeichen).

public final static int MAX_VALUE_LENGTH

Maximale Länge, der den ein Wert als Text enthalten kann (8192 Zeichen).

Konstruktoren im Detail

protected Preferences()

Konstruktor ohne Parameter. Er wird von Unterklassren - meist implizit - aufgerufen.

Methoden im Detail

public abstract String absolutePath()

Liefert den absoluten Pfad eines Knotens.

public abstract void addNodeChangeListener(NodeChangeListener ncl)

Das übergebene Exemplar wird nach dem Aufruf über Änderungen innerhalb der Einstellungs-Hierarchie informiert (z. B. Hinzufügen oder Löschen des Knotens).

public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)

Das übergebene Exemplar wird nach dem Aufruf über Änderungen innerhalb des Einstellungs-Knotens informiert (Einfügen, Löschen und Ändern von Schlüssel-Wert Paaren innerhalb des Knotens).

public abstract String[] childrenNames()

Liefert die Namen der Kind-Knoten relativ zu diesem Knoten zurück. Wenn der Knoten keine Kind-Knoten hat, wird ein Array der Länge 0 zurückgeliefert.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract void clear()

Löscht alle Einstellungen (Schlüssel-Wert Paare) im diesem Knoten.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract void exportNode(OutputStream os)

Schreibt die Einstellungen im aktuellen Knoten im XML-Export Format in den übergebenen Stream. Die Einstellungen in Kind-Knoten werden dabei nicht berücksichtigt.

Exception: IOException

• Wenn der übergebene Stream eineIOException auslöst.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract void exportSubtree(OutputStream os)

Schreibt, ausgehend vom aktuellen Knoten, die Einstellungs-Hierarchie im XML-Export Format in den übergebenen Stream. Dabei werden die Einstellungen im aktuellen Knoten und all seiner Kind-Knoten exportiert.

Exception: IOException

• Wenn der übergebene Stream eineIOException auslöst.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract void flush()

Sort dafür, dass der Inhalt dieses Einstellungs-Knotens und aller Unterknoten mit dem Speicherungsmechanismus synchronisiert werden. Dabei werden alle noch nicht gespeicherten Änderungen persistent.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract String get(String key, String def)

Liefert die Einstellung mit dem übergebenen Schlüssel als String zurück.

public abstract boolean getBoolean(String key, boolean def)

Liefert die Einstellung mit dem übergebenen Schlüssel als boolean-Wert zurück. Dabei wird der Wert true in der zugrundeliegenden Zeichenkette als »true« und false als »false« gespeichert, wobei die Konvertierung nicht case-sensitiv ist.

public abstract byte[] getByteArray(String key, byte[] def)

Liefert die Einstellung mit dem übergebenen Schlüssel als Byte-Array zurück. Es wird erwartet, dass die zugrundeliegenden Daten intern als Base64 codierte Zeichenkette nach RFC 2045 (http://www.ietf.org/rfc/rfc2045.txt) vorliegt mit einer Änderung: Es sind nur Zeichen aus dem Base64-Alphabet zulässig.

public abstract double getDouble(String key, double def)

Liefert die Einstellung mit dem übergebenen Schlüssel als double-Wert. Wenn die zugrundeliegene Einstellung keinen mit dem Datentyp double kompatiblen Wert enthält, wird beim Aufruf eine NumberFormatException ausgelöst.

public abstract float getFloat(String key, float def)

Liefert die Einstellung mit dem übergebenen Schlüssel als float-Wert. Wenn die zugrundeliegene Einstellung keinen mit dem Datentyp float kompatiblen Wert enthält, wird beim Aufruf eine NumberFormatException ausgelöst.

public abstract int getInt(String key, int def)

Liefert die Einstellung mit dem übergebenen Schlüssel als int-Wert. Wenn die zugrundeliegene Einstellung keinen mit dem Datentyp int kompatiblen Wert enthält, wird beim Aufruf eine NumberFormatException ausgelöst.

public abstract long getLong(String key, long def)

Liefert die Einstellung mit dem übergebenen Schlüssel als long-Wert. Wenn die zugrundeliegene Einstellung keinen mit dem Datentyp long kompatiblen Wert enthält, wird beim Aufruf eine NumberFormatException ausgelöst.

public static void importPreferences(InputStream is)

Importiert die Einstellungen, die über den übergebenen Stream gelesenen werden in die aktuelle Einstellungs-Hierarchie. Die zu lesenen Daten müssen daben entsprechend dem XML-Format für Einstellungen aufgebaut sein.

Exception: IOException

• Wenn die Leseoperation von dem übergebenen Stream eineIOException auslöst.

Exception: InvalidPreferencesFormatException

• Wenn die eingelesenen Daten in keinem gültigen Format abgelegt sind.

public abstract boolean isUserNode()

Liefert true zurück, wenn es sich bei diesem Knoten um eine Benutzer-spezifische Einstellunge handelt, ansonsten false (bei einer System-spezifischen Einstellung).

public abstract String[] keys()

Liefert alle Schlüssel zurück, zu denen in diesem Knoten Werte zu geordnet sind. Wenn der Knoten keine Schlüssel-Wert Paare enthält, wird ein Array der Länge 0 zurückgeliefert.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract String name()

Liefert den Namen des Knotens zurück.

public abstract Preferences node(String pathName)

Liefert den Einstellungs-Knoten mit dem übergebenen Namen relativ zum aktuellen Knoten zurück. Wenn kein Knoten mit dem übergebenen Namen existiert, wird der Knoten neu erstellt. Diese Methode akzeptiert sowohl relative als auch absolute Pfade.

Die Persistenz von neu erstellten Knoten ist erst nach dem Aufruf von flush() sichergestellt.

public abstract boolean nodeExists(String pathName)

Liefert true, falls der Knoten mit dem übergebenen Pfad existiert. Relative Pfade sind zulässig und werden relativ zum aktuellen Knoten interpretiert.

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public abstract Preferences parent()

Liefert den Eltern-Knoten zurück, oder null falls es sich bei diesem Knoten um einen Wurzel-Knoten handelt.

public abstract void put(String key, String value)

Speichert den Wert zum übergebenen Schlüssel als Zeichenkette.

Alle Einstellungen werden intern als Zeichenketten abgelegt. Die Methoden zur Speicherung typisierter Daten führen intern eine Konvertierung in eine Zeichenkette durch und verwenden meist diese Methode zur tatsächlichen Speicherung.

public abstract void putBoolean(String key, boolean value)

Speichert den Wert zum übergebenen Schlüssel als boolean.

public abstract void putByteArray(String key, byte[] value)

Speichert den Wert zum übergebenen Schlüssel als Byte-Array. Dabei wird intern das übergeben Byte-Array in eine leicht modifiziert Form von Base64 (RFC 2045) konvertiert. Der Unterschied zum Original Base64 besteht dabei lediglich darin, dass die codierter Zeichenkette keine Zeilenumbrüche enthält.

Bei der Verwendung dieser Methode ist darauf zu achten, dass die codierte Form des Byte-Arrays in der Länge nicht den Wert übersteigt, der in MAX_VALUE_LENGTH definiert ist.

public abstract void putDouble(String key, double value)

Speichert den Wert zum übergebenen Schlüssel als double.

public abstract void putFloat(String key, float value)

Speichert den Wert zum übergebenen Schlüssel als float:

public abstract void putInt(String key, int value)

Speichert den Wert zum übergebenen Schlüssel als int.

public abstract void putLong(String key, long value)

Speichert den Wert zum übergebenen Schlüssel als long.

public abstract void remove(String key)

Entfernt die Einstellung zum übergebenen Schlüssel aus diesem Einstellung-Knoten.

public abstract void removeNode()

Entfernt diesen und alle untergeordneten Knoten. Alle Methoden liefern einen IllegalStateException nach dem Löschvorgang, mit Ausnahme vonname() , absolutePath(),isUserNode() , flush(), node(String),nodeExists(»«) und den Standard-Methoden, die in der Klasse Object definiert sind.

Erst nach dem Aufruf von flush() wird sichergestellt, dass der Löschvorgang über Persistenz-Mechanismus festgeschrieben wurde.

Nach dem Entfernen eines Knotens wird der Default-Zustand vor dem Einfügen an der Stelle in der Einstellung-Hierarchie wieder hergestellt.

Exception: BackingStoreException

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

Entfernt den übergebenen NodeChangeListener von diesem Einstellung-Knoten.

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

Entfernt den übergebenen PreferenceChangeListener von diesem Einstellung-Knoten.

public abstract void sync()

Stellt sicher, das zukünftige Lese-Operationen von diesem Knoten und allen Unterknoten alle Änderungen enthalten, die über den Persistenz-Mechanismus festgeschrieben wurden. Dabei werden auch Änderungen sichtbar, die in anderen Java-Laufzeitumgebungen oder direkt über den Persistenz-Mechanismus durchgeführt wurden (z. B. direktes Editieren von Einträgen in der Windows-Registry).

Exception: BackingStoreException

• Wenn eine Operation auf einem Einstellung-Knoten nicht durchgeführt werden konnte, weil ein Fehler im Persistenz-Mechanismus auftrat oder der Persistenz-Mechanismus nicht kontaktiert werden konnte.

public static Preferences systemNodeForPackage(Class c)

Liefert den System-spezifischen Einstellung-Knoten für eine konkrete Java-Klasse zurück. Der Pfad zum Einstellung-Knoten wird dabei bestimmt, indem beim vollqualifizierten Klassennamen das Paket-Trennzeichen (der Punkt) durch einen Schrägstrich ersetzt wird. d. h. wird die Klassede.dpunkt.runtime.prefs.SimplePrefDemo , verwendet, liefert die Methode den Einstellung-Knoten mit dem Pfad (/de/dpunkt/runtime/prefs/SimplePrefDemo) zurück.

Befindet sich die übergebene Klasse um unbenannten Package, so wird der Einstellung-Knoten mit dem Namen /<unnamed> zurückgeliefert. In diesem Knoten sollte allerdings nur temporär benutzt werden, um die Funktionalität einer Anwendung zu testen.

Folgende Beispiele zeigen, wie man auf über diese Methode auf einen Einstellung-Knoten zugreift. Innerhalb einer Klasse kann man folgende Technik benutzen:

Preferences prefs = Preferences.systemNodeForPackage(getClass());

Für den statischen Zugriff empfielt sich die Verwendung der folgenden Technik:

static Preferences prefs = Preferences.systemNodeForPackage(MyClass.class);

Die Methode wandelt intern zunächst die übergebene Klasse in den Namen eines Einstellung-Knoten um und ruft danach den Knoten mit dem ermittelten Namen über die Methode systemRoot().node() ab. Dadurch wird der Knoten erzeugt, falls er vor dem Aufruf noch nicht existiert.

public static Preferences systemRoot()

Liefert den Wurzel-Knoten für die System-Einstellungen.

public abstract String toString()

Liefert eine Zeichenkette zurück, die den Knoten repräsentiert. Dabei wird folgender Ausdruck für die Erstellung benutzt:

isUserNode() ? "User" :
 "System") + " Preference Node: " + this.absolutePath()

public static Preferences userNodeForPackage(Class c)

Liefert den Benutzer-spezifischen Einstellung-Knoten für eine konkrete Java-Klasse zurück. Der Pfad zum Einstellung-Knoten wird dabei bestimmt, indem beim vollqualifizierten Klassennamen das Paket-Trennzeichen (der Punkt) durch einen Schrägstrich ersetzt wird. d. h. wird die Klassede.dpunkt.runtime.prefs.SimplePrefDemo , verwendet, liefert die Methode den Einstellung-Knoten mit dem Pfad (/de/dpunkt/runtime/prefs/SimplePrefDemo) zurück.

Befindet sich die übergebene Klasse um unbenannten Package, so wird der Einstellung-Knoten mit dem Namen /<unnamed> zurückgeliefert. In diesem Knoten sollte allerdings nur temporär benutzt werden, um die Funktionalität einer Anwendung zu testen.

Folgende Beispiele zeigen, wie man auf über diese Methode auf einen Einstellung-Knoten zugreift. Innerhalb einer Klasse kann man folgende Technik benutzen:

Preferences prefs = Preferences.userNodeForPackage(getClass());

Für den statischen Zugriff empfielt sich die Verwendung der folgenden Technik:

static Preferences prefs = Preferences.userNodeForPackage(MyClass.class);

Die Methode wandelt intern zunächst die übergebene Klasse in den Namen eines Einstellung-Knoten um und ruft danach den Knoten mit dem ermittelten Namen über die Methode userRoot().node() ab. Dadurch wird der Knoten erzeugt, falls er vor dem Aufruf noch nicht existiert.

public static Preferences userRoot()

Liefert den Wurzel-Knoten mit den Benutzer-Einstellungen des aufrufenden Anwenders.