Melhores práticas para desenvolver plug-ins do Eclipse

Usando marcadores, anotações e decoradores

Este tutorial destaca as melhores práticas ao marcar informações para recursos usando marcados e então apresenta melhores anotações e decoradores que podem ser usados para destacar marcadores dentro do ambiente de trabalho. Estendendo pontos de extensão, é possível reutilizar e adaptar as funções integradas no Eclipse e realizar marcação avançada de recursos, como mover um marcador de texto ao editar texto. Discutimos métodos que aproveitam o modelo de plug-in, o que permite um plug-in eficiente, de alto desempenho e com visual e experiência integrados.

Andy Flatt, Software Developer, IBM

Photo of Andy FlattAndy Flatt é desenvolvedor no IBM Software Development Laboratory em Hursley, no Reino Unido. Sua experiência inclui Java, Java Performance, OSGi e teste de integração. Antes de desenvolvimento de software, Andy estudou na Universidade de Hertfordshire e graduou-se com honras em Ciência da Computação. Ele pode ser contatado pelo endereço aflatt@uk.ibm.com.


nível de autor Contribuidor do
        developerWorks

Mickael Maison, Software Developer, IBM

Photo of Mickael MaisonDesde que passou a fazer parte da IBM em meados de 2009, Mickael trabalha do departamento de Runtime Deliveries do IBM Java Technology Center. Depois de trabalhar na equipe L3 Support para IBM Java SDK, ele passou para a função de desenvolvedor. Em seu tempo livre, Mickael gosta de escutar música e viajar.



03/Nov/2011

Introdução

Ao desenvolver um plug-in para um ambiente IDE Eclipse, há várias considerações de design. Essas considerações garantem que você:

  • Não bloqueie o encadeamento da interface com o usuário.
  • Decore a interface com o usuário sem causar impacto ao desempenho.
  • Processe dados no segundo plano.

Este tutorial discute como processar e exibir dados associados a recursos no espaço de trabalho com essas considerações de design. Examinaremos como o Eclipse fornece uma interface de marcador para armazenar e manipular informações sobre um recurso.

Fornecemos melhores práticas para manipular marcadores de dados com relação a um recurso. Primeiro, mostramos como marcar dados e, então, como desenvolver o conhecimento para representar o marcador na interface com o usuário e, por fim, atualizar o marcador conforme o recurso muda. Nesse contexto, os recursos são os objetos do Eclipse que implementam a interface IResource, como projetos, arquivos, pastas e objetos Java ™ (incluindo pacotes, classes e origens).

Este tutorial é voltado para desenvolvedores que sabem escrever um plug-in básico, mas desejam aprender as melhores práticas ao lidar com recursos do Eclipse.

Interfaces e pontos de extensão individuais de documentos do Eclipse.org. Este artigo fornece assistência na escolha da melhor prática para usá-los em combinação. Leia mais para obter vantagem das funções do Eclipse existente para fornecer novos recursos.


Parte 1: criar seu próprio marcador

O que são marcadores?

Marcadores são usados para vincular informações a um recurso sem precisar alterar o recurso. Exemplos comuns de informações marcadas são pontos de interrupção, marcadores e erros de compilação. Pegando o exemplo de erros de compilação, sempre que um trabalho de compilação é executado, o trabalho procurará na origem e destacará os erros criando um novo marcador.

Estender marcadores

Na primeira parte deste tutorial, criaremos nosso próprio tipo de marcador. Isso é feito pelo uso do ponto de extensão do marcador e escrevendo apenas uma linha de código.

É possível criar seus próprios marcadores estendendo o ponto de extensão IMarker org.eclipse.core.resources.markers. Comece adicionando o código na Listagem 1. ao seu arquivo plugin.xml. Isso diz que você criará um marcador chamado My Marker com o id com.ibm.mymarkers.mymarker. Seu supertipo é org.eclipse.core.resources.marker. Esse é o tipo de marcador mais básico. É possível estender outros supertipos que oferecem funções que são ligeiramente mais específicas. Os outros supertipos disponíveis são:

  • org.eclipse.core.resources.problemmarker
  • org.eclipse.core.resources.textmarker

Observação: é possível usar tantos desses supertipos quantos forem adequados.

Lista 1. Definição de extensão de marcador a partir do plugin.xml
<extension point="org.eclipse.core.resources.markers" id="com.ibm.mymarkers.mymarker"
  name="My Marker">
	<super type="org.eclipse.core.resources.marker"/>
	<persistent value="false"/><attribute name="description"/>
</extension>

Observe, na Listagem 1, os dois elementos persistent e attribute. Eles são propriedades dadas ao marcador mymarker . Persistent indica se os marcadores devem ser armazenados dentro do espaço de trabalho. Há também um novo atributo description dado ao mymarker.

Usar o novo marcador

É possível criar um marcador chamando o método createMarker no recurso desejado. Você também pode desejar definir seus atributos.

O método mostrado na Listagem 2 também pode ser usado para criar um marcador. Sua única entrada requerida é o IResource que vincula ao marcador. Uma vez criado, é possível definir seus atributos.

Lista 2. Código Java criando o novo tipo de marcador
public static IMarker createMarker(IResource res)
throws CoreException {
       IMarker marker = null;
       //note: you use the id that is defined in your plugin.xml
       marker = res.createMarker("com.ibm.mymarkers.mymarker");
       marker.setAttribute("description," "this is one of my markers");
       //note: you can also use attributes from your supertype
       marker.setAttribute(IMarker.MESSAGE, "My Marker");
       return marker;
}

Localize seu marcador

Para localizar os marcadores associados a um IResource , é possível consultar um recurso para obter todos os marcadores do ID específico e marcar se deseja procurar os recursos relacionados. Para procurar marcadores, chame o método findMarkers no recurso. Especifique os argumentos, como o tipo de marcador e a profundidade da procura.

O código na Listagem 3 descobre os marcadores diretamente vinculados ao recurso usando o argumento IResource.DEPTH_ZERO .

Lista 3. Código Java descobrindo o novo tipo de marcador
public static final String MARKER = "com.ibm.mymarkers.mymarker";

public static List<IMarker> findMarkers(IResource resource) {
        try {
               return Arrays.asList(resource.findMarkers(MARKER, true,
	IResource.DEPTH_ZERO));
        } catch (CoreException e) {
               return new ArrayList<IMarker>();
        }
    }

Alterar a profundidade de recurso para IResource.DEPTH_INFINITE retornará todos os marcadores relacionados a este ou quaisquer subrecursos. Por exemplo, é possível passar um pacote e obter todos os marcadores vinculados aos recursos desse pacote.


Parte 2: Exibir e atualizar marcadores usando anotações

O que é uma anotação?

Anotações são usadas para marcar uma área de texto dentro de um editor. São amplamente usadas no Eclipse para exibir informações como erros, avisos, problemas de compilação, tarefas ou pontos de interrupção. Anotações são visíveis nas réguas do editor e no texto. A Figura 1 mostra uma anotação exibindo um erro de sintaxe.

Figura 1. Exemplo de uma anotação
Exemplo de uma anotação

Implementações comuns de anotações geram marcas durante a análise do arquivo e seleção de elementos como erros e tags "todo". Isso normalmente é concluído no tempo de desenvolvimento. Outras são vinculadas a marcadores persistentes, como pontos de interrupção. Este exemplo usa um marcador persistente.

A maneira como o usuário visualiza as anotações pode ser personalizada no painel de preferências sob General > Editors > Text Editors > Annotations. Isso significa que nenhum trabalho adicional é necessário para permitir customização do usuário das anotações.

Figura 2. Uma captura de tela do painel de preferências de anotação
Uma captura de tela do painel de preferências de anotação

Clique para ver a imagem maior

Figura 2. Uma captura de tela do painel de preferências de anotação

Uma captura de tela do painel de preferências de anotação

As propriedades do ponto de extensão do marcador

Na Parte 1 deste tutorial, o marcador apenas estendeu o tipo de marcador padrão. Na Parte 2, estenderemos o tipo de marcador de texto de modo que seja possível marcar um local do texto. Esse tipo define dois atributos-chave: charStart e charEnd. Também queremos que o marcador persista entre as sessões, então mudamos o valor de persistent para true. Para fazer isso, é preciso atualizar o marcador conforme definido na Listagem 4.

Lista 4. Definição de extensão de marcador a partir do plugin.xml
<extension point="org.eclipse.core.resources.markers" id="com.ibm.mymarkers.mymarker"
  name="My Marker">
	<super type="org.eclipse.core.resources.textmarker"/>
	<super type="org.eclipse.core.resources.marker"/>
	<persistent value="true"/>
</extension>

Defina sua extensão de especificação de anotação

Para criar suas próprias anotações, use o ponto de extensão org.eclipse.ui.editors.markerAnnotationSpecification. (Consulte Listagem 5.) Isso define as propriedades da anotação e suas opções de exibição padrão.

Lista 5. Definição de extensão de anotação a partir do plugin.xml
<extension point="org.eclipse.ui.editors.markerAnnotationSpecification"
		id="myannotationspecification" name="MyAnnotation">
	<specification annotationType="com.ibm.example.myannotation"
			label="MyAnnotation"
			icon="icons/sample.gif"
			overviewRulerPreferenceKey="clruler"
			overviewRulerPreferenceValue="true"
			colorPreferenceKey="clcolor"
			colorPreferenceValue="255,255,0"
			textPreferenceKey="cltext"
			textPreferenceValue="true"
			verticalRulerPreferenceKey="clvertical"
			verticalRulerPreferenceValue="true"
			textStylePreferenceKey="clstyle"
			textStylePreferenceValue="BOX">
	</specification>
</extension>

As partes do XML que serão usadas para vincular à especificação são os atributos ID e annotationType . O Eclipse.org documenta os outros atributos que serão usados para personalização (consulte Recursos).

A próxima etapa é vincular o marcador existente à nova especificação de anotação usando o ponto de extensão org.eclipse.ui.editors.annotationTypes. Vinculamos a especificação usando o tipo de anotação da especificação e o id da definição do marcador.

Lista 6. Definição de tipo de anotação a partir do plugin.xml

Clique aqui para ver lista de códigos

Lista 6. Definição de tipo de anotação a partir do plugin.xml

<extension point="org.eclipse.ui.editors.annotationTypes">
                <type markerSeverity="0"
                                        super="org.eclipse.ui.workbench.texteditor.info"
                                        name="com.ibm.example.myannotation"markerType="com.ibm.mymarkers.mymarker"/>
</extension>

Consulte Recursos para encontrar mais informações sobre o ponto de extensão a partir do Eclipse.org.

Criar e adicionar uma anotação ao editor

O código na Listagem 7 é usado para criar e adicionar a anotação a um editor.

Lista 7. Adicionar uma nova anotação ao editor
public static void addAnnotation(IMarker marker, ITextSelection selection,
							ITextEditor editor) {
      //The DocumentProvider enables to get the document currently loaded in the editor
      IDocumentProvider idp = editor.getDocumentProvider();

      //This is the document we want to connect to. This is taken from
      //the current editor input.
      IDocument document = idp.getDocument(editor.getEditorInput());

      //The IannotationModel enables to add/remove/change annotation to a Document
      //loaded in an Editor
      IAnnotationModel iamf = idp.getAnnotationModel(editor.getEditorInput());

      //Note: The annotation type id specify that you want to create one of your
      //annotations
      SimpleMarkerAnnotation ma = new SimpleMarkerAnnotation(
				“com.ibm.example.myannotation”,marker);

      //Finally add the new annotation to the model
      iamf.connect(document);
      iamf.addAnnotation(ma,newPosition(selection.getOffset(),selection.getLength()));
      iamf.disconnect(document);
}

Manter o marcador e a anotação em sincronia

O modelo de anotação cuida do movimento da anotação quando o documento é editado. Porém, ele não atualiza os atributos do marcador quando a anotação se move. Neste caso, queremos atualizar os atributos charStart e charEnd do marcador. Esse último ponto de extensão é o atualizador do marcador. Ele define uma classe usada para atualizar os marcadores quando a anotação se move.

Lista 8. Definição do atualizador do marcador a partir do plugin.xml
<extension point="org.eclipse.ui.editors.markerUpdaters">
               <updater
                       id="com.ibm.example.MarkerUpdater"
                       class="com.ibm.example.mymarker.MarkerUpdater"
                       markerType="com.ibm.mymarkers.mymarker">
               </updater>
</extension>:

Usamos a interface IMarkerUpdater para fornecer o código que queremos executar quando a anotação é movida. A classe mostrada na Listagem 9 é o atualizador de marcador. O código em que estamos interessados está no método updateMarker . Aqui estamos usando-o para atualizar os atributos charStart e charEnd do marcador.

Lista 9. Código do atualizador do marcador
public class MarkerUpdater implements IMarkerUpdater {
       /*
       *Returns the attributes for which this updater is responsible.
       *If the result is null, the updater assumes responsibility for any attributes.
       */
       @Override
       public String[] getAttribute() {
            return null;
       }

       @Override
       public String getMarkerType() {
             //returns the marker type that we are interested in updating
            return "com.ibm.mymarkers.mymarker";
       }

       @Override
       public boolean updateMarker(IMarker marker, IDocument doc, Position position) {
             try {
                 int start = position.getOffset();
                   int end = position.getOffset() + position.getLength();
                   marker.setAttribute(IMarker.CHAR_START, start);
                   marker.setAttribute(IMarker.CHAR_END, end);
                   return true;
             } catch (CoreException e) {
                   return false;
             }
       }
}

O que são decoradores?

Dentro do Eclipse, os decoradores são usados para adicionar informações visuais a objetos no ambiente de trabalho. Normalmente, exibem o tipo de objeto e quaisquer propriedades-chave atualmente associadas ao objeto. A Figura 3 mostra como os decoradores são exibidos no Package Explorer para o usuário. Os decoradores mostram quais itens são arquivos ou pacotes de origem Java e mostra os ícones do marcador para origens e pacotes que contêm avisos ou erros. Aqui, os decoradores também são usados para adicionar detalhes da equipe, como se os arquivos estão dentro ou fora de sincronia com o repositório.

Figura 3. Pacotes e origens decorados com ícones simbólicos
Pacotes e origens decorados com ícones simbólicos

Defina seu próprio decorador

A primeira etapa para adicionar o decorador é estender o ponto de extensão org.eclipse.ui.decorators . Isso permite a definição de um novo decorador e seleciona qual tipo de objeto ele irá decorar.

Os campos importantes aqui são:

  • classe, — que deve ser o nome totalmente qualificado de um a classe que implementa ILightweightLabelDecorator (uma vez que lightweight está definido para true).
  • ativação, — que contém a lista de objetos Eclipse aplicada ao decorador.
Lista 10. Definição de decorador a partir do plugin.xml
<extension point="org.eclipse.ui.decorators">
	<decorator   id="com.ibm.example.filedecorator"
			label="MyMarker Decorator"
			state="true"
			class= "com.ibm.example.mymarker.FileDecorator"
			adaptable="true"
			lightweight="true">
		<enablement>
			<objectClass name="org.eclipse.core.resources.IResource"/>
		</enablement>
	</decorator>
</extension>

Consulte Recursos para obter mais documentação sobre ponto de extensão a partir de Eclipse.org.

Observação: leve vs. não leve: de acordo com a API, decoradores leves podem ser descontinuados em versões futuras do Eclipse.

Nossa classe do decorador de arquivo

Precisamos implementar a classe FileDecorator para determinar o comportamento do nosso decorador. Essa classe precisa implementar ILightweightLabelDecorator. É uma boa ideia fazer com que estenda LabelProvider , uma vez que isso permitirá apenas substituir o método no qual estamos interessados, ou seja, decorate().

Uma implementação básica de decorate() é mostrada na Listagem 11.

Lista 11. Implementação básica de decorate()
public void decorate(Object resource, IDecoration decoration)  {
	decoration.addOverlay(ImageDescriptor.createFromFile(FileDecorator.class,
					"/icons/sample.gif"), IDecoration.TOP_RIGHT);
	decoration.addPrefix("My Prefix ");
	decoration.addSuffix(" My Suffix");
}

O objeto IDecoration também permite a customização da fonte e da cor do texto/plano de fundo.

Figura 4. Uma captura de tela do código na Listagem 11 decorando IResources
Uma captura de tela do código na Listagem 11 decorando IResources

O primeiro argumento de decorate() pode ser usado para filtrar os recursos que queremos decorar. Se o objetivo é apenas decorar recursos que contenham marcadores específicos, o código exemplificado na Listagem 12 é usado.

Lista 12. Decorar recursos com marcadores específicos
public void decorate(Object resource, IDecoration decoration) {
	if(resource instanceof IResource){
		List<IMarker> markers = MyMarkerFactory.findMarkers((IResource) resource);
		if (markers.size() > 0) {
			decoration.addSuffix("  Marker !!");
		}
	}
}

Você acompanhou este tutorial, o que vem a seguir?

Melhorias avançadas podem incluir:

  • Adicionar propriedades editáveis a marcadores. Permita ao usuário alterar o estado dos marcadores
  • Automatizar a criação e a exclusão dos marcadores. Use tarefas de processamento em segundo plano para criar, atualizar e excluir marcadores automaticamente.
  • Customizar a ajuda instantânea do marcador. Use ajuda instantânea avançada de marcador para fornecer suporte a HTML ou conteúdo multimídia.

Neste tutorial, usamos o Eclipse para criar e customizar com facilidade marcadores e realizar marcação avançada de recursos. Os desenvolvedores são incentivados a usar essa ferramenta simples, mas eficiente, para integrar com perfeição seus plug-ins no ambiente de desenvolvimento integrado do Eclipse. Tenha em mente, no entanto, que esse recurso pode tornar-se inconveniente para o usuário e implementado muito amplamente. Além disso, é responsabilidade do desenvolvedor manter o visual e a experiência do Eclipse levando em consideração as Diretrizes de Interface com o Usuário do Eclipse, consulte Recursos.


Downloads

DescriçãoNomeTamanho
Code from Part 1Marker.zip13KB
Code from Part 2Annotation.zip16.3KB
Code from Part 3Decorator.zip18.2KB

Recursos

Aprender

Obter produtos e tecnologias

  • O Eclipse Marketplace é um portal conveniente em que é possível encontrar ofertas comerciais e de software livre relacionadas ao Eclipse. Se você fizer o download do Indigo por meio de um pacote, terá acesso ao cliente Eclipse Marketplace.

Discutir

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Tecnologia Java, Software livre
ArticleID=768910
ArticleTitle=Melhores práticas para desenvolver plug-ins do Eclipse
publish-date=11032011