Java @ Annotazione deprecata

1. Panoramica

In questo rapido tutorial, daremo uno sguardo alle API deprecate in Java e come utilizzare l' annotazione @Deprecated .

2. L' annotazione @Deprecated

Man mano che un progetto si evolve, la sua API cambia. Nel tempo, ci sono determinati costruttori, campi, tipi o metodi che non vogliamo più che le persone utilizzino.

Invece di rompere la compatibilità con le versioni precedenti dell'API del progetto, possiamo taggare questi elementi con l' annotazione @Deprecated .

@Deprecated dice ad altri sviluppatori che l' elemento contrassegnato non dovrebbe più essere utilizzato . È comune aggiungere anche un po 'di Javadoc accanto all'annotazione @Deprecated per spiegare quale sarebbe un'alternativa migliore che serve il comportamento corretto:

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; } }

Ricorda che un compilatore visualizza solo l'avviso API deprecato se l'elemento Java annotato viene utilizzato da qualche parte nel codice. Quindi, in questo caso, verrebbe visualizzato solo se fosse presente un codice che chiama il metodo di calcolo .

Inoltre, possiamo comunicare lo stato deprecato anche nella documentazione utilizzando il tag Javadoc @deprecated .

3. Attributi opzionali aggiunti in Java 9

Java 9 aggiunge alcuni attributi opzionali all'annotazione @Deprecated : since e forRemoval .

L' attributo since richiede una stringa che ci consenta di definire in quale versione l'elemento è stato deprecato. Il valore predefinito è una stringa vuota.

E forRemoval è un booleano che ci permette di specificare se l'elemento verrà rimosso nella prossima versione. Il suo valore predefinito è 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; } }

In poche parole, l'utilizzo di cui sopra significa che il calcolo è stato deprecato dalla 4.5 della nostra libreria e che è pianificato per la rimozione nella prossima versione principale.

È utile per noi aggiungerlo poiché il compilatore ci darà un avviso più forte se scopre che stiamo usando un metodo con quel valore.

E c'è già il supporto degli IDE per rilevare gli usi di un metodo contrassegnato con forRemoval = true. IntelliJ, ad esempio, attraversa il codice con una linea rossa invece che nera.

4. Conclusione

In questo rapido articolo, abbiamo visto come utilizzare l' annotazione @Deprecated e i suoi attributi opzionali per contrassegnare il codice che non dovrebbe più essere utilizzato.

Il codice sorgente completo per gli esempi può essere trovato su GitHub.