Java Anotações

As anotações Java fornecem informações sobre o código. As anotações Java não têm efeito direto sobre o código que elas anotam. No tutorial de anotações Java, vamos examinar o seguinte;

1. Anotações Java integradas
2. Como escrever Anotação Personalizada
3. Uso de anotações e como analisá-las usando API de Reflexão .

Anotações Java

O Java 1.5 introduziu anotações e agora é amplamente utilizado em frameworks Java EE como Hibernate, Jersey e Spring. A Anotação Java é metadados sobre o programa incorporados no próprio programa. Pode ser analisado pela ferramenta de análise de anotações ou pelo compilador. Também podemos especificar a disponibilidade da anotação apenas para o tempo de compilação ou até o tempo de execução. Antes das anotações Java, os metadados do programa estavam disponíveis por meio de comentários Java ou pelo Javadoc, mas a anotação oferece mais do que isso. Os metadados das anotações também podem estar disponíveis em tempo de execução e os analisadores de anotações podem usá-los para determinar o fluxo do processo. Por exemplo, no webservice Jersey, adicionamos a anotação PATH com uma string URI a um método e, em tempo de execução, o Jersey a analisa para determinar o método a ser invocado para o padrão de URI fornecido.

Anotação Personalizada Java

Criar uma anotação personalizada é semelhante a escrever uma interface, exceto que a palavra-chave da interface é prefixada com o símbolo _@_. Podemos declarar métodos na anotação. Vamos ver um exemplo de anotação personalizada em Java e depois discutiremos suas características e pontos importantes.

package com.journaldev.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface MethodInfo{
	String author() default "Pankaj";
	String date();
	int revision() default 1;
	String comments();
}

Alguns pontos importantes sobre as anotações em Java são:

1. Os métodos de anotação não podem ter parâmetros.
2. Os tipos de retorno dos métodos de anotação estão limitados a primitivos, String, Enums, Annotation ou array destes.
3. Os métodos de anotação em Java podem ter valores padrão.
4. As anotações podem ter meta-anotações anexadas a elas. Meta-anotações são usadas para fornecer informações sobre a anotação.

Meta-anotações em Java

Há cinco tipos de meta-anotações:

1. @Documented – indica que elementos que usam esta anotação devem ser documentados pelo javadoc e ferramentas similares. Este tipo deve ser usado para anotar as declarações de tipos cujas anotações afetam o uso de elementos anotados por seus clientes. Se uma declaração de tipo for anotada com Documented, suas anotações se tornam parte da API pública dos elementos anotados.
2. @Alvo – indica os tipos de elementos do programa aos quais um tipo de anotação é aplicável. Alguns valores possíveis são TYPE, METHOD, CONSTRUCTOR, FIELD, etc. Se a meta-anotação Alvo não estiver presente, então a anotação pode ser usada em qualquer elemento do programa.
3. @Herdado – indica que um tipo de anotação é automaticamente herdado. Se o usuário consultar o tipo de anotação em uma declaração de classe e a declaração de classe não tiver uma anotação para esse tipo, a superclasse da classe será consultada automaticamente para o tipo de anotação. Esse processo será repetido até que uma anotação para esse tipo seja encontrada ou que o topo da hierarquia de classes (Object) seja alcançado.
4. @Retenção – indica por quanto tempo as anotações com o tipo anotado devem ser retidas. Ela recebe um argumento RetentionPolicy, cujos valores possíveis são SOURCE, CLASS e RUNTIME
5. @Repetível – usado para indicar que o tipo de anotação cuja declaração está sendo anotada é repetível.

Anotações integradas em Java

O Java fornece cinco anotações integradas.

1. @Override – Quando queremos substituir um método da Superclasse, devemos usar esta anotação para informar ao compilador que estamos substituindo um método. Assim, quando o método da superclasse é removido ou alterado, o compilador mostrará uma mensagem de erro. Aprenda por que devemos sempre usar a anotação de substituição de java ao substituir um método.
2. @Deprecated – quando queremos que o compilador saiba que um método está obsoleto, devemos usar esta anotação. O Java recomenda que no javadoc, devemos fornecer informações sobre por que este método está obsoleto e qual é a alternativa a ser usada.
3. @SuppressWarnings – Isso é apenas para dizer ao compilador para ignorar avisos específicos que ele produz, por exemplo, usar tipos crus em genéricos java. Sua política de retenção é SOURCE e é descartada pelo compilador.
4. @FunctionalInterface – Esta anotação foi introduzida no Java 8 para indicar que a interface se destina a ser uma interface funcional.
5. @SafeVarargs – Uma afirmação do programador de que o corpo do método ou construtor anotado não executa operações potencialmente inseguras em seu parâmetro varargs.

Exemplo de Anotações em Java

Vamos ver um exemplo em Java que mostra o uso de anotações embutidas em Java, bem como o uso de uma anotação personalizada criada por nós no exemplo acima.

package com.journaldev.annotations;

import java.io.FileNotFoundException;
import java.util.ArrayList;
import java.util.List;

public class AnnotationExample {

	public static void main(String[] args) {
	}

	@Override
	@MethodInfo(author = "Pankaj", comments = "Main method", date = "Nov 17 2012", revision = 1)
	public String toString() {
		return "Overriden toString method";
	}

	@Deprecated
	@MethodInfo(comments = "deprecated method", date = "Nov 17 2012")
	public static void oldMethod() {
		System.out.println("old method, don't use it.");
	}

	@SuppressWarnings({ "unchecked", "deprecation" })
	@MethodInfo(author = "Pankaj", comments = "Main method", date = "Nov 17 2012", revision = 10)
	public static void genericsTest() throws FileNotFoundException {
		List l = new ArrayList();
		l.add("abc");
		oldMethod();
	}

}

I believe above java annotation example is self-explanatory and showing the use of annotations in different cases.

Análise de Anotações em Java

Vamos usar Reflection para analisar as anotações em Java de uma classe. Por favor, note que a Política de Retenção da Anotação deve ser RUNTIME, caso contrário, suas informações não estarão disponíveis em tempo de execução e não poderemos recuperar nenhum dado dela.

package com.journaldev.annotations;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

public class AnnotationParsing {

	public static void main(String[] args) {
		try {
			for (Method method : AnnotationParsing.class.getClassLoader()
					.loadClass(("com.journaldev.annotations.AnnotationExample")).getMethods()) {
				// verifica se a anotação MethodInfo está presente no método
				if (method.isAnnotationPresent(com.journaldev.annotations.MethodInfo.class)) {
					try {
						// itera todas as anotações disponíveis no método
						for (Annotation anno : method.getDeclaredAnnotations()) {
							System.out.println("Annotation in Method '" + method + "' : " + anno);
						}
						MethodInfo methodAnno = method.getAnnotation(MethodInfo.class);
						if (methodAnno.revision() == 1) {
							System.out.println("Method with revision no 1 = " + method);
						}

					} catch (Throwable ex) {
						ex.printStackTrace();
					}
				}
			}
		} catch (SecurityException | ClassNotFoundException e) {
			e.printStackTrace();
		}
	}

}

O resultado do programa acima é:

Annotation in Method 'public java.lang.String com.journaldev.annotations.AnnotationExample.toString()' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=1, comments=Main method, date=Nov 17 2012)
Method with revision no 1 = public java.lang.String com.journaldev.annotations.AnnotationExample.toString()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.oldMethod()' : @java.lang.Deprecated()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.oldMethod()' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=1, comments=deprecated method, date=Nov 17 2012)
Method with revision no 1 = public static void com.journaldev.annotations.AnnotationExample.oldMethod()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.genericsTest() throws java.io.FileNotFoundException' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=10, comments=Main method, date=Nov 17 2012)

A API de Reflection é muito poderosa e amplamente utilizada em Java, frameworks J2EE como Spring, Hibernate, JUnit, confira Reflection em Java. Isso é tudo para o tutorial de exemplo de anotações em Java, espero que você tenha aprendido algo com isso. Atualizações de Anotações em Java:

1. Especificações do Servlet 3.0 introduziram o uso de anotações para Configuração de Servlet e parâmetros de inicialização, leia mais em Tutorial do Java Servlet.
2. Podemos usar anotações no Struts 2 para configurar suas classes de ação e páginas de resultado, confira um exemplo funcional em Exemplo de Anotação Struts 2 Hello World.

Referência: Site da Oracle