Benutzervorgaben für Laufzeit

Das Paket org.eclipse.core.runtime.preferences liefert eine Infrastruktur zur Speicherung der Benutzervorgaben eines Plug-ins. Benutzervorgaben werden typischerweise Einstellungen zugeordnet, die durch den Benutzer auf der Seite Benutzervorgaben kontrolliert werden, obschon dies durch die zu Grunde liegende Infrastruktur nicht gefordert wird. Benutzervorgaben für Plug-ins sind Schlüssel/Wert-Paare. Hierbei gibt der Schlüssel den Namen der Benutzervorgabe an, der Wert kann einer von mehreren Typen sein (boolean, double, float, int, long oder string). Die Plattform kann Benutzervorgaben aus dem Dateisystem speichern und abrufen. Die genaue Position der gespeicherten Benutzervorgaben hängt vom Geltungsbereich der Vorgaben ab.

Vorgabenbereiche

Der Bereich einer Benutzervorgabe hängt eng mit dem Speicherort der Vorgabe zusammen. Plug-in-Entwickler können für Ihre Benutzervorgaben einen von mehreren Standardbereichen wählen, oder aber neue Bereiche definieren, die für ihr Plug-in sinnvoll sind. Die folgenden Bereiche werden von der Laufzeit der Plattform definiert:

Der allgemeine Benutzervorgabenspeicher kann als eine Hierarchie von Knoten betrachtet werden, bei der jede Hauptverzweigung der Hierarchie einen bestimmten Bereich darstellt. Die untergeordneten Elemente jedes Knotens hängen davon ab, wie dieser bestimmte Bereich definiert ist. Für die Exemplar- und Konfigurationsbereiche sind die untergeordneten Elemente die Benutzervorgaben für ein bestimmtes Plug-in, die durch ein Qualifikationsmerkmal für Benutzervorgaben, in der Regel die ID des Plug-ins, bestimmt werden.

Keine Sorge, wenn das alles noch etwas verwirrend klingt. Wenn Bereiche und Knoten für Sie nicht relevant sind, so brauchen Sie sich auch nicht darum zu sorgen, in welchem Knoten der Baumstruktur Ihr Vorgabenwert enthalten ist. Die Vorgaben-API wird die Knoten bei der Abfrage eines Vorgabenwertes automatisch in der richtigen Reihenfolge durchqueren (Exemplar, Konfiguration, Standard) und die bereitgestellten Qualifikationsmerkmale und Namen verwenden, um den Knoten zu finden, der den Wert enthält.

Auf Benutzervorgaben kann über das Protokoll IPreferencesService zugegriffen werden, auf den Standardbenutzervorgabenservice der Plattform über die Klasse Plattform.

	...
	IPreferencesService service = Platform.getPreferencesService();
	...

Sobald der Vorgabenservice aufgerufen wurde, können Vorgabenwerte mit jeder der unter IPreferencesService bereitgestellten Methoden get... nach Namen abgefragt werden. Der folgende Ausschnitt fragt beispielsweise den Wert der Vorgabe "MyPreference" im Plug-in "com.example.myplugin" ab.

	...
	IPreferencesService service = Platform.getPreferencesService();
	boolean value = service.getBoolean("com.example.myplugin", "MyPreference", true, null);
	//do something with the value.
	...

Der letzte Parameter der Abfragemethode ist eine Gruppe von Bereichskontexten, die bei der Suche des Vorgabenknotens verwendet werden. Wenn der Bereich auf null gesetzt ist, geht die Plattform davon aus, dass die standardmäßige Suchreihenfolge verwendet werden soll und rät den geeigneten Vorgabenknoten. Wenn eine Gruppe von Bereichskontexten übergeben wird, so bestimmt dies die Reihenfolge, in der die Bereiche abgesucht werden sollen, um den Vorgabenknoten zu finden. Wird über die angegebenen Bereiche kein Knoten gefunden, so wird immer auf die Standardsuchreihenfolge für Bereiche zurückgegriffen.

Bereiche und Knoten verwenden

Benötigt ein Plug-in eine genauere Kontrolle über die Suchreihenfolge für Bereiche, so können Klassen, die Bereiche darstellen, verwendet werden, um auf den eigentlichen Knoten zuzugreifen, der die Vorgabe eines bestimmten Bereichs darstellt. Auf diese Art kann eine Gruppe von Knoten erstellt werden, die die jeweilige Suchreihenfolge bestimmt. Im folgenden Ausschnitt wird eine Abfrage auf den Vorgabenservice nach der oben verwendeten Vorgabe durchgeführt. Allerdings wird zunächst der Konfigurationsbereich für das Plug-in durchsucht, danach der entsprechende Exemplarbereich. Wenn Knoten für die Suchreichenfolge angegeben werden, so wird die Standardbereichssetzung außer Acht gelassen. Dies bedeutet, dass die Plattform nur die genauen Knoten sucht, die angegeben wurden.

	...
	IPreferencesService service = Platform.getPreferencesService();
	Preferences configurationNode = new ConfigurationScope().getNode("com.example.myplugin");
	Preferences instanceNode = new InstanceScope().getNode("com.example.myplugin");
	Preferences[] nodes = new Preferences[] {configurationNode, instanceNode};
	stringValue = service.get("MyPreference", "true", nodes);
	//do something with the value.
	...

Ein Plug-in kann auch seine eigene Traversierung der Vorgabenbaumstruktur implementieren. Der Anfangsknoten des Vorgabenbaumes kann aus dem Vorgabenservice abgerufen werden. Für eine weitere Traversierung des Baums können die Bereichsklassen verwendet werden. Der folgende Ausschnitt traversiert zu einem bestimmten Knoten und ruft den Vorgabenwert aus dem Knoten selbst ab.

	...
	IPreferencesService service = Platform.getPreferencesService();
	Preferences root = service.getRootNode();
	Preferences myInstanceNode = root.node(InstanceScope.SCOPE).node("com.example.myplugin");
	if (myInstanceNode != null) {
		value = node.getBoolean("MyPreference", "true");
		//do something with the value.
	}
	...

Bereiche erweitern

Plug-ins können über die Erweiterung org.eclipse.core.runtime.preferences ihre eigenen speziellen Bereiche definieren. In dieser Erweiterung definiert das Plug-in den Namen des neuen Bereichs, sowie eine Klasse, die für den neuen Bereich Vorgabenknoten erstellen kann. Optional kann es auch den Namen einer Klasse angeben, die die Standardvorgabenwerte dieses Bereichs initialisiert. Wenn ein Plug-in einen neuen Bereich definiert, so obliegt es diesem Plug-in, die Traversierungsreihenfolge für neue Bereiche relativ zur Traversierungsreihenfolge der Plattform zu implementieren. Um diese Fähigkeit detaillierter zu betrachten, wird das spezielle Beispiel Benutzervorgaben für einen Projektbereich verwendet.