Java @Устаревшая аннотация

1. Обзор

В этом кратком руководстве мы рассмотрим устаревшие API в Java и как использовать аннотацию @Deprecated .

2. Аннотация @Deprecated

По мере развития проекта его API меняется. Со временем появляются определенные конструкторы, поля, типы или методы, которые мы больше не хотим, чтобы люди использовали.

Вместо того, чтобы нарушать обратную совместимость API проекта, мы можем пометить эти элементы аннотацией @Deprecated .

@Deprecated сообщает другим разработчикам, что помеченный элемент больше не следует использовать . Также обычно рядом с аннотацией @Deprecated добавляют некоторый Javadoc, чтобы объяснить, что было бы лучшей альтернативой, обеспечивающей правильное поведение:

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

Помните, что компилятор отображает предупреждение об устаревшем API только в том случае, если аннотированный элемент Java используется где-то в коде. Таким образом, в этом случае это будет отображаться только в том случае, если есть код, вызывающий метод calculate .

Кроме того, мы можем сообщить об устаревшем статусе в документации, используя тег Javadoc @deprecated .

3. Дополнительные атрибуты, добавленные в Java 9

Java 9 добавляет в аннотацию @Deprecated некоторые необязательные атрибуты : until и forRemoval . ``

Поскольку атрибуту требуется строка, которая позволяет нам определить, в какой версии элемент устарел. Значение по умолчанию — пустая строка.

А forRemoval — это логическое значение , которое позволяет нам указать, будет ли элемент удален в следующем выпуске. Его значение по умолчанию равно false:

public class Worker {
    /**
     * Calculate period between versions
     * @deprecated
     * This method is no longer acceptable to compute time between versions.
     * <p> 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;
    }
}

Проще говоря, указанное выше использование означает, что calculate устарел, начиная с версии 4.5 нашей библиотеки, и что его планируется удалить в следующем основном выпуске.

Нам полезно добавить это, так как компилятор выдаст нам более строгое предупреждение , если обнаружит, что мы используем метод с таким значением.

И уже есть поддержка со стороны IDE для обнаружения использования метода, отмеченного forRemoval=true. IntelliJ, например, перечеркивает код красной линией вместо черной.

4. Вывод

В этой быстрой статье мы увидели, как использовать аннотацию @Deprecated и ее необязательные атрибуты , чтобы пометить код, который больше не следует использовать.

Полный исходный код примеров можно найти на GitHub .