Preferências de tempo de execução

O pacote org.eclipse.core.runtime.preferences faculta uma infra-estrutura para armazenar as preferências de um plug-in. As preferências geralmente correlacionam-se com definições controladas pelo utilizador na página Preferências, embora tal não seja requisito da infra-estrutura subjacente. As preferências de plug-ins são pares chave/valor, em que a chave descreve o nome da preferência, e o valor é um dos vários tipos diferentes (booleano, duplo, flutuante, número inteiro, longo ou cadeia de caracteres). A plataforma pode armazenar e obter as preferências a partir do sistema de ficheiros. A localização exacta das preferências guardadas depende do âmbito da preferência.

Âmbitos de preferências

O âmbito de uma preferência está intimamente relacionado com o lugar de armazenamento da mesma. Os programadores de plug-ins podem decidir qual dos âmbitos padrão aplicar às suas preferências ou definir novos âmbitos que façam sentido para o seu plug-in. Vejamos primeiro os âmbitos definidos pelo tempo de execução da plataforma:

Poderá pensar no arquivo de preferências global como uma hierarquia de nós, em que cada ramificação principal da hierarquia representa determinado âmbito. Os descendentes de determinado nó dependem da definição desse âmbito. Para os âmbitos de instância e configuração, os nós descendentes são as preferências para determinado plug-in, conforme especificado por um qualificador de preferência, geralmente o ID do plug-in.

Se tudo isto lhe parecer confuso, não se preocupe. Se não se importar com âmbitos e nós, não terá de se debruçar sobre determinado âmbito ou qual o nó da árvore que contém o seu valor de preferência. A API de preferências atravessa automaticamente os nós pela ordem apropriada (instância, configuração, predefinição) quando se consulta um valor de preferência e se utiliza o qualificador e o nome da preferência facultados para detectar o nó que contém realmente o valor.

As preferências são acedidas com o protocolo IPreferencesService. O serviço de preferências predefinido da plataforma pode ser acedido com a classe Platform.

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

Uma vez obtido o serviço de preferências, os valores de preferências podem ser consultados pelo nome com qualquer dos métodos get... facultados em IPreferencesService. Por exemplo, a porção de código seguinte consulta o valor da preferência "aMinhaPreferência" no plug-in "com.exemplo.omeuplugin".

	...
	IPreferencesService service = Platform.getPreferencesService();
	boolean value = service.getBoolean("com.exemplo.omeuplugin", "aMinhaPreferência", true, null);
		//fazer algo com o valor.
	...

O último parâmetro no método de consulta é uma matriz de contextos de âmbito a utilizar na pesquisa do nó de preferências. Se a matriz for null, a plataforma presume que a ordem de pesquisa do âmbito predefinido deve ser usada e adivinha o nó de preferências apropriado. Se for transmitida uma matriz de contextos de âmbito, esta determina a ordem de busca do âmbito que deve ser usado para detectar o nó de preferências. A ordem de busca do âmbito é sempre consultada se não for detectado nó algum com os âmbitos especificados.

Utilizar âmbitos e nós

Se um plug-in precisar de mais controlo sobre a ordem de pesquisa de âmbitos, podem ser usadas as classes que representam os âmbitos para aceder ao verdadeiro nó que representa as preferências em determinado âmbito. Desta forma, pode ser criada uma matriz de nós que especifique a ordem de pesquisa necessária. A porção de código seguinte consulta o serviço de preferências para ver a mesma preferência utilizada supra, mas pesquisa o âmbito de configuração para ver o plug-in, seguido do âmbito de instância para ver o plug-in também. Quando são especificados nós para ordem de pesquisa, não se considera âmbito de predefinição. Significa isto que a plataforma só pesquisa os nós exactos que tenham sido facultados.

	...
	IPreferencesService service = Platform.getPreferencesService();
	Preferences configurationNode = new ConfigurationScope().getNode("com.exemplo.omeuplugin");
	Preferences instanceNode = new InstanceScope().getNode("com.exemplo.omeuplugin");
	Preferences[] nodes = new Preferences[] {configurationNode, instanceNode};
	stringValue = service.get("aMinhaPreferência", "true", nodes);
		//fazer algo com o valor.
	...

Um plug-in também pode implementar a sua própria travessia através dos nós da árvore de preferências. O nó raiz da árvore de preferências pode ser obtido junto do serviço de preferências. As classes de âmbito podem ser utilizadas para fazer mais travessias na árvore. A porção de código seguinte atravessa para um nó específico e obtém o valor da preferência junto do próprio nó.

	...
	IPreferencesService service = Platform.getPreferencesService();
	Preferences root = service.getRootNode();
	Preferences oMeuNóInstância = root.node(InstanceScope.SCOPE).node("com.exemplo.omeuplugin");
	if (oMeuNóInstância != null) {
		value = node.getBoolean("aMinhaPreferência", "true");
		//fazer algo com o valor.
	}
	...

Estender âmbitos

Os plug-ins podem definir os seus próprios âmbitos especializados com a extensão org.eclipse.core.runtime.preferences. Nesta extensão, o plug-in define o nome do novo âmbito, assim como uma classe que possa criar nós de preferências para o novo âmbito. Opcionalmente, pode especificar o nome de uma classe que inicialize os valores de preferências predefinidos nesse âmbito. Quando um plug-in define novo âmbito, compete a esse plug-in implementar a ordem de travessia para qualquer âmbito relativamente à ordem de travessia da plataforma. Veremos esta capacidade em mais pormenor no exemplo específico de Preferências por âmbito de projecto.