Java Anotações

Uma anotação é uma etiqueta que começa com @ e fica grudada numa classe, num método ou num campo: @Override, @Deprecated, @Test. Ela não muda o que o código faz; ela informa algo sobre o código para quem vai lê-lo: o compilador, uma ferramenta ou um framework.

Você já usou @Override na aula de sobrescrita e talvez @FunctionalInterface em interfaces funcionais. Agora vamos entender o que esse @ é. Os exemplos rodaram no JDK 25 da máquina da Ana, na pasta ~/java.

A ideia antes do código

Pense nas etiquetas que a Ana cola nas caixas da loja: "FRÁGIL", "ESTE LADO PARA CIMA", "PROMOÇÃO ATÉ SEXTA". A etiqueta não muda o que tem dentro da caixa. Mas quem pega a caixa lê a etiqueta e age de acordo: o entregador carrega com cuidado; o caixa aplica o desconto.

Uma anotação é a mesma coisa no código. @Override é uma etiqueta que diz ao compilador "este método substitui um da classe mãe; confira para mim". @Deprecated diz "este método está aposentado; avise quem usar". Quem lê as etiquetas pode ser:

• o compilador (javac), na hora de compilar;
• uma ferramenta, como o Javadoc ou o IDE;
• o próprio programa ou um framework, enquanto roda, usando reflexão.

Como se escreve

A anotação fica logo antes do que ela etiqueta, normalmente na linha de cima. Pode etiquetar classes, métodos, campos, parâmetros e variáveis locais.

1. @Override: "confira que estou sobrescrevendo"

A classe Produto quer mostrar um texto bonito no println. Para isso, ela precisa sobrescrever o método toString() que herda de Object. A Ana digitou o nome com um s minúsculo:

class Produto {
    String nome;
    double preco;

    Produto(String nome, double preco) {
        this.nome = nome;
        this.preco = preco;
    }

    public String tostring() {
        return nome + " (R$ " + preco + ")";
    }
}

public class Main {
    public static void main(String[] args) {
        Produto p = new Produto("Café", 12.5);
        System.out.println(p);
    }
}

$ javac Main.java && java Main
Produto@1dbd16a6

Compilou sem reclamar e mostrou um texto estranho: o toString() padrão do Object (o nome da classe, @ e um número que muda de uma execução para outra). Para o Java, tostring é só mais um método, com outro nome, que ninguém chama. O erro passou despercebido.

Agora com a etiqueta:

    @Override
    public String tostring() {
        return nome + " (R$ " + preco + ")";
    }

$ javac Main.java
Main.java:10: error: method does not override or implement a method from a supertype
    @Override
    ^
1 error

"O método não sobrescreve nem implementa um método de um supertipo (classe mãe ou interface)." O compilador leu a etiqueta, foi conferir e achou o problema antes de o programa rodar. Corrigindo para toString:

$ javac Main.java && java Main
Café (R$ 12.5)

@

Marca o início de uma anotação.

Override

"Sobrescrever", em inglês. É uma anotação que vem com o Java (java.lang.Override), por isso não precisa de import.

Regra de ouro: sempre que sobrescrever um método, escreva @Override. Ela custa uma linha e pega erros de digitação, de parâmetros e de nomes que mudaram na classe mãe.

class Produto {
    String nome;
    double preco;

    Produto(String nome, double preco) {
        this.nome = nome;
        this.preco = preco;
    }

    public String tostring() {
        return nome + " (R$ " + preco + ")";
    }
}

public class Main {
    public static void main(String[] args) {
        Produto p = new Produto("Café", 12.5);
        System.out.println(p);
    }
}

class Produto {
    String nome;
    double preco;

    Produto(String nome, double preco) {
        this.nome = nome;
        this.preco = preco;
    }

    @Override
    public String toString() {
        return nome + " (R$ " + preco + ")";
    }
}

public class Main {
    public static void main(String[] args) {
        Produto p = new Produto("Café", 12.5);
        System.out.println(p);
    }
}

2. @FunctionalInterface: "esta interface é para lambdas"

Uma interface funcional tem exatamente um método abstrato, e por isso pode receber uma lambda. A etiqueta @FunctionalInterface pede ao compilador que garanta isso. Se alguém acrescentar um segundo método abstrato:

@FunctionalInterface
interface Desconto {
    double aplicar(double preco);
    double reverter(double preco);
}

$ javac Main.java
Main.java:1: error: Unexpected @FunctionalInterface annotation
@FunctionalInterface
^
  Desconto is not a functional interface
    multiple non-overriding abstract methods found in interface Desconto
1 error

"Anotação @FunctionalInterface inesperada: Desconto não é uma interface funcional; foram encontrados vários métodos abstratos." Sem a etiqueta, a interface compilaria, e o erro só apareceria em outro arquivo, no dia em que alguém tentasse usar uma lambda com ela. Com um método só, tudo funciona:

@FunctionalInterface
interface Desconto {
    double aplicar(double preco);
}

public class Main {
    public static void main(String[] args) {
        Desconto metade = preco -> preco / 2;
        Desconto dezReais = preco -> preco - 10;
        System.out.println(metade.aplicar(80.0));
        System.out.println(dezReais.aplicar(80.0));
    }
}

$ java Main.java
40.0
70.0

3. @Deprecated: "aposentado, não use"

Deprecated quer dizer "desaprovado", "obsoleto". Quando um método antigo foi substituído por um melhor, mas ainda não pode ser apagado (porque tem gente usando), ele ganha essa etiqueta. O código continua funcionando, mas o compilador avisa quem o usa.

class Loja {
    @Deprecated
    static double precoAntigo(double valor) {
        return valor + 10;
    }

    static double preco(double valor) {
        return valor + 8;
    }
}

public class Main {
    public static void main(String[] args) {
        System.out.println(Loja.precoAntigo(100));
    }
}

$ javac Main.java
Note: Main.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
$ javac -Xlint:deprecation Main.java
Main.java:14: warning: [deprecation] precoAntigo(double) in Loja has been deprecated
        System.out.println(Loja.precoAntigo(100));
                               ^
1 warning
$ java Main
110.0

Repare nos três momentos:

1. O javac comum mostra só duas notas ("Main.java usa ou sobrescreve uma API obsoleta"; "recompile com -Xlint:deprecation para ver os detalhes"). O arquivo .class foi gerado: nota não é erro.
2. Com a opção -Xlint:deprecation, aparece o aviso (warning) completo, com linha e setinha: "precoAntigo(double) em Loja has been deprecated" (foi marcado como obsoleto).
3. O programa roda normalmente.

Marcado para remoção

A anotação aceita dois elementos: since ("desde qual versão") e forRemoval ("vai ser removido"). Com forRemoval = true, o aviso fica mais forte e aparece mesmo sem o -Xlint:

class Loja {
    @Deprecated(since = "2.0", forRemoval = true)
    static double precoAntigo(double valor) {
        return valor + 10;
    }
}

$ javac Main.java && java Main
Main.java:10: warning: [removal] precoAntigo(double) in Loja has been deprecated and marked for removal
        System.out.println(Loja.precoAntigo(100));
                               ^
1 warning
110.0

"…foi marcado como obsoleto e para remoção." Ou seja: numa versão futura, esse método vai sumir, e o seu código vai parar de compilar. Hora de trocar para o método novo.

A própria biblioteca do Java usa essa etiqueta. O construtor new Integer(5) é obsoleto desde o Java 9 (o certo é Integer.valueOf(5) ou só 5, veja wrappers):

$ javac -Xlint:deprecation Main.java
Main.java:3: warning: [deprecation] Integer(int) in Integer has been deprecated
        Integer quantidade = new Integer(5);
                             ^
1 warning

4. @SuppressWarnings: "eu sei, pode ficar quieto"

Suppress warnings = "suprimir avisos". Às vezes você usa algo obsoleto de propósito (por exemplo, enquanto migra um sistema antigo) e não quer que o aviso esconda outros mais importantes. A etiqueta diz qual categoria de aviso calar, o nome que aparece entre colchetes na mensagem ([deprecation], [removal], [unchecked]…):

public class Main {
    @SuppressWarnings("deprecation")
    public static void main(String[] args) {
        Integer quantidade = new Integer(5);
        System.out.println(quantidade);
    }
}

$ javac Main.java && java Main
5

Sem notas e sem avisos. Use com moderação e no menor pedaço possível (um método, não a classe inteira): um aviso calado é um aviso que ninguém mais vai ver.

5. Anotações de frameworks

Até aqui, quem lia as etiquetas era o compilador. Mas as anotações mais famosas do mundo Java são lidas por frameworks (bibliotecas grandes que "chamam o seu código") enquanto o programa roda. Você não precisa saber usá-las agora; só reconhecer o padrão quando encontrar:

Como um framework "lê" uma etiqueta? Com reflexão: ele examina as suas classes enquanto o programa roda, procura os métodos com @Test e os chama. Na próxima seção você faz isso em miniatura.

6. Criando uma anotação

Você pode criar suas próprias etiquetas. A Ana quer marcar os métodos que são tarefas da loja, com o nome do responsável e uma prioridade. Esta seção é uma apresentação: criar anotações é mais comum em quem escreve bibliotecas do que no dia a dia.

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.Method;
import java.util.Arrays;
import java.util.Comparator;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Tarefa {
    String responsavel();
    int prioridade() default 1;
}

public class Main {
    @Tarefa(responsavel = "Ana", prioridade = 3)
    static void conferirEstoque() { }

    @Tarefa(responsavel = "Bruno")
    static void limparVitrine() { }

    static void almocar() { }

    public static void main(String[] args) {
        Method[] metodos = Main.class.getDeclaredMethods();
        Arrays.sort(metodos, Comparator.comparing(Method::getName));
        for (Method m : metodos) {
            Tarefa t = m.getAnnotation(Tarefa.class);
            if (t != null) {
                System.out.println(m.getName() + " -> " + t.responsavel() + ", prioridade " + t.prioridade());
            }
        }
    }
}

$ javac Main.java && java Main
conferirEstoque -> Ana, prioridade 3
limparVitrine -> Bruno, prioridade 1

Repare que as anotações @Retention e @Target são anotações sobre a anotação (os nomes técnicos são "meta-anotações"). É exatamente assim que o JUnit define o @Test.

Qual usar?

Quando dá errado

    @Tarefa(prioridade = 2)
    static void conferirEstoque() { }

$ javac Main.java
Main.java:14: error: annotation @Tarefa is missing a default value for the element 'responsavel'
    @Tarefa(prioridade = 2)
    ^
1 error

@Tarefa(responsavel = "Ana")
public class Main {

$ javac Main.java
Main.java:13: error: annotation interface not applicable to this kind of declaration
@Tarefa(responsavel = "Ana")
^
1 error

Referência

Exercícios

interface Desconto {
    double aplicar(double preco);
}

public class Main {
    public static void main(String[] args) {
        // crie as lambdas metade e dezReais aqui

        System.out.println(metade.aplicar(80.0));
        System.out.println(dezReais.aplicar(80.0));
    }
}

@FunctionalInterface
interface Desconto {
    double aplicar(double preco);
}

public class Main {
    public static void main(String[] args) {
        Desconto metade = preco -> preco / 2;
        Desconto dezReais = preco -> preco - 10;
        System.out.println(metade.aplicar(80.0));
        System.out.println(dezReais.aplicar(80.0));
    }
}

Resumo

• Uma anotação (@Nome) é uma etiqueta: não muda o que o código faz, mas informa o compilador, ferramentas ou frameworks.
• @Override faz o javac conferir a sobrescrita (method does not override or implement a method from a supertype). Use sempre.
• @FunctionalInterface garante um único método abstrato.
• @Deprecated gera nota/aviso has been deprecated; com forRemoval = true, o aviso [removal] aparece sempre.
• @SuppressWarnings("categoria") cala avisos, no menor trecho possível.
• Frameworks (JUnit, Spring, JPA) leem anotações com reflexão. Você cria as suas com @interface, @Retention e @Target.

Próxima aula: Reflexão, o jeito de um programa examinar a si mesmo.