Jak zadeklarować lub oznaczyć przestarzałą metodę Java?

284

Chciałbym, aby jedna z moich metod była „przestarzała” = już nie używana.

Ale nadal chciałbym mieć to w moim API. Chcę tylko pokazać „ostrzeżenie” każdemu, kto używa tej metody.

Jak mogę to osiągnąć?

java deprecated Pavel Janicek
źródło
10
Czy @Deprecrated nie jest dla ciebie opcją?
templatetypedef
18
Tak, ale nie wiedziałem o tym ... dlatego zadaję pytanie :)
Pavel Janicek
1
Zobacz docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/…
Raedwald
4
komentarze nie są miejscem na odpowiedzi!
mattumotu,

Odpowiedzi:

577

Użyj @Deprecatedwedług metody. Nie zapomnij o wyjaśnieniu pola javadoc:

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}
Władimir Iwanow
źródło
2
Jak połączyć zewnętrzną bibliotekę? np .: com.hello.api.PublicController # new
Faizan Kazi
@LinuxLars całkowicie się zgadza! Java 9 dodała kilka atrybutów, aby zacząć traktować deprecjację jako poważną, ale dodanie kolejnego atrybutu reasono wartości domyślnej ""nie mogło zaszkodzić
asgs
3
Chciałbym, aby @deprecatedwiadomość w komentarzu mogła zostać dodana do @Deprecated(jedno miejsce, aby naprawić je wszystkie) ...
U. Windl
88

Użyj zarówno @Deprecatedadnotacji, jak i @deprecatedznacznika JavaDoc.

Znacznik @deprecatedJavaDoc służy do celów dokumentacji.

@DeprecatedAdnotacja instruuje kompilator, że metoda jest przestarzała. Oto, co napisano w dokumencie Sun / Oracles na ten temat:

Wykorzystanie @Deprecatedadnotacji do wycofania klasy, metody lub pola gwarantuje, że wszystkie kompilatory będą wydawały ostrzeżenia, gdy kod użyje tego elementu programu. W przeciwieństwie do tego, nie ma gwarancji, że wszystkie kompilatory zawsze będą generowały ostrzeżenia na podstawie @deprecatedznacznika Javadoc, chociaż obecnie kompilatory Sun to robią. Inne kompilatory mogą nie wydawać takich ostrzeżeń. Tak więc używanie @Deprecatedadnotacji do generowania ostrzeżeń jest bardziej przenośne niż poleganie na @deprecatedznaczniku Javadoc.

Pełen dokument można znaleźć w temacie Jak i kiedy wycofywać interfejsy API

ShaMan-H_Fel
źródło
1
Niezupełnie prawda. Zarówno javadoc, jak i adnotacja informują, że metoda kompilatora jest przestarzała
Czeski
17
@ Bohemian W rzeczywistości nie jest to do końca prawda. Adnotacja jest zdefiniowana w sekcji 9.6.1.6 specyfikacji języka Java ( java.sun.com/docs/books/jls/third_edition/html/... ), podczas gdy tag javadoc nie jest. Adnotacja jest więc częścią języka. Jeśli zdecydujesz się napisać własny kompilator Java, możesz zignorować tag javadoc, ale musisz rozpoznać adnotację.
ShaMan-H_Fel
@ ShaMan-H_Fel Wierzę, że model javadoc też działa. Ponieważ był to jedyny wybór przed Javą 5 i działał. Kiedy zaznaczyłeś metodę @deprecatedtagiem javadoc (w Javie 4-), kompilator oznaczył metodę (klasę, pole) jako przestarzałą, a IDE pokazały ostrzeżenia, nawet jeśli żadne źródło nie było dostępne.
Amir Pashazadeh
42

ponieważ brakowało kilku drobnych wyjaśnień

Użyj @Deprecatedadnotacji na takiej metodzie

 /**
 * @param basePrice
 * 
 * @deprecated  reason this method is deprecated <br/>
 *              {will be removed in next version} <br/>
 *              use {@link #setPurchasePrice()} instead like this: 
 * 
 * 
 * <blockquote><pre>
 * getProduct().setPurchasePrice(200) 
 * </pre></blockquote>
 * 
 */
@Deprecated
public void setBaseprice(int basePrice) {
}

pamiętaj, aby wyjaśnić:

  1. Dlaczego ta metoda nie jest już zalecana . Jakie problemy pojawiają się podczas korzystania z niego. Podaj link do dyskusji na ten temat, jeśli istnieje. (pamiętaj, aby oddzielić linie dla czytelności<br/>
  2. Kiedy zostanie usunięty . (poinformuj użytkowników, na ile mogą nadal polegać na tej metodzie, jeśli zdecydują się trzymać starej metody)
  3. Podaj rozwiązanie lub link do zalecanej metody {@link #setPurchasePrice()}
azerafati
źródło
Czy nie powinno to być <br/> zamiast </br>?
argh1969,
@ argh1969, racja! nie pamiętam, skąd wtedy wziąłem szablon. Ale mogę potwierdzić, że obie wersje działają. Chociaż redaguję na rzecz standardów.
azerafati,
37

Możesz zrobić dwie rzeczy:

  1. Dodaj @Deprecatedadnotację do metody i
  2. Dodaj @deprecatedznacznik do javadoc metody

Powinieneś zrobić oba !

Cytując dokumentację Java na ten temat:

Począwszy od J2SE 5.0, klasa, metoda lub pole są przestarzałe przy użyciu adnotacji @Deprecated. Ponadto można użyć tagu Javadoc @deprecated informującego programistów, czego należy użyć.

Użycie adnotacji powoduje, że kompilator Java generuje ostrzeżenia, gdy używana jest przestarzała klasa, metoda lub pole. Kompilator eliminuje ostrzeżenia o wycofaniu, jeśli przestarzała jednostka kompilacyjna używa przestarzałej klasy, metody lub pola. Umożliwia to tworzenie starszych interfejsów API bez generowania ostrzeżeń.

Zdecydowanie zalecamy użycie tagu Javadoc @deprecated z odpowiednimi komentarzami wyjaśniającymi, jak korzystać z nowego interfejsu API. Dzięki temu programiści będą mieli wykonalną ścieżkę migracji ze starego interfejsu API do nowego interfejsu API

Czeski
źródło
8

Użyj adnotacji @Deprecated dla swojej metody i powinieneś również wspomnieć o niej w javadocs.

amit
źródło
Link jest teraz zerwany
Yetti99
3

Spójrz na @Deprecatedadnotację.

jham
źródło