Preferencje środowiska wykonawczego

Pakiet org.eclipse.core.runtime.preferences stanowi infrastrukturę do przechowywania preferencji związanych z modułem dodatkowym. Preferencje są zwykle odpowiednikami ustawień określanych przez użytkownika na stronie Preferencje, chociaż nie jest to wymogiem stawianym przez bazową infrastrukturę. Preferencje modułu dodatkowego mają postać par klucz/wartość, gdzie klucz jest nazwą preferencji, a wartość ma jeden z kilku dozwolonych typów (boolean, double, float, int, long lub string). Preferencje mogą być zapisywane i odczytywane przez platformę w systemie plików. Dokładne położenie zapisywanych preferencji zależy od zasięgu preferencji.

Zasięg preferencji

Zasięg preferencji jest ściśle związany z miejscem przechowywania preferencji. Twórcy modułów dodatkowych mogą decydować, które ze standardowych zasięgów mają zastosowanie w przypadku ich preferencji, mogą także definiować nietypowe zasięgi odpowiednio do potrzeb. W pierwszej kolejności omówione zostaną zasięgi definiowane przez środowisko wykonawcze platformy:

Zbiór zapisanych preferencji można przedstawić w postaci hierarchii węzłów, w której każda główna gałąź hierarchii reprezentuje określony zasięg. Węzły potomne danego węzła zależą od definicji zasięgu. W przypadku zasięgów o skali instancji i konfiguracji węzły potomne są preferencjami określonego modułu dodatkowego zgodnie z kwalifikatorem preferencji, którym jest zwykle identyfikator modułu dodatkowego.

Jeśli informacje te są trudne do ogarnięcia, nie ma potrzeby się tym martwić. Jeśli kwestia zasięgów i węzłów nie ma znaczenia dla tworzonego modułu, nie ma potrzeby rozpatrywać zasięgów ani tego, który węzeł drzewa w istocie zawiera potrzebne wartości preferencji. Interfejs API preferencji automatycznie przechodzi przez węzły we właściwym porządku (instancja, konfiguracja, ustawienia domyślne) po wprowadzeniu zapytania o wartość preferencji z użyciem kwalifikatora i nazwy preferencji, znajdując węzeł faktycznie zawierający daną wartość.

Dostęp do preferencji odbywa się z użyciem protokołu IPreferencesService. Usługa preferencji domyślnych platformy jest dostępna za pośrednictwem klasy Platform.

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

Po uzyskaniu usługi preferencji wartości preferencji można odczytywać według nazwy przy użyciu dowolnej z metod get... zaimplementowanych w klasie IPreferencesService. Na przykład następujący fragment kodu odczytuje wartość preferencji "MyPreference" dla modułu dodatkowego "com.example.myplugin".

	...
 IPreferencesService service = Platform.getPreferencesService();
	boolean value = service.getBoolean("com.example.myplugin", "MyPreference", true, null);
	//operacje na odczytanej wartości.
	...

Ostatnim parametrem w metodzie zapytania jest tablica kontekstów zasięgu, używana przy wyszukiwaniu węzła preferencji. Jeśli parametr tablicy ma wartość null, platforma zakłada, że należy zastosować domyślny porządek przeszukiwania zasięgów, odgadując właściwy węzeł preferencji. W razie przekazania tablicy kontekstów zasięgu ustalany jest porządek przeszukiwania odpowiedni do danego węzła preferencji. Jeśli przy użyciu wskazanych zasięgów nie uda się znaleźć żadnego węzła, zawsze następuje odwołanie do domyślnego porządku przeszukiwania zasięgów.

Korzystanie z zasięgów i węzłów

Jeśli w przypadku danego modułu dodatkowego wymagana jest bardziej szczegółowa kontrola nad porządkiem przeszukiwania zasięgów, można posłużyć się klasami reprezentującymi zasięgi, odwołując się w ten sposób do konkretnego węzła zawierającego preferencję o właściwym zasięgu. Dzięki temu można utworzyć tablicę węzłów definiującą właściwy porządek przeszukiwania. Niżej przedstawiony fragment kodu powoduje odpytanie usługi preferencji pod kątem tej samej preferencji co poprzednio, jednak z uwzględnieniem następującego porządku: najpierw zasięg konfiguracji modułu, a później zasięg instancji modułu. W razie podania węzłów na potrzeby porządku przeszukiwania domyślny układ zasięgów nie jest uwzględniany. Oznacza to, że platforma będzie przeszukiwać wyłącznie wskazane węzły.

	...
 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);
	//operacje na odczytanej wartości.
	...

Moduł dodatkowy może też zawierać implementację własnej ścieżki przejścia przez węzły drzewa preferencji. Węzeł główny drzewa preferencji można ustalić, odwołując się do usługi preferencji. Do dalszego poruszania się po drzewie służą następnie klasy zasięgów. Następujący fragment kodu powoduje przejście do określonego węzła i odczytanie wartości preferencji z tego węzła.

	...
 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");
	//operacje na odczytanej wartości.
	}
	...

Rozszerzanie zasięgów

Moduły dodatkowe mogą zawierać własne definicje nietypowych zasięgów w rozszerzeniu org.eclipse.core.runtime.preferences. Rozszerzenie to definiuje nazwę nowego zasięgu oraz klasę odpowiedzialną za tworzenie węzłów preferencji w tym zasięgu. Opcjonalnie można określić nazwę klasy inicjującej domyślne wartości preferencji zasięgu. Gdy moduł dodatkowy definiuje nowy zasięg, musi on także określać porządek przechodzenia dla każdego nowego zasięgu w odniesieniu do porządku przechodzenia na platformie. Funkcja ta zostanie omówiona bardziej szczegółowo na przykładzie preferencji o zasięgu projektu.