Ajonaikaiset oletusasetukset

Paketissa org.eclipse.core.runtime.preferences on lisäosan oletusasetusten tallennusrakenne. Oletusasetukset vastaavat yleensä asetuksia, joita käyttäjä hallitsee Oletusasetukset-sivun avulla, mutta perustana oleva rakenne ei edellytä tätä. Lisäosan oletusasetukset ovat avain/arvo-pareja, joissa avain on oletusasetuksen nimi ja arvo on jokin useista eri lajeista (boolean, double, float, int, long tai string). Ympäristö voi tallentaa oletusasetuksia tiedostojärjestelmään ja noutaa niitä sieltä. Tallennettujen oletusasetusten täsmällinen sijainti määräytyy oletusasetuksen vaikutusalueen mukaan.

Oletusasetusten vaikutusalueet

Oletusasetuksen vaikutusalue liittyy läheisesti siihen, mihin oletusasetus on tallennettu. Lisäosien kehittäjät voivat päättää, mitä vakiovaikutusalueista käyttävät oletusasetuksissaan, tai voivat määrittää uusia vaikutusalueita, jotka ovat lisäosalle sopivia. Ensin tarkastellaan ajonaikaisen ympäristön määrittämiä vaikutusalueita:

Oletusasetusvarastoa voi ajatella solmujen hierarkiana, jossa hierarkian kukin päähaara edustaa tiettyä vaikutusaluetta. Solmujen aliobjektit ovat riippuvaisia vaikutusalueen määrityksestä. Jos vaikutusalue on ilmentymä tai kokoonpano, alisolmut ovat tietyn lisäosan oletusasetuksia siten kuin on määritetty oletusasetuksen tarkenteessa, joka on yleensä lisäosan tunnus.

Tämä voi aluksi tuntua hämmentävältä. Jos et välitä vaikutusalueista ja solmuista, sinun ei tarvitse huolehtia mistään tietystä vaikutusalueesta tai siitä, missä rakenteen solmussa oletusasetuksen arvo on. Oletusasetusten sovellusohjelmaliittymä käy solmut automaattisesti läpi oikeassa järjestyksessä (ilmentymä, kokoonpano, oletusarvo), kun teet oletusasetuksen arvoa koskevan kyselyn ja selvität, mikä solmu sisältää arvon, käyttämällä toimitettua tarkennetta ja oletusasetuksen nimeä.

Oletusasetuksia käytetään IPreferencesService-käytännön avulla. Ympäristön oletusarvoista oletusasetuspalvelua voi käyttää Platform-luokan avulla.

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

Kun oletusasetuspalvelu on noudettu, oletusasetusten arvoja koskevan kyselyn voi tehdä voi nimen mukaan käyttämällä mitä tahansa get...-metodia IPreferencesService-kohteesta. Esimerkiksi seuraava katkelma tekee "MyPreference"-oletusasetuksen arvoa koskevan kyselyn lisäosassa "com.example.myplugin".

	...
	IPreferencesService service = Platform.getPreferencesService();
	boolean value = service.getBoolean("com.example.myplugin", "MyPreference", true, null);
	//tee jotain arvolla.
	...

Kyselymetodin viimeinen parametri on vaikutusaluekontekstien joukko, jonka avulla voi hakea oletusasetussolmua. Jos joukko on tyhjä, ympäristö käyttää oletusarvoista haun vaikutusaluetta ja arvaa sopivan oletusasetussolmun. Jos vaikutusaluekontekstien joukko välitetään, se määrittää vaikutusalueen hakujärjestyksen, jonka mukaan oletusasetussolmua etsitään. Oletusarvoista vaikutusalueen hakujärjestystä käytetään aina, jos määritettyjen vaikutusalueiden avulla ei löydy solmua.

Vaikutusalueiden ja solmujen käyttö

Jos lisäosa tarvitsee vaikutusalueen hakujärjestyksen tarkempaa hallintaa, tietyn vaikutusalueen oletusasetusta kuvaavaa solmua voi käyttää vaikutusaluetta kuvaavan luokan avulla. Tällä tavoin voi luoda joukon solmuja, jotka määrittävät edellytetyn hakujärjestyksen. Seuraava katkelma tekee edellä käytetyn oletusasetuksen oletusasetuspalvelua koskevan kyselyn, mutta hakee lisäosaa kokoonpanon vaikutusalueella ja sen jälkeen lisäosaa ilmentymän vaikutusalueella. Kun hakujärjestykseen määritetään solmuja, oletusarvoista vaikutusaluetta ei käytetä. Toisin sanoen ympäristö kohdistaa haun vain annettuihin solmuihin.

	...
	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);
	//tee jotain arvolla.
	...

Lisäosa voi myös toteuttaa oman läpikäyntinsä oletusasetusrakenteen solmujen kautta. Oletusasetusrakenteen pääsolmun voi noutaa oletusasetuspalvelusta. Vaikutusalueluokkien avulla rakennetta voi käydä läpi lisää. Seuraava katkelma käy rakennetta läpi tiettyyn solmuun asti ja noutaa oletusasetuksen arvon solmusta itsestään.

	...
	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");
	//tee jotain arvolla.
	}
	...

Vaikutusalueiden laajennus

Lisäosat voivat määrittää omat erikoisvaikutusalueensa org.eclipse.core.runtime.preferences-laajennuksen avulla. Tässä laajennuksessa lisäosa määrittää uuden vaikutusalueen nimen ja luokan, joka voi luoda uuden vaikutusalueen oletusasetussolmuja. Valinnaisesti se voi määrittää sellaisen luokan nimen, joka alustaa kyseisen vaikutusalueen oletusasetusten oletusarvot. Kun lisäosa määrittää uuden vaikutusalueen, on lisäosan tehtävä toteuttaa uuden vaikutusalueen läpikäyntijärjestys suhteessa ympäristön läpikäyntijärjestykseen. Tätä toimintoa tarkastellaan tarkemmin kohdassa Projektinlaajuiset oletusasetukset.