streamalism.org

1. Oversigt

I denne hurtige vejledning ser vi på forældede API'er i Java, og hvordan man bruger @Forældet kommentar.

2. Den @Forældet Kommentar

Efterhånden som et projekt udvikler sig, ændres dets API. Over tid er der visse konstruktører, felter, typer eller metoder, som vi ikke ønsker, at folk skal bruge mere.

I stedet for at bryde bagudkompatibiliteten af ​​projektets API kan vi mærke disse elementer med @Forældet kommentar.

@Forældet fortæller andre udviklere, atdet markeret element bør ikke længere bruges. Det er almindeligt at tilføje noget Javadoc ved siden af @Forældet kommentar for at forklare, hvad der ville være et bedre alternativ, der tjener den rigtige adfærd:

public class Worker {/ ** * Beregn periode mellem versioner * @ udfældet * Denne metode er ikke længere acceptabel til at beregne tid mellem versioner. * 
 Brug i stedet {@link Utils # calcifyPeriod (Machine)}. * * @paramaskineforekomst * @return beregnet tid * / @Forældet offentlig int beregne (maskine maskine) {return machine.exportVersions (). størrelse () * 10; }}

Husk, at en compiler kun viser den forældede API-advarsel, hvis det annoterede Java-element bruges et eller andet sted i koden. Så i dette tilfælde ville det kun vise, om der var kode, der kaldte Beregn metode.

Også, Vi kan også kommunikere den forældede status i dokumentationen ved hjælp af Javadoc @ forældet tag.

3. Valgfrie attributter tilføjet i Java 9

Java 9 tilføjer nogle valgfri attributter til @Forældet kommentar: siden og til fjernelse.

Det siden attribut kræver en streng, der lader os definere i hvilken version elementet blev udfaset. Standardværdien er en tom streng.

Og til fjernelse er en boolsk der giver os mulighed for at specificere, om elementet vil blive fjernet i den næste udgivelse. Dens standardværdi er falsk:

public class Worker {/ ** * Beregn periode mellem versioner * @ udfældet * Denne metode er ikke længere acceptabel til at beregne tid mellem versioner. * 
 Brug i stedet {@link Utils # calcifyPeriod (Machine)}. * * @paramaskine-forekomst * @return beregnet tid * / @Deprecated (since = "4.5", forRemoval = true) public int calc (Machine machine) {return machine.exportVersions (). size () * 10; }}

Kort sagt betyder ovenstående brug det Beregn er udfaset siden 4.5 af vores bibliotek, og at det er planlagt til fjernelse i den næste større udgivelse.

Det er nyttigt for os at tilføje dette siden kompilatoren vil give os en stærkere advarsel hvis det finder ud af, at vi bruger en metode med den værdi.

Og der er allerede støtte fra IDE'ertil at opdage anvendelser af en metode markeret med forRemoval = true. IntelliJ slår for eksempel gennem koden med en rød linje i stedet for en sort.

4. Konklusion

I denne hurtige artikel så vi, hvordan man bruger @Forældet kommentar og dens valgfrie attributter til at markere kode, der ikke længere skal bruges.

Den fulde kildekode til eksemplerne kan findes på GitHub.