CKTIS / Java
Ler anotações de classe através de reflexão
Obtém as anotações repetíveis num array e verifica a presença de uma anotação marcadora. Distingue a pesquisa com herança da pesquisa limitada à declaração da classe.
Versão: Java SE 21
Sintaxe
On java.lang.Class<T> (instance methods; Annotation is java.lang.annotation.Annotation):
<A extends Annotation> A[] getAnnotationsByType(Class<A> annotationClass)
boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
<A extends Annotation> A[] getDeclaredAnnotationsByType(Class<A> annotationClass)
<A extends Annotation> A getDeclaredAnnotation(Class<A> annotationClass)
Class literals: Child.class has type Class<Child>; Tag.class has type Class<Tag>.
Example call: Child.class.getAnnotationsByType(Tag.class)O literal de classe Child.class dá-te o objeto Class<Child> a inspecionar; Tag.class dá-te o objeto Class<Tag> que identifica o tipo de anotação procurado. São métodos de instância de Class: não precisas de criar um objeto Child. Para ler por reflexão as anotações de uma declaração de classe, aplica @Retention(RetentionPolicy.RUNTIME) ao tipo de anotação.
getAnnotationsByType(Tag.class) devolve um Tag[]; se não houver correspondências, devolve um array vazio, não null. Extrai as anotações do contentor indicado por @Repeatable, mantendo a ordem dos seus elementos. Se o tipo procurado tiver @Inherited e não houver correspondências na classe, nem diretas nem no contentor, a pesquisa segue pelas superclasses, não pelas interfaces. Não junta resultados de níveis diferentes. getDeclaredAnnotationsByType também extrai as anotações do contentor, mas só verifica a classe inspecionada.
isAnnotationPresent(A.class) devolve um boolean e equivale a getAnnotation(A.class) != null. É útil para anotações marcadoras, que não têm elementos. Se não houver uma correspondência direta e o tipo procurado tiver @Inherited, consulta as superclasses, não as interfaces. Não consulta o interior do contentor: as repetições que só lá existam não fazem o teste devolver true para o tipo repetível. getDeclaredAnnotation só verifica se há uma correspondência direta na classe e devolve null se não houver.
Todos os métodos referidos que recebem um tipo de anotação lançam NullPointerException se o argumento for null. Para verificar se há pelo menos uma correspondência, incluindo as do contentor, usa getAnnotationsByType(Tag.class).length > 0.
Exemplos
import java.lang.annotation.*;
import java.util.Arrays;
public class AnnotationDemo {
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@interface Flag {}
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@Repeatable(Tags.class)
@interface Tag { String value(); }
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@interface Tags { Tag[] value(); }
@Flag
@Tag("alpha")
@Tag("beta")
static class Base {}
static class Child extends Base {}
@Tag("local")
static class Local extends Child {}
public static void main(String[] args) {
System.out.println("Child tags: " + values(Child.class.getAnnotationsByType(Tag.class)));
System.out.println("Child declared tags: " + Child.class.getDeclaredAnnotationsByType(Tag.class).length);
System.out.println("Child flag: " + Child.class.isAnnotationPresent(Flag.class));
System.out.println("Child declared flag: " + (Child.class.getDeclaredAnnotation(Flag.class) != null));
System.out.println("Base Tag present: " + Base.class.isAnnotationPresent(Tag.class));
System.out.println("Local tags: " + values(Local.class.getAnnotationsByType(Tag.class)));
}
private static String values(Tag[] tags) {
return Arrays.stream(tags).map(Tag::value).toList().toString();
}
}Resultado
Child tags: [alpha, beta] Child declared tags: 0 Child flag: true Child declared flag: false Base Tag present: false Local tags: [local]
`Child` herda `@Flag` e as duas ocorrências de `@Tag`, mas não declara nenhuma. As duas ocorrências de `@Tag` em `Base` estão no contentor `@Tags`, pelo que o teste de presença de `Tag.class` em `Base` devolve `false`. A anotação `@Tag` de `Local` substitui no resultado as ocorrências herdadas, em vez de se juntar a elas.
Lições relacionadas
- Java · Lição 58 · Avançado · Versão: 2
Fontes
- Java SE 21 API — Class.getAnnotationsByType
- Java SE 21 API — Class.isAnnotationPresent
- Java SE 21 API — Class.getDeclaredAnnotationsByType
- Java SE 21 API — Class.getDeclaredAnnotation
- Java SE 21 API — AnnotatedElement: kinds of annotation presence
- Java SE 21 API — Inherited
- Java SE 21 API — RetentionPolicy.RUNTIME
- Java Language Specification, Java SE 21 — §9.6.3 Repeatable Annotation Interfaces
- Java Language Specification, Java SE 21 — §9.7.5 Multiple Annotations of the Same Interface
- Java Language Specification, Java SE 21 — §15.8.2 Class Literals