O pacote org.eclipse.core.runtime.preferences fornece infra-estrutura para armazenar as preferências de um plug-in. As preferências normalmente mapeiam para configurações controladas pelo usuário na página de Preferências, embora isso não seja requerido pela estrutura de suporte. As preferências de plug-in são pares chave/valor, em que a chave descreve o nome da preferência e o valor é um em vários tipos diferentes (booleano, duplo, flutuante, int, longo, ou cadeia). As preferências podem ser armazenadas e recuperadas pela plataforma a partir do sistema de arquivo. O local exato das preferências salvas depende do escopo da preferência.
Você pode pensar no armazenamento geral das preferências como uma hierarquia de nós em que cada ramificação principal da hierarquia representa um escopo específico. As crianças de qualquer nó específico dependem de como esse escopo é definido. Para os escopos de instância e de configuração, os nós filhos são as preferências para um plug-in específico como especificado por um qualificador de preferência, normalmente o id do plug-in.
Se tudo isso parecer confuso, não se preocupe. Se você não se importa com escopos e nós, você não precisa se preocupar com qualquer escopo específico ou sobre qual nó da árvore realmente contém seu valor de preferência. A API de preferências automaticamente atravessará os nós na ordem adequada (instância, configuração, padrão) quando você consultar um valor de preferência e utilizar o qualificador e o nome da preferência fornecidos para localizar o nó que realmente contém o valor.
As preferências são acessadas utilizando o protocolo IPreferencesService. O serviço de preferência padrão da plataforma pode ser acessado utilizando a classe Plataforma.
... IPreferencesService service = Platform.getPreferencesService(); ...
Assim que o serviço de preferência é obtido, os valores de preferência podem ser consultados por nome, utilizando qualquer um dos métodos get... fornecidos em IPreferencesService. Por exemplo, o seguinte fragmento consulta o valor da preferência "MyPreference" no plug-in "com.example.myplugin".
... IPreferencesService service = Platform.getPreferencesService(); boolean value = service.getBoolean("com.example.myplugin", "MyPreference", true, null); //do something with the value. ...
O último parâmetro no método de consulta é uma matriz dos contextos de escopo a serem utilizados ao procurar o nó da preferência. Se a matriz é null, a plataforma assume que a ordem de procura do escopo padrão deve ser utilizada e adivinha o nó de preferência apropriado. Se uma matriz de contextos de escopo é transmitida, isso determina a ordem de consulta de escopo que deve ser utilizada para localizar o nó de preferência. A ordem de consulta do escopo padrão é sempre consultada se nenhum nó pode ser localizado utilizando os escopos especificados.
Se um plug-in precisa de um controle mais intenso sobre a ordem de procura do escopo, as classes que representam os escopos podem ser utilizadas para acessar o nó verdadeiro que representa a preferência em um escopo específico. Desse modo, uma matriz de nós pode ser criada que especifica a ordem de procura específica requerida. O seguinte fragmento consulta o serviço de preferências para a mesma preferência utilizada acima, mas procura o escopo de configuração para o plug-in, seguido pelo escopo da instância para o plug-in. Quando os nós são especificados para a ordem de procura, o escopo padrão não é considerado. Ou seja, a plataforma procurará somente os nós exatos que foram fornecidos.
... 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. ...
Um plug-in também pode implementar sua própria travessia por meio dos nós da árvore de preferência. O nó da raiz da árvore de preferência pode ser obtido a partir do serviço de preferências. As classes de escopo podem ser utilizadas para atravessar a árvore. O seguinte fragmento atravessa um nó específico e recupera o valor de preferência da nó em si.
... 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. } ...
Os plug-ins podem definir seus próprios escopos especializados utilizando a extensão org.eclipse.core.runtime.preferences. Nessa extensão, o plug-in define o nome do novo escopo, assim como uma classe que pode criar nós de preferência para o novo escopo. Opcionalmente, pode especificar o nome de uma classe que inicializa os valores de preferência padrão nesse escopo. Quando um plug-in define um novo escopo, depende desse plug-in implementar a ordem de travessia para qualquer novo escopo relativo à ordem de travessia da plataforma. Observaremos esse recurso mais detalhadamente utilizando o exemplo específico de Preferências em Escopo do Projeto.