Anotação (Java)

Em conexão com a linguagem de programação Java , a anotação é um elemento da linguagem que permite que os metadados sejam incorporados ao texto fonte . Este elemento foi definido no JSR 175 e introduzido com a versão Java 5.0.

As anotações começam com um sinal @. Isso é seguido pelo nome dela. Opcionalmente, uma lista de parâmetros separados por vírgulas, que está entre colchetes, pode vir a seguir. Por exemplo, no seguinte trecho do código-fonte, a anotação marca a classe A como obsoleta :

@Deprecated
public class A {}

Um processador de anotação é um plug-in do compilador que pode avaliar as anotações durante a compilação para suprimir ou acionar avisos e mensagens de erro ou para gerar código-fonte adicional ou outros arquivos. No entanto, ele não pode alterar o código anotado. As anotações para as quais isso se destina também podem ser avaliadas em tempo de execução usando reflexão .

As anotações são usadas, entre outras coisas, no ambiente Jakarta EE para adicionar informações às classes que precisavam ser armazenadas em arquivos separados antes do Java 5. Exemplos proeminentes são interfaces domésticas e locais, bem como descritores de implantação.

Uma técnica anterior para incorporar metadados no código-fonte Java é o uso de comentários Javadoc especiais . Estes foram avaliados com a ajuda dos chamados doclets . Uma ferramenta amplamente usada para este método é o XDoclet . Esta técnica ainda pode ser usada após a introdução das anotações.

Tipos de anotação predefinidos

No Java SE 5.0 estão disponíveis sete tipos de anotação predefinidos, nos pacotes ( pacote ) java.langou java.lang.annotationlie. Em contraste com a maioria das anotações, todas são avaliadas pelo compilador. Os programadores podem criar mais.

/**
 * @deprecated  Die Klasse A wurde mit Version 10.3 durch die Klasse ANeu ersetzt.
 */
@Deprecated
public class A {}

public class A {
    public void eineMethode() {}
}
 
public class B extends A {
    @Override
    public void eineMethode() {}
}

public class A {
    @SuppressWarnings({"deprecation"})
    public void eineMethode() {
        EineDeprecatedKlasse b = new EineDeprecatedKlasse();
    }
}

Definição de suas próprias anotações

As anotações são interfaces especiais; Portanto, de acordo com a convenção, seus nomes são escritos com letras maiúsculas. Em seu acordo está interfaceo sinal @. Eles estendem implicitamente a interface java.lang.annotation.Annotation. Eles não devem estender outras interfaces (ou seja, extendssão proibidos) e não são genéricos. Seus métodos não têm parâmetros e não são genéricos. Apenas os seguintes tipos são permitidos como tipos de resultado (tipo de retorno):

• tipos primitivos
• Tipos de enumeração ( enum)
• Tipos de anotação
• String
• Class
• Campos (matrizes) desses tipos

Eles também não lançam exceções e não têm permissão para usar recursão.

Muitas anotações não contêm nenhum método. Um exemplo seria:

@interface Vorlaeufig { }

Outras anotações contêm métodos (como é usual para interfaces), mas apenas com os tipos de resultados listados acima. Por convenção, se uma anotação contém apenas um método, seu nome é value:

@interface Test {
	boolean value(); // true solange nicht freigegeben
}

ou

@interface Autoren {
	String[] value(); // Namen der Autoren
}

ou

@interface Kunden {
	Person[] value();
}

onde Pessoa enumdeve ser definida como tipo de enumeração ( ) ou anotação, por exemplo, B.:

@interface Person {
	String name();
	int alter();
}

Ao concordar com as anotações, as anotações padrão do pacote são freqüentemente java.lang.annotationusadas. Em particular, deve ser @Retentionespecificado por quanto tempo a anotação deve ser mantida: apenas no código-fonte ( SOURCE), no arquivo de classe salvo ( CLASS) ou também na classe carregada ( RUNTIME). @Targetdescreve para quais elementos do programa a anotação pode ser usada. Por exemplo, todos os acordos de anotação são agrupados java.lang.annotationcom as anotações

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)

Erro. Como resultado, todos eles são avaliados pelo javadoc, carregados no bytecode e, portanto, podem ser avaliados em tempo de execução; além disso, eles só podem ser usados ​​para tipos de anotação.

Uso de suas próprias anotações

Uma anotação sem métodos, tais como @Vorlaeufig, pode, por exemplo, B. ser colocado na frente de uma classe:

@Vorlaeufig
class Klasse {
	void methode();
}

Uma anotação com apenas um método com o nome valuedeve receber um valor constante do tipo de resultado deste método entre colchetes:

@Test(true)
public void methode() { ... }

Se o tipo de resultado for uma matriz, um literal de matriz deve ser usado:

@Autoren({"Solymosi", "Grude"})
String buch = "Algorithmen und Datenstrukturen mit Java"

Se a matriz não contém nenhum elemento, também deve ser ({})especificado. No entanto, se a matriz contiver apenas um elemento, as chaves podem ser omitidas:

@Autoren("Solymosi")
String anderesBuch = "Programmieren in Scala"

Uma anotação com vários métodos deve receber um valor constante entre colchetes para cada um de seus métodos:

@Person(name = "Andreas Solymosi", alter = 56)
Konto konto = new Konto();

A opção de especificar o valor por nome também está disponível para anotações com um método (no entanto, é supérflua, no máximo para legibilidade):

@Test(value = true)

Uma anotação complexa (aninhada) deve ser aplicada aninhada:

@Kunden(@Person(name = "Andreas Solymosi", alter = 56))
class Unternehmen { … }

Os valores padrão podem ser definidos para os métodos no contrato de anotação; então, o valor correspondente pode ser omitido quando usado. Como as anotações são interfaces, você mesmo pode marcá-las com anotações:

@Autoren("Solymosi")
public @interface Test {
	boolean wert() default false; // muss nicht unbedingt wert heißen
}

Avaliação de anotações

Se as anotações forem carregadas com o bytecode da classe, elas podem ser avaliadas com a ajuda da reflexão. Por exemplo, você pode determinar se uma anotação foi especificada ou não:

boolean vorlaeufig = Klasse.class.isAnnotationPresent(Vorlaeufig.class);

Depois de determinar que a anotação está lá, você também pode ler seu valor, por exemplo, B. se o método ainda está no estado de teste ou não:

boolean imTestzustand = Klasse.class.getMethod("methode", new Class[]{}).getAnnotation(Test.class).value();

Se a anotação não existir aqui, getAnnotation()a exceção será NullPointerExceptionlançada. Seus elementos devem ser selecionados individualmente a partir de uma anotação complexa:

Person kunden = Unternehmen.class.getAnnotation(Kunden.class).value()[0];

Anotação de pacotes

A especificação da linguagem Java também permite que os pacotes sejam anotados, por exemplo, para fornecer documentação para um pacote. No máximo uma packagedeclaração pode ser anotada por pacote . Se um pacote deve receber anotações, a Especificação da linguagem Java recomenda a criação de um arquivo separado package-info.javano diretório deste pacote. Este arquivo contém a packagedeclaração com as anotações.

Links da web

• Anotações em Java
• Anotações no tutorial de Java da Sun
• Ferramenta de processamento de anotações (apt )
• O recurso de anotações J2SE 5.0 na Sun
• JSR 175: Um recurso de metadados para a linguagem de programação JavaTM (inglês)
• Anotações na especificação da linguagem Java (inglês)
• Anotações em "Java também é uma ilha"