Il pacchetto org.eclipse.core.runtime.preferences fornisce l'infrastruttura per la memorizzazione delle preferenze di un plugin. Le preferenze in genere vengono associate alle impostazioni controllate dall'utente nella pagina Preferenze, nonostante ciò non sia richiesto dall'infrastruttura sottostante. Le preferenze di plugin sono coppie chiave/valore, dove la chiave descrive il nome della preferenza e il valore può essere di tipi diversi (boolean, double, float, int, long, or string). Le preferenze possono essere memorizzate e richiamate mediante la piattaforma dal filesystem. L'ubicazione esatta delle preferenze salvate dipende dall'ambito della preferenza.
È possibile pensare alla memorizzazione complessiva della preferenza come una gerarchia di nodi, dove ciascun ramo principale della gerarchia rappresenti un determinato ambito. Gli elementi secondari di un determinato nodo dipendono dal modo in cui l'ambito è definito. Per gli ambiti di istanza e configurazione, i nodi principali rappresentano le preferenze per un determinato plugin, come specificato da una preferenza qualifier, in genere l'id del plugin.
Se tutto ciò sembra complicato, non bisogna preoccuparsi. Se non si presta attenzione agli ambiti ed ai nodi, non è necessario preoccuparsi di un determinato ambito o del nodo della struttura che attualmente contiene il valore di preferenza. Le API delle preferenze passano attraverso i nodi automaticamente nell'ordine corretto (istanza, configurazione, predefinito) quando si interroga un valore di preferenza e si utilizza il qualificatore fornito e il nome della preferenza per individuare il nodo che effettivamente contiene il valore.
È possibile accedere alle preferenze mediante il protocollo IPreferencesService. È possibile accedere al servizio delle preferenze predefinito della piattaforma utilizzando la classe Piattaforma.
... IPreferencesService service = Platform.getPreferencesService(); ...
Una volta richiamato il servizio delle preferenze, i valori di preferenza possono essere interrogati per nome, mediante uno dei metodi get... forniti in IPreferencesService. Ad esempio, il frammento di seguito riportato interroga il valore della preferenza "MyPreference" nel plugin "com.example.myplugin".
... IPreferencesService service = Platform.getPreferencesService(); boolean value = service.getBoolean("com.example.myplugin", "MyPreference", true, null); //do something with the value. ...
L'ultimo parametro nel metodo query è una matrice di contesti di ambito da utilizzare quando si ricerca il nodo della preferenza. Se la matrice è null, la piattaforma presuppone che debba essere utilizzato l'ordine di ricerca dell'ambito predefinito e nasconde il nodo di preferenza appropriato. Se una matrice di contesti di ambito viene trasferita, ciò determina l'ordine di ricerca dell'ambito da utilizzare per individuare il nodo della preferenza. L'ordine di ricerca dell'ambito predefinito viene sempre consultato, se non è possibile individuare alcun nodo utilizzando gli ambiti specificati.
Se un plugin necessita di uno stretto controllo sull'ordine di ricerca dell'ambito, le classi che rappresentano gli ambiti possono essere utilizzate per accedere al nodo effettivo che rappresenta la preferenza in un determinato ambito. In questo modo, può essere creata una matrice di nodi che specifichi il particolare ordine di ricerca richiesto. Nel frammento di seguito riportato viene interrogato il servizio delle preferenze per la preferenza utilizzata in precedenza, ma viene ricercato l'ambito di configurazione del plugin, seguito dall'ambito dell'istanza del plugin. Quando per l'ordine di ricerca vengono specificati i nodi, l'ambito predefinito non viene considerato. Ciò significa che la piattaforma ricerca solo i nodi che sono stati forniti.
... 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. ...
Un plugin può anche implementare il proprio passaggio attraverso i nodi della struttura delle preferenze. Il nodo principale della struttura delle preferenze può essere richiamato dal servizio delle preferenze. Le classi dell'ambito possono essere utilizzate per passare attraverso la struttura. Il frammento di seguito riportato passa attraverso uno specifico nodo e richiama il valore di preferenza del nodo.
... 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. } ...
I plugin possono definire propri ambiti specifici utilizzando l'estensione org.eclipse.core.runtime.preferences. In questa estensione, il plugin definisce il nome del nuovo ambito e una classe che può creare i nodi di preferenze per il nuovo ambito. Facoltativamente, è possibile specificare il nome di una classe che inizializza valori di preferenza predefiniti per questo ambito. Quando un plugin definisce un nuovo ambito, è compito di questo plugin implementare l'ordine di passaggio per i nuovi ambiti, relativo all'ordine di passaggio della piattaforma. Questa funzione viene illustrata con maggiori dettagli utilizzando l'esempio specifico riportato nella sezione Preferenze del progetto in base all'ambito.