Como declarar ou marcar um método Java como obsoleto?

284

Gostaria de tornar um dos meus métodos "obsoleto" = não usado mais.

Mas ainda assim eu gostaria de tê-lo na minha API. Eu só quero mostrar "aviso" para quem usa esse método.

Como posso conseguir isso?

Pavel Janicek
fonte
10
O @Deprecrated não é uma opção para você?
templatetypedef
18
É, mas eu não sabia sobre isso ... é por isso que eu estou fazendo a pergunta :)
Pavel Janicek
4
comentários não são o lugar para respostas!
mattumotu

Respostas:

577

Use @Deprecatedno método Não se esqueça de esclarecer o campo javadoc:

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}
Vladimir Ivanov
fonte
2
Como você vincula uma biblioteca externa? por exemplo: com.hello.api.PublicController # new #
Faizan Kazi
@LinuxLars concordou completamente! O Java 9 adicionou alguns atributos para começar a tornar a depreciação levada a sério, mas a adição de outro atributo reasoncom um valor padrão ""não poderia ter prejudicado
asgs
3
Eu desejaria que a @deprecatedmensagem no comentário poderia ser adicionado ao @Deprecated(um local para corrigi-los todos) ...
U. Windl
88

Use a @Deprecatedanotação e a @deprecatedtag JavaDoc.

A @deprecatedtag JavaDoc é usada para fins de documentação.

A @Deprecatedanotação instrui o compilador que o método está obsoleto. Aqui está o que diz o documento Sun / Oracles sobre o assunto:

O uso da @Deprecatedanotação para reprovar uma classe, método ou campo garante que todos os compiladores emitam avisos quando o código usar esse elemento do programa. Por outro lado, não há garantia de que todos os compiladores sempre emitam avisos com base na @deprecatedtag Javadoc, embora atualmente os compiladores da Sun o façam. Outros compiladores podem não emitir esses avisos. Portanto, usar a @Deprecatedanotação para gerar avisos é mais portátil do que confiar na @deprecatedtag Javadoc.

Você pode encontrar o documento completo em Como e quando descontinuar APIs

ShaMan-H_Fel
fonte
1
Não é bem verdade. Ambos método javadoc e compilador tell anotação está obsoleto
Bohemian
17
@ Bohemian Na verdade isso não é bem verdade. A anotação é definida na seção 9.6.1.6 (Java Language Specification) ( java.sun.com/docs/books/jls/third_edition/html/… ), enquanto a tag javadoc não. Portanto, a anotação faz parte do idioma. Se você decidir escrever seu próprio compilador Java, poderá ignorar a tag javadoc, mas deverá reconhecer a anotação.
ShaMan-H_Fel
@ ShaMan-H_Fel Acredito que o modelo javadoc também funcione. Porque era a única opção antes do Java 5, e funcionou. Quando você marcou um método com a @deprecatedtag javadoc (em Java 4-), o compilador marcou o método (classe, campo) como reprovado e os IDEs mostraram avisos, mesmo quando nenhuma fonte estava disponível.
Amir Pashazadeh
42

pois faltavam algumas explicações menores

Use @Deprecatedanotação no método como este

 /**
 * @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) {
}

lembre-se de explicar:

  1. Por que esse método não é mais recomendado . Que problemas surgem ao usá-lo. Forneça um link para a discussão sobre o assunto, se houver. (lembre-se de separar linhas para facilitar a leitura<br/>
  2. Quando será removido . (informe aos usuários o quanto eles ainda podem confiar nesse método se decidirem seguir o caminho antigo)
  3. Forneça uma solução ou link para o método recomendado {@link #setPurchasePrice()}
azerafati
fonte
Não deveria ser <br/>, em vez de </br>?
Argh1969
@ argh1969, certo! não me lembro de onde eu peguei o modelo naquela época. Mas posso confirmar que ambas as versões funcionam. Embora eu esteja editando a favor de padrões.
Azerafati #
37

Há duas coisas que você pode fazer:

  1. Adicione a @Deprecatedanotação ao método e
  2. Adicione uma @deprecatedtag ao javadoc do método

Você deve fazer as duas coisas !

Citando o documentação java sobre este assunto:

A partir do J2SE 5.0, você preteriu uma classe, método ou campo usando a anotação @Deprecated. Além disso, você pode usar a tag Javadoc @ obsoleta para informar aos desenvolvedores o que usar.

O uso da anotação faz com que o compilador Java gere avisos quando a classe, método ou campo descontinuado é usado. O compilador suprime avisos de descontinuação se uma unidade de compilação descontinuada usar uma classe, método ou campo descontinuado. Isso permite criar APIs herdadas sem gerar avisos.

É altamente recomendável usar a tag Javadoc @ obsoleta com comentários apropriados explicando como usar a nova API. Isso garante que os desenvolvedores tenham um caminho de migração viável da API antiga para a nova API

Boêmio
fonte
Isso significa que o comentário do javadoc é altamente recomendado além da anotação, não como um substituto! É por isso que é sempre melhor colocar as duas coisas.
morellet.d
@ morellet.d Obrigado por apontar isso. Eu basicamente reescrevi minha resposta agora (não li o documento com atenção suficiente!). Cheers
Bohemian
8

Use a anotação @Deprecated para seu método e você também deve mencioná-la em seus javadocs.

amit
fonte
Fazer a ligação agora é dividido
Yetti99
3

Dê uma olhada na @Deprecatedanotação.

jham
fonte