Anotação obsoleta do Java @

1. Visão geral

Neste tutorial rápido, daremos uma olhada nas APIs obsoletas em Java e como usar a anotação@Deprecated.

2. A anotação@Deprecated

À medida que um projeto evolui, sua API muda. Com o tempo, existem certos construtores, campos, tipos ou métodos que não queremos que as pessoas usem mais.

Em vez de quebrar a compatibilidade com versões anteriores da API do projeto, podemos marcar esses elementos com a anotação@Deprecated.

@Deprecated tells other developers thatthemarked element should no longerbe used. É comum também adicionar algum Javadoc próximo à anotação@Deprecated para explicar o que seria uma alternativa melhor que atende ao comportamento certo:

public class Worker {
    /**
     * Calculate period between versions
     * @deprecated
     * This method is no longer acceptable to compute time between versions.
     *  Use {@link Utils#calculatePeriod(Machine)} instead.
     *
     * @param machine instance
     * @return computed time
     */
    @Deprecated
    public int calculate(Machine machine) {
        return machine.exportVersions().size() * 10;
    }
}

Lembre-se de que um compilador exibe apenas o aviso de API reprovado se o elemento Java anotado for usado em algum lugar do código. Portanto, neste caso, só seria mostrado se houvesse um código que chamasse o métodocalculate.

Além disso,we can communicate the deprecated status in the documentation as well by using the Javadoc @deprecated tag.

3. Atributos opcionais adicionados no Java 9

Java 9 adiciona alguns atributos opcionais à anotação@Deprecated:sinceeforRemoval.

O atributosince requer uma string que nos permite definir em qual versão o elemento foi preterido. O valor padrão é uma sequência vazia.

EforRemoval é umboolean que nos permite especificar se o elemento será removido na próxima versão. Seu valor padrão éfalse:

public class Worker {
    /**
     * Calculate period between versions
     * @deprecated
     * This method is no longer acceptable to compute time between versions.
     *  Use {@link Utils#calculatePeriod(Machine)} instead.
     *
     * @param machine instance
     * @return computed time
     */
    @Deprecated(since = "4.5", forRemoval = true)
    public int calculate(Machine machine) {
        return machine.exportVersions().size() * 10;
    }
}

Simplificando, o uso acima significa quecalculate se tornou obsoleto desde 4.5 de nossa biblioteca e que está programado para remoção na próxima versão principal.

É útil adicionarmos isso, poisthe compiler will give us a stronger warning se descobrir que estamos usando um método com esse valor.

And there is already support from IDEsto detect uses of a method marked with forRemoval=true. IntelliJ, por exemplo, risca o códigowith a red line em vez de um preto.

4. Conclusão

Neste artigo rápido, vimos como usar a anotação@Deprecated e seuoptional attributes para marcar o código que não deve mais ser usado.

O código-fonte completo dos exemplos pode ser encontradoover on GitHub.

TOC

Anotação obsoleta do Java @