Como criar Anota��es em Java

Neste artigo veremos dois assuntos muito importantes e interessantes no mundo Java: as anotaç�es e o recurso de reflex�o (reflection). Nosso intuito ser� criar uma anotaç�o �til para determinada tarefa na codificaç�o de nosso sistema, mas fazer isso n�o � poss�vel sem que tenhamos o conhecimento de reflection.

Estudaremos as teorias de ambos os conceitos e posteriormente veremos como aplicar tais recursos.

Reflection

Ao desenvolver um software conseguimos definir diversos recursos de forma est�tica, como usar m�todos de classes j� criada, definir atributos tamb�m previamente criados e etc. Na maioria das vezes, isso � suficiente para a construç�o de um projeto, mas h� exceç�es e � exatamente elas que estudaremos.

Pense em como � poss�vel o framework Hibernate saber que nossa classe Cliente tem um m�todo setNome() se na codificaç�o dele com certeza n�o h� nenhuma refer�ncia a esta classe? Lembre-se que os desenvolvedores do Hibernate ou qualquer outro framework jamais imaginaram que voc� precisaria usar a classe Cliente. Eles desenvolveram tal recurso da forma mais gen�rica poss�vel afim de adaptar-se a qualquer regra de neg�cio.

A resposta para esta pergunta �: Reflection, j� que seu uso � comumente aplicado a muitos frameworks afim de tornar o mesmo plug�vel, tais como: Hibernate, Spring, CDI e etc. O pacote javax.reflection possibilita que sejam feitas chamadas a m�todos, atributos e etc. em tempo de execuç�o, ou seja, conseguimos instanciar uma classe sem saber qual � a classe. Mas como isso � poss�vel?

Primeiro vamos construir um Java Bean que ser� utilizada durante todo nosso artigo com uma classe simples chamada Cliente com seus atributos e m�todos de acesso (getters e setters), como mostra a Listagem 1.


  import java.util.Date;
   
   
  public class Cliente {
         
         private String nome;
         private int codigo;
         private Date dataNascimento;
         private String nomePai;
         private String nomeMae;
         private String enderecoCompleto;
         public String getNome() {
               return nome;
         }
         public void setNome(String nome) {
               this.nome = nome;
         }
         public int getCodigo() {
               return codigo;
         }
         public void setCodigo(int codigo) {
               this.codigo = codigo;
         }
         public Date getDataNascimento() {
               return dataNascimento;
         }
         public void setDataNascimento(Date dataNascimento) {
               this.dataNascimento = dataNascimento;
         }
         public String getNomePai() {
               return nomePai;
         }
         public void setNomePai(String nomePai) {
               this.nomePai = nomePai;
         }
         public String getNomeMae() {
               return nomeMae;
         }
         public void setNomeMae(String nomeMae) {
               this.nomeMae = nomeMae;
         }
         public String getEnderecoCompleto() {
               return enderecoCompleto;
         }
         public void setEnderecoCompleto(String enderecoCompleto) {
               this.enderecoCompleto = enderecoCompleto;
         }      
   
  }

Listagem 1. Classe Cliente

S�o tr�s os recursos que o reflection possibilita que acessar em tempo de execuç�o: Class, Field e Method. Com estes tr�s voc� consegue fazer tudo que precisa com qualquer tipo de classe. Primeiro vamos aprender um pouco sobre os m�todos que o reflection fornece e depois usaremos como exemplo o bean criado na Listagem 1 para resolver problemas reais. Observe a Listagem 2.


public static void main(String[] args) {
     Cliente cliente = new Cliente();
     System.out.println(cliente.getClass().getName());

  }

Sa�da: Cliente

Listagem 2. Usando getClass()

O primeiro m�todo � o getClass() e com ele n�s capturamos a classe do objeto cliente, que no nosso caso � a classe Cliente. O getClass() retorna um objeto Class, que possui muitos m�todos para manipularmos a classe Cliente, tais como: getName(), getModifiers, getConstructor e etc.

Usamos acima um objeto para retornar a classe dele, mas poder�amos usar a pr�pria classe Cliente para obter essas informaç�es, da mesma forma que a apresentada na Listagem 3.


public static void main(String[] args) {
     Cliente cliente = new Cliente();
     System.out.println(Cliente.class.getName());
}

Listagem 3. Usando Cliente.class

Com a Class em m�os podemos começar a destrinchar os recursos contidos dentro dela como, por exemplo: atributos, m�todos, modificadores, construtores e etc. Vamos ver o nome de todos os atributos na Listagem 4.


public static void main(String[] args) {
       Cliente cliente = new Cliente();
       Class<Cliente> clazz = (Class<Cliente>) cliente.getClass();
       for(Field f : clazz.getDeclaredFields()){
              System.out.println(f.getName());
       }

   }

Sa�da:
nome
codigo
dataNascimento
nomePai
nomeMae
enderecoCompleto

Listagem 4. Capturando o nome dos atributos da classe Cliente

O m�todo getDeclaredFields() retorna um array de Field, onde Field � a classe utilizada para manipular os atributos presentes na classe que estamos trabalhando. Podemos aplicar a mesma l�gica para os m�todos, como mostra a Listagem 5.


   public static void main(String[] args) {
         Cliente cliente = new Cliente();
         Class<Cliente> clazz = (Class<Cliente>) cliente.getClass();
         for(Method m : clazz.getDeclaredMethods()){
                System.out.println(m.getName());
         }

   }
   
  Sa�da:
  getNome
  setNome
  getCodigo
  setCodigo
  getDataNascimento
  setDataNascimento
  getNomePai
  setNomePai
  getNomeMae
  setNomeMae
  getEnderecoCompleto
  setEnderecoCompleto

Listagem 5. Capturando o nome dos m�todos da classe Cliente

Como poder�amos criar um m�todo gen�rico para instanciar/criar todo tipo de objeto, independente da sua classe? Imagine que n�s n�o saibamos qual a classe que deve-se instanciar, ent�o n�o podemos usar a palavra reservada �new MinhaClass()�. Precisamos apenas disponibilizar um m�todo onde seja passada a classe, atrav�s do MinhaClasse.class, e neste m�todo seja feita a instanciaç�o e o retorno seja o objeto desejado. Observe a Listagem 6.


private static Object createNewInstance(Class clazz) {
     Constructor<?> ctor;
     try {
            ctor = clazz.getConstructors()[0];
            Object object = ctor.newInstance();
            return object;
     } catch (SecurityException
                   | InstantiationException | IllegalAccessException
                   | IllegalArgumentException | InvocationTargetException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
     }
     
     return null;
}

Listagem 6. Criando um m�todo gen�rico para instanciar Classes com reflection

O m�todo createNewInstance � respons�vel por retornar uma inst�ncia de Class, independente do seu tipo. O que fazemos � utilizar o �clazz� para capturar o primeiro construtor encontrado, que � o vazio. Ap�s capturar este n�s chamamos o m�todo newInstance(), que retorna um objeto do tipo �clazz�. Algumas exceç�es s�o obrigat�rias, por isso colocamos o bloco try-catch e adicionamos cinco exceç�es requeridas, ou checked exceptions.

Vejamos como utilizar o m�todo disposto na Listagem 6 com o c�digo da Listagem 7.


public static void main(String[] args) {
     Cliente cliente = (Cliente) createNewInstance(Cliente.class);

     if (cliente == null) {
            System.err.println("Ops, n�o foi poss�vel criar o objeto cliente");
     } else {
            System.out.println("Objeto cliente criado = " + cliente.toString());
     }

}
Sa�da:
Objeto cliente criado = Cliente@5f67198e

Listagem 7. Usando o createnewinstance

Observe que em nenhum momento usamos �new Cliente()�, pois o m�todo createnewinstance nem sabe que a classe Cliente existe. Ele s� saber� disso em tempo de execuç�o.

Agora fica mais claro entender como os frameworks atuais conseguem �ler� a sua classe sem ter digitado uma linha de c�digo sobre ela, repare que nada foi implementado especificamente para classe Cliente.

Anotaç�es

Anotaç�es s�o metadados, disponibilizados a partir do Java 5, para �configurar� determinados recursos que antes deveriam ser feitos em arquivos separados como, por exemplo, no XML.

Voc� diariamente deve usar diversas anotaç�es, tais como @Override, @Deprecated, @Entity, @Table, @Column e etc. Se voc� tenta usar o @Override em um m�todo que n�o tem um semelhante na classe pai, ent�o voc� ver� um erro em tempo de design, e isso s� � poss�vel porque o Java usa o reflection para checar se existe um m�todo com a mesma assinatura na classe pai, caso contr�rio, o @Override n�o ser� aceito.

Nesta seç�o vamos criar nossa pr�pria anotaç�o, que ter� por objetivo anotar os m�todos que devem ser mostrados no console, assim entenderemos como funciona a criaç�o de anotaç�es. Para n�o confundir começaremos anotando nossos m�todos com @Mostrar, como mostra a Listagem 8.


import java.util.Date;
 
 
public class Cliente {
       
     private String nome;
     private int codigo;
     private Date dataNascimento;
     private String nomePai;
     private String nomeMae;
     private String enderecoCompleto;
     
     @Mostrar
     public String getNome() {
           return nome;
     }
     
     public void setNome(String nome) {
           this.nome = nome;
     }
     

     @Mostrar
     public int getCodigo() {
           return codigo;
     }
     
     public void setCodigo(int codigo) {
           this.codigo = codigo;
     }
     
     @Mostrar
     public Date getDataNascimento() {
           return dataNascimento;
     }
     
     
     public void setDataNascimento(Date dataNascimento) {
           this.dataNascimento = dataNascimento;
     }
     
     public String getNomePai() {
           return nomePai;
     }
     
     public void setNomePai(String nomePai) {
           this.nomePai = nomePai;
     }
     
     public String getNomeMae() {
           return nomeMae;
     }
     
     public void setNomeMae(String nomeMae) {
           this.nomeMae = nomeMae;
     }
     

     @Mostrar
     public String getEnderecoCompleto() {
           return enderecoCompleto;
     }
     
     public void setEnderecoCompleto(String enderecoCompleto) {
           this.enderecoCompleto = enderecoCompleto;
     }      
 
}

Listagem 8. Anotando nossos m�todos com @Mostrar

Inicialmente voc� ver� o seguinte erro:�Mostrar cannot be resolved to a type�. Isso ocorre porque nossa anotaç�o n�o foi criada ainda e para fazermos isso seguimos o c�digo a seguir:


public @interface Mostrar {
  }

A partir do momento que a anotaç�o Mostrar for criada o erro da Listagem 8 desaparecer� e voc� conseguir� compilar o c�digo. O Java optou por usar @interface como recurso para anotaç�es, pois os arquitetos da linguagem preferiram n�o criar uma nova palavra reservada apenas para anotaç�o, algo como: public Annotation Mostrar{}.

Agora precisamos definir dois atributos importantes para nossa anotaç�o:

Que tipo de estrutura ela pode anotar? M�todos, Classes, atributos, construtores, pacotes e etc.?
Para isso usamos @Target(ElementType.METHOD) quando desejamos especificar que nossa anotaç�o servir� apenas para m�todos, ou @Taget(ElementType.FIELD) para anotar atributos, e assim por diante.
A anotaç�o serve apenas em tempo de compilaç�o ou execuç�o? Um exemplo disto � a anotaç�o @Override, que serve apenas em tempo de compilaç�o, pois o Java ir� checar se aquele m�todo existe na classe pai, caso contr�rio, o c�digo nem chegar� a ser compilado. J� a nossa anotaç�o @Mostrar ser� usada apenas em tempo de execuç�o, pois quando estivermos lendo os m�todos da classe Cliente verificaremos se este foi anotado com @Mostrar, caso contr�rio, ignoraremos ele. Para isso usaremos: @Retention(RetentionPolicy.RUNTIME).

Veja como ficou nossa anotaç�o final na Listagem 9.


  import java.lang.annotation.ElementType;
  import java.lang.annotation.Retention;
  import java.lang.annotation.RetentionPolicy;
  import java.lang.annotation.Target;
   
   
  @Target(ElementType.METHOD)
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Mostrar {
         
  }

Listagem 9. Anotaç�o @Mostrar completa

Agora sim estamos prontos para o �ltimo passo, que � fazer uso da anotaç�o @Mostrar com o reflection. Nosso objetivo ser� popular o objeto cliente com alguns dados e depois pass�-lo para um m�todo onde os valores anotados com @Mostrar ser�o mostrados no console. Por exemplo, o getNome() mostrar� o nome do cliente e assim por diante, como mostra a Listagem 10.


  // Mostra valores apenas com anotaç�o @Mostrar
    public static void mostrarValores(Object obj) {
         try {
                Class clazz = obj.getClass();
                for (Method m : clazz.getDeclaredMethods()) {
                       if (m.isAnnotationPresent(Mostrar.class)){
                              System.out.println(m.getName()+": "+m.invoke(obj));
                       }
                }
         } catch (IllegalAccessException | IllegalArgumentException
                       | InvocationTargetException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
         }
    }

Listagem 10. Mostrando m�todo com anotaç�es @Mostrar

O m�todo mostrarValores() recebe o objeto que queremos manipular. Logo em seguida, capturamos a classe desse objeto. De posse da classe n�s capturamos todos os m�todos desse objeto, pois sabemos que a anotaç�o @Mostrar s� pode ser usada em m�todos.

Fazendo uma iteraç�o nos m�todos do objeto passado, n�s precisamos verificar se aquele determinado m�todo possui a anotaç�o @Mostrar, e para fazer isso usamos o seguinte c�digo:


m.isAnnotationPresent(Mostrar.class)

O isAnnotationPresent() verifica se aquele determinado m�todo possui a anotaç�o passada como par�metro, no nosso caso, Mostrar.class. Se isso for verdade, podemos executar o m�todo. Mas como fazemos isso?

Uma aç�o muito interessante da classe Method � o invoke(), que lhe possibilita chamar um m�todo atrav�s do reflection, e � exatamente ele que usamos para chamar o getNome(), getCodigo() e etc., como mostra o c�digo a seguir:


System.out.println(m.getName()+": "+m.invoke(obj));

O invoke() retorna um object, por ser a classe de mais alta hierarquia, e podemos fazer cast para qualquer outra. Isso significa que nosso m�todo pode retornar um inteiro, double, string, char, list, set e etc.

Conseguiu entender o que ir� acontecer ap�s chamarmos o invoke()? Apenas os valores marcados com @Mostrar ser�o mostrados no console, assim como desejamos.

Vamos ver um exemplo pr�tico disto na Listagem 11.


  public static void main(String[] args) {
     Cliente cliente = new Cliente();
     cliente.setCodigo(1010);
     cliente.setDataNascimento(new Date());
      cliente.setEnderecoCompleto("Rua ABC, Bairro YHU n� 190");
     cliente.setNome("Antonio da Silva Nunes");
     cliente.setNomeMae("Maria da Silva Nunes");
     cliente.setNomePai("Joao da Silva Nunes");
     
     mostrarValores(cliente);
  }
   
  Sa�da:
   
  getNome: Antonio da Silva Nunes
  getCodigo: 1010
  getDataNascimento: Thu Mar 12 21:04:33 BRT 2015
  getEnderecoCompleto: Rua ABC, Bairro YHU n� 190

Listagem 11. Usando o m�todo mostrarValores()

Imagine o mundo de possibilidades que se abre quando aprendemos a usar o reflection, principalmente para quem quer trabalhar com reusabilidade em larga escala, construindo API's respons�veis por acoplar-se em qualquer projeto.

Vale atentar que dada nossa l�gica apresentada, se anotarmos um m�todo set() com o @Mostrar teremos um erro, pois o m�todo set() espera um par�metro e n�s n�o passamos nenhum par�metro no invoke(), como mostra a Listagem 12.


  @Mostrar
     public void setNome(String nome) {
           this.nome = nome;
     }

Listagem 12. Anotando o m�todo errado

Anotamos acima o setNome() com o @Mostrar, e agora vamos executar novamente a Listagem 12 e ver o resultado na Listagem 13.


java.lang.IllegalArgumentException: wrong number of arguments
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
   at java.lang.reflect.Method.invoke(Method.java:606)
   at ReflectionApp.mostrarValores(ReflectionApp.java:28)
   at ReflectionApp.main(ReflectionApp.java:19)

Listagem 13. Resultado do @Mostrar

Exatamente o que esper�vamos: wrong number of arguments.

Neste caso, o invoke() precisa receber o par�metro para o setNome() e como n�o est� recebendo, ele retorna o erro acima. E como poder�amos resolver isso?

Uma das formas poss�veis � checar no m�todo mostrarValores() se o m�todo que possui a anotaç�o @Mostrar n�o recebe nenhum par�metro, caso contr�rio, vamos mostrar uma mensagem no console e passar para o pr�ximo. Dessa forma, mesmo que seja feita uma anotaç�o errada n�o teremos muitos problemas, como mostra a Listagem 14.


// Mostra valores apenas com anotaç�o @Mostrar
public static void mostrarValores(Object obj) {
     try {
        Class clazz = obj.getClass();
        for (Method m : clazz.getDeclaredMethods()) {
           if (m.isAnnotationPresent(Mostrar.class)){
              if (m.getParameterTypes().length > 0){
                  System.err.println(" "+m.getName()+" anotado com 
                  @Mostrar de forma errada, ignorando ...");
                  continue;
              }
              System.out.println(m.getName()+": "+m.invoke(obj));
           }
        }
     } catch (IllegalAccessException | IllegalArgumentException
                   | InvocationTargetException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
     }
}

Listagem 14. Ignorando m�todos com par�metros

Adicionamos a linha �if (m.getParameterTypes().length > 0)� que ir� verificar se existe pelo menos um par�metro neste m�todo, e caso isso seja verdade, uma mensagem ser� mostrada e a iteraç�o ir� para o pr�ximo passo atrav�s do �continue�.

Este artigo teve como principal objetivo mostrar a criaç�o de uma anotaç�o simples para mostrar valores espec�ficos de um objeto, mas que por necessidade foi necess�rio explicar todo o conceito de reflection at� podermos chegar nas anotaç�es, caso contr�rio, isso n�o seria poss�vel. O uso de anotaç�es e consequentemente reflections est� diretamente ligada a construç�o principalmente de frameworks que podemos trabalhar de forma mais gen�rica poss�vel, sem se preocupar especificamente com a regra de neg�cio do desenvolvedor, mas sim com a estrutura que ele precisar

Como criar Anota��es em Java

Veja neste artigo como criar Anotações em Java e usar reflection para utilizá-la de forma adequada.

Reflection

Anotaç�es

Artigos relacionados