Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

In the JavaDoc for X509Certificate getSubjectDN() it states:

Denigrated, replaced by getSubjectX500Principal().

I am used to seeing Deprecated in the for methods that should not be used any longer, but not Denigrated. I found a bug report about this particular case where it was closed with comment:

This isn't a bug. "Deprecated" is meant to be used only in serious cases.

When we are using a method that is Deprecated, the general suggested action is to stop using the method.

So what is the suggested action when a method is marked as Denigrated?

share|improve this question
2  
Wow. I've read the answers, and while I'm sure they're technically correct, 'Denigrated' is a terrible word to use. They should have just used 'Discouraged'. No need to spit on the code; a warning would suffice. –  Eric King Nov 2 '12 at 20:19
    
@Eric King I kinda felt the same way. I was thinking more along the lines that if it is discouraged just deprecate it. –  jschoen Nov 2 '12 at 20:32

2 Answers 2

up vote 9 down vote accepted

Merriam-Webster definition of denigrate suggests:

1: to attack the reputation of : defame <denigrate one's opponents>
2: to deny the importance or validity of: belittle <denigrate their achievements>

Based on what is written in another related bug, defame / belittle appears to match the intent of wording used in javadocs - Bug ID: 4959744 Denigrate X509Certificate.getSubjectDN() & co:

The methods getSubjectDN() and getIssuerDN() in X509Certificate and getIssuerDN() in X509CRL are problematic. They return an unspecified class implementing the java.security.Principal interface, which has a very loose specification.

Because no additional specification is present in the getSubjectDN() and getIssuerDN() methods, it is permissible for implementations to return an arbitrary, implementation specific class. Real world experience has shown that this is the case resulting in non-portability or unreliability of the code. For compatibility reasons, the specifications for those methods cannot be changed and they must be considered unsalvageable.

Replacement methods getSubjectX500Principal() & co that return an instance of the well-defined X500Principal class were added in JDK 1.4. The implementations of those methods have been designed to avoid all problems of this sort. However, the new methods suffer from underexposure and programmers continue to use the familiar and more intuitively named getSubjectDN() & co methods.

To change this, the old getSubjectDN() and getIssuerDN() methods should be deprecated. That will ensure that developers who use this methods receive a compile time warning....

EVALUATION

...Deprecation was considered inappropriate in this case. Instead, cautionary comments were added to the JavaDoc.


The fact that reading Bug ID 5008142 has left you confused about this "denigrated" stuff looks more like a fault of developer who dealt with it.

They should have found bug 4959744 and refer it in their evaluation, instead of vague statement "meant to be used only in serious cases". They could probably even close as duplicate, with justification like "Deprecation has been considered, evaluated and rejected in favor of denigration per Bug ID 4959744".

At the very very least they could refer Bug ID 4959744 (maybe along with 4638294) in the Related Reports field (called See Also in old bugs.sun.com iirc) of their bug tracker. That this has not been done makes one suspect that they did not search for related issues at all.

share|improve this answer
1  
+1 Good job on digging that up. –  FrustratedWithFormsDesigner Nov 2 '12 at 18:31
1  
@FrustratedWithFormsDesigner hardest part was to figure how to enter "denigrated" at oracle search page so that results are filtered to "bugs.sun.com". The rest was easy, I just checked a handful of search results that popped up. "Denigrate" is a pretty good word to search :) –  gnat Nov 2 '12 at 18:37
1  
See I had used Google to find that first one, but it didn't give me the others. I probably should have looked harder. Thanks –  jschoen Nov 2 '12 at 18:39
    
@jschoen I think this isn't that much of your fault; I expanded an answer on that –  gnat Nov 2 '12 at 20:45

After some more digging I was able to find a blog post called Deprecation in the JDK. It basically states that things marked Deprecated are considered harmful to be used, and that there are some things that are simply discouraged.

The general policy for several feature releases is that core JDK components are only marked as deprecated if they are actively harmful. If using a class or method is just ill-advised, that is usually not sufficient to earn the deprecated mark.

He mentioned that there currently a way to mark an item as being discouraged to use, but that they might eventually add a way to do this.

At some point, this kind of advice might be formalized with a less-harmful-than-deprecated "denigration" facility based a combination of javadoc tags and annotations to allow programmatic checks be made for usage of these less harmful API elements to.

While I can not find anything else specifically about a decision to use the term Denigrated this seems pretty close. And based on this it seems the action a developer should take is the same as Deprecated, do not use the method.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.