1. Обзор
В этом кратком руководстве мы рассмотрим устаревшие API в Java и как использовать аннотацию @Deprecated .
2. Аннотация @Deprecated
По мере развития проекта его API меняется. Со временем появляются определенные конструкторы, поля, типы или методы, которые мы больше не хотим использовать.
Вместо того чтобы нарушать обратную совместимость API проекта, мы можем пометить эти элементы с помощью @Deprecated аннотации .
@Deprecated сообщает другим разработчикам, что отмеченный элемент больше не должен использоваться . Обычно также добавляют некоторый Javadoc рядом с аннотацией @Deprecated , чтобы объяснить, что было бы лучшей альтернативой, которая служит правильному поведению:
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;
}
}
Помните, что компилятор отображает предупреждение об устаревшем API только в том случае, если аннотированный элемент Java используется где-то в коде. Таким образом, в этом случае он будет отображаться только в том случае, если существует код, вызывающий метод calculate .
Кроме того, мы также можем сообщить об устаревшем статусе в документации с помощью тега Javadoc @deprecated .
3. Дополнительные атрибуты, добавленные в Java 9
Java 9 добавляет некоторые необязательные атрибуты к @Устарело аннотация: с и для удаления .
Атрибут since требует строки, которая позволяет нам определить, в какой версии элемент был устаревшим. Значение по умолчанию-пустая строка.
А for Removal – это boolean , который позволяет нам указать, будет ли элемент удален в следующем выпуске. Его значение по умолчанию равно 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;
}
}
Проще говоря, вышеприведенное использование означает, что calculate устарел с версии 4.5 нашей библиотеки и что его планируется удалить в следующем крупном выпуске.
Нам полезно добавить это, так как компилятор выдаст нам более сильное предупреждение , если обнаружит, что мы используем метод с таким значением.
И уже есть поддержка IDEs для обнаружения использования метода, помеченного forRemoval=true. IntelliJ, например, пробивает код красной линией вместо черной.
4. Заключение
В этой краткой статье мы увидели, как использовать аннотацию @Deprecated и ее необязательные атрибуты для обозначения кода, который больше не должен использоваться.
Полный исходный код примеров можно найти на GitHub .