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 елемент се използва някъде в кода. Така че, в този случай ще се покаже само ако има код, който извиква метода за изчисляване .
Също така можем да съобщим за оттегления статус в документацията, като използваме и Javadoc @deprecated таг .
3. Добавени незадължителни атрибути в Java 9
Java 9 добавя някои незадължителни атрибути към анотацията @Deprecated : since и forRemoval .
Най тъй като атрибут изисква низ, който ни позволява да се определи в коя версия, е извадено от елемента. Стойността по подразбиране е празен низ.
И forRemoval е булева стойност , която ни позволява да посочим дали елементът ще бъде премахнат в следващото издание. Стойността му по подразбиране е 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; } }
Просто казано, горното използване означава, че изчислението е оттеглено от 4.5 на нашата библиотека и че е планирано да бъде премахнато в следващата голяма версия.
За нас е полезно да добавим това, тъй като компилаторът ще ни даде по-силно предупреждение, ако установи, че използваме метод с тази стойност.
И вече има поддръжка от IDE за откриване на използване на метод, маркиран с forRemoval = true. IntelliJ например зачертава кода с червена линия вместо с черна.
4. Заключение
В тази бърза статия видяхме как да използваме анотацията @Deprecated и нейните незадължителни атрибути, за да маркираме код, който вече не трябва да се използва.
Пълният изходен код за примерите може да бъде намерен в GitHub.