Běhové předvolby

Balíček org.eclipse.core.runtime.preferences poskytuje infrastrukturu pro uložení předvoleb modulu plug-in. Předvolby se zpravidla mapují na nastavení ovládaná uživatelem na stránce Předvolby, přestože to základní infrastruktura nevyžaduje. Předvolby modulů plug-in jsou dvojice klíč-hodnota, kde klíč popisuje název předvolby a hodnota je jednou z několika různých typů hodnot (logická, dvojitá, plovoucí, interval, dlouhá nebo řetězec). Předvolby lze ukládat a platforma je může načítat ze systému souborů. Přesné umístění uložených předvoleb závisí na rozsahu předvolby.

Rozsahy předvoleb

Rozsah předvolby je v úzkém vztahu k místu, kam se předvolba ukládá. Vývojáři modulů plug-in se mohou rozhodnout, které ze standardních rozsahů na své předvolby uplatní, nebo mohou definovat nové rozsahy, které jsou pro jejich modul plug-in smysluplné. Podívejme se nejdříve na rozsahy definované běhovým modulem platformy:

Celkovou zásobu předvoleb si můžete představit jako hierarchickou soustavu uzlů, kde každá hlavní větev hierarchické struktury představuje určitý rozsah. Podřízené prvky kteréhokoli konkrétního uzlu závisí na způsobu, jakým je daný rozsah definován. U rozsahů typu instance a konfigurace jsou podřízenými uzly předvolby pro konkrétní modul plug-in, specifikované kvalifikátorem předvolby, což je obvykle ID daného modulu plug-in.

Pokud se vám to zdá příliš složité, nebojte se. Jestliže vás rozsahy a uzly nezajímají, nemusíte se zabývat žádným konkrétním rozsahem ani tím, který uzel stromové struktury ve skutečnosti obsahuje hodnotu vaší předvolby. Odešlete-li dotaz na hodnotu předvolby, rozhraní API pro předvolby automaticky prochází jednotlivé uzly ve správném pořadí (instance, konfigurace, výchozí) a za použití poskytnutého kvalifikátoru a názvu předvolby najde uzel, který danou hodnotu skutečně obsahuje.

Pro přístup k předvolbám slouží protokol IPreferencesService. Pro přístup k výchozí službě předvoleb platformy je možno použít třídu Platform.

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

Po získání služby předvoleb je možno odesílat dotazy na hodnoty předvoleb podle jejich názvů za použití kterékoli z metod get... nabízených v IPreferencesService. Následující úsek kódu například představuje dotaz na hodnotu předvolby "MyPreference" v modulu plug-in "com.example.myplugin".

	...
	IPreferencesService service = Platform.getPreferencesService();
	boolean value = service.getBoolean("com.example.myplugin", "MyPreference", true, null);
		//provést něco s hodnotou.
	...

Poslední parametr v dotazovací metodě je pole kontextů rozsahu, které se má používat při hledání uzlu předvolby. Pokud je jako hodnota pole zadáno null, potom platforma předpokládá, že se má použít výchozí pořadí hledání rozsahů, a vhodný uzel předvolby odhadne. Pokud je předáno pole kontextů rozsahu, potom určuje pořadí hledání rozsahů, které se má použít k vyhledání uzlu dané předvolby. Pokud při použití zadaných rozsahů nelze žádný uzel najít, použije se vždy výchozí pořadí vyhledávání.

Použití rozsahů a uzlů

Pokud modul plug-in potřebuje jemněji řídit pořadí vyhledávání rozsahů, potom pro přístup ke skutečnému uzlu, který reprezentuje předvolbu v určitém rozsahu, lze použít třídy, které reprezentují jednotlivé uzly. Takto lze vytvořit pole uzlů, které udává požadované pořadí vyhledávání rozsahů. Následující úsek kódu například představuje dotaz na službu předvoleb, přičemž se dotazuje na stejnou předvolbu jako v předchozím příkladu, avšak určuje, že se má prohledávat rozsah předvoleb modulu plug-in na úrovni konfigurace a poté rozsah jeho předvoleb na úrovni instance. Pokud jsou pro pořadí vyhledávání zadány uzly, výchozí vymezení rozsahu platnosti se nebere v úvahu. Znamená to, že platforma prohledá pouze přesně ty uzly, které byly zadány.

	...
	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);
		//provést něco s hodnotou.
	...

Modul plug-in také může implementovat své vlastní pořadí procházení prostřednictvím uzlů stromu předvoleb. Kořenový uzel stromu předvoleb lze získat od služby předvoleb. K dalšímu procházení stromu je možno použít třídy rozsahů. Následující úsek kódu slouží k procházení stromu až k určitému uzlu a k získání hodnoty předvolby ze samotného uzlu.

	...
	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");
		//provést něco s hodnotou.
	}
	...

Rozšiřování rozsahů

Moduly plug-in mohou definovat své vlastní specializované rozsahy za použití rozšíření org.eclipse.core.runtime.preferences. V tomto rozšíření modul plug-in definuje název nového rozsahu a třídu, která umí pro nový rozsah vytvořit uzly předvoleb. Volitelně také může zadat název třídy, která inicializuje výchozí hodnoty předvoleb daného rozsahu. Když modul plug-in definuje nový rozsah, je na tomto modulu plug-in, aby implementoval pořadí procházení stromu pro případný nový rozsah ve vztahu k pořadí procházení platformy. Této schopnosti se budeme podrobněji věnovat za pomoci příkladu Předvolby v rozsahu projektu.