Obsoleto contro denigrato in JavaDoc?

In JavaDoc per X509Certificate getSubjectDN()esso afferma:

Denigrato , sostituito da getSubjectX500Principal ().

Sono abituato a vedere deprecato nei metodi for che non dovrebbero più essere usati, ma non denigrati. Ho trovato un bug report su questo caso particolare in cui è stato chiuso con un commento:

Questo non è un bug. "Obsoleto" deve essere utilizzato solo in casi gravi.

Quando stiamo usando un metodo obsoleto , l'azione generale suggerita è di smettere di usare il metodo.

Quindi qual è l'azione suggerita quando un metodo è contrassegnato come denigrato ?

La definizione di denigrato di Merriam-Webster suggerisce:

1: attaccare la reputazione di: diffamazione <denigrare i propri avversari>
2: negare l'importanza o la validità di: sminuire <denigrare i loro successi>

Sulla base di ciò che è scritto in un altro bug correlato, defame / belittle sembra corrispondere all'intento della formulazione utilizzata in javadocs - Bug ID: 4959744 Denigrate X509Certificate.getSubjectDN () & co :

I metodi getSubjectDN () e getIssuerDN () in X509Certificate e getIssuerDN () in X509CRL sono problematici . Restituiscono una classe non specificata che implementa l'interfaccia java.security.Principal, che ha una specifica molto ampia.

Poiché nei metodi getSubjectDN () e getIssuerDN () non è presente alcuna specifica aggiuntiva, è possibile che le implementazioni restituiscano una classe arbitraria specifica per l'implementazione. L'esperienza del mondo reale ha dimostrato che questo è il caso con conseguente non portabilità o inaffidabilità del codice. Per motivi di compatibilità, le specifiche di tali metodi non possono essere modificate e devono essere considerate invalicabili.

In JDK 1.4 sono stati aggiunti metodi di sostituzione getSubjectX500Principal () & co che restituiscono un'istanza della classe X500Principal ben definita. Le implementazioni di questi metodi sono state progettate per evitare tutti i problemi di questo tipo. Tuttavia, i nuovi metodi soffrono di sottoesposizione e i programmatori continuano a utilizzare i metodi familiari e intuitivamente chiamati getSubjectDN () & co.

Per modificare ciò, i vecchi metodi getSubjectDN () e getIssuerDN () dovrebbero essere deprecati. Ciò garantirà che gli sviluppatori che utilizzano questi metodi ricevano un avviso di compilazione ....

VALUTAZIONE

... La deprecazione è stata considerata inappropriata in questo caso. Invece, sono stati aggiunti commenti cautelativi a JavaDoc .

Il fatto che leggere il Bug ID 5008142 ti abbia lasciato confuso su questa roba "denigrata" sembra più un errore dello sviluppatore che l'ha affrontata.

Avrebbero dovuto trovare il bug 4959744 e riferirlo nella loro valutazione, invece della vaga affermazione "destinato a essere utilizzato solo in casi gravi". Probabilmente potrebbero anche chiudersi come duplicati, con giustificazioni come "La deprecazione è stata considerata, valutata e respinta a favore della denigrazione per ID bug 4959744" .

Per lo meno potrebbero fare riferimento all'ID bug 4959744 (forse insieme a 4638294 ) nel campo Rapporti correlati (chiamato Vedi anche nel vecchio iirc bugs.sun.com) del loro bug tracker. Il fatto che ciò non sia stato fatto sospetta di non aver cercato affatto problemi correlati.

Dopo qualche altro scavo sono stato in grado di trovare un post sul blog chiamato Deprecation nel JDK . In sostanza afferma che le cose contrassegnate come obsolete sono considerate dannose per essere utilizzate e che ci sono alcune cose che sono semplicemente scoraggiate.

La politica generale per diverse versioni di funzionalità è che i componenti JDK principali sono contrassegnati come obsoleti solo se sono attivamente dannosi. Se l'utilizzo di una classe o di un metodo è sconsiderato, di solito non è sufficiente per guadagnare il voto deprecato.

Ha detto che attualmente esiste un modo per contrassegnare un elemento come scoraggiato da usare, ma che potrebbero eventualmente aggiungere un modo per farlo.

Ad un certo punto, questo tipo di consiglio potrebbe essere formalizzato con una struttura di "denigrazione" meno dannosa del deprecata basata su una combinazione di tag e annotazioni javadoc per consentire l'esecuzione di controlli programmatici per l'utilizzo di questi elementi API meno dannosi.

Anche se non riesco a trovare nient'altro in particolare sulla decisione di usare il termine Denigrato, questo sembra abbastanza vicino. E in base a questo sembra che l'azione che uno sviluppatore dovrebbe intraprendere sia la stessa di Deprecated , non usare il metodo.