SEI CERT Oracle Coding Standard for Java

Space shortcuts

Page tree

Never use deprecated fields, methods, or classes in new code. Java provides an @deprecated annotation to indicate the deprecation of specific fields, methods, and classes. For example, many methods of java.util.Date, such as Date.getYear(), have been explicitly deprecated. THI05-J. Do not use Thread.stop() to terminate threads describes issues that can result from using the deprecated Thread.stop() method. 

The Java SE documentation provides a list of deprecated APIs for each version of the language:

Programmers should use the list of deprecated functions specific to the language version they are using, although it may also be possible to avoid the use of APIs that are deprecated in later versions as well if suitable alternatives are available.

Obsolete fields, methods, and classes should not be used. Java lacks any annotation that indicates obsolescence; nevertheless, several classes and methods are documented as obsolete. For instance, the java.util.Dictionary<K,V> class is marked as obsolete; new code should use java.util.Map<K,V> instead [API 2014].

Obsolete Methods and Classes

The methods and classes listed in the following table must not be used:

Class or Method

Replacement

Rule

java.lang.Character.isJavaLetter()

java.lang.Character.isJavaIdentifierStart()


java.lang.Character.isJavaLetterOrDigit()

java.lang.Character.isJavaIdentifierPart()


java.lang.Character.isSpace()

java.lang.Character.isWhitespace()


java.lang.Class.newInstance()

java.lang.reflect.Constructor.newInstance()

ERR06-J. Do not throw undeclared checked exceptions

java.util.Date (many methods)

java.util.Calendar


java.util.Dictionary<K,V>

java.util.Map<K,V>


java.util.Properties.save()

java.util.Properties.store()


java.lang.Thread.run()

java.lang.Thread.start()

THI00-J. Do not invoke Thread.run()

java.lang.Thread.stop()

java.lang.Thread.interrupt()

THI05-J. Do not use Thread.stop() to terminate threads

java.lang.ThreadGroup (many methods)

java.util.concurrent.Executor

THI01-J. Do not invoke ThreadGroup methods

java.util.Datejava.time (since Java 8)

The Java Virtual Machine Profiler Interface (JVMPI) and JVM Debug Interface (JVMDI) are also deprecated and have been replaced by the JVM Tool Interface (JVMTI) (see ENV05-J. Do not deploy an application that can be remotely monitored for more information).

Risk Assessment

Using deprecated or obsolete classes or methods in program code can lead to erroneous behavior.

Rule

Severity

Likelihood

Remediation Cost

Priority

Level

MET02-J

Low

Unlikely

Medium

P2

L3

Automated Detection

Detecting uses of deprecated methods is straightforward. Obsolete methods have no automatic means of detection.

ToolVersionCheckerDescription
Parasoft Jtest
2024.1
CERT.MET02.DPRAPI
CERT.MET02.THRD		Do not use deprecated APIs
Avoid calling unsafe deprecated methods of 'Thread' and 'Runtime'
SonarQube
9.9
S1874"@Deprecated" code should not be used

Related Guidelines

ISO/IEC TR 24772:2010

Deprecated Language Features [MEM]

MITRE CWE

CWE-589, Call to Non-ubiquitous API

Android Implementation Details

The Android SDK has deprecated and obsolete APIs. Also, there may exist incompatible APIs depending on the SDK version. Consequently, it is recommended that developers refer to the "Android API Differences Report" and consider replacing deprecated APIs.

Bibliography

[API 2014]

Deprecated API
Interface Map<K,V>

[SDN 2008]

Bug database, Bug ID 4264153




8 Comments

  1. Robert Seacord (Manager)

    I tried to rewrite this a bit, but it is really hard to tell what is going on here.

    There is a similar rule in C that is more precise MSC34-C. Do not use deprecated or obsolescent functions

    This needs to be more precise. Do we really mean deprecated or obsolete classes and methods? Deprecated is well-defined, but which classes are obsolete? For example, is java.util.Calendar obsolete? The Java API doesn't say that it is. If we can't point to a list, we need to provide a list here.

    1. David Svoboda

      A list of methods with the @deprecated annotation is unnecessary, as such methods are automatically detectable both in the source code and API documentation. It's also really big.

      A list of obsolete methods, fields, and classes is harder, as there is no obsolete tag. Lots of stuff marked obsolete in the APIIs, some is outside our scope, (such as AWT methods). The only obsolete classes I can find are java.util.Dictionary and java.rmi.server.SocketSecurityException. The best we could do is provide a homegrown list of things considered obsolete in our own Java standard. I have started such a list, someone needs to scour the rules to complete the list.

      There is some stuff in here about thread-unsafe methods & classes. Ideally that stuff should go into a concurrency rule, but I'm not sure which one. Perhaps folded into the intro?

  2. Dhruv Mohindra

    java.text.SimpleDateFormat can be used for date related stuff.

  3. Robert Seacord (Manager)

    I feel like the guideline THI05-J. Do not use Thread.stop() to terminate threads is referenced at least one too many times in this rule.

    I think because there is a separate rule saying don't call "java.lang.Thread.stop()" it is better not to include it here. This means, for example, a static analyzer would need to determine which of this two rules to list this as a violation of. Consequently, I'm removing this from the table and eliminating the additional "Guideline" column.

  4. Masaki Kubo

    The last sentence:

    Finally, several classes and methods impose particular limitations on their use. For instance, all of the subclasses of the abstract class java.text.Format are thread-unsafe. These classes must be avoided in multithreaded code.

    seems to have little to do with this rule and could be eliminated.

    1. David Svoboda

      Agreed. There are more appropriate rules addressing specific limitations such as thread safety.

  5. Yozo TODA

    Someone commented on the japanese version about the notations Dictionary and Map;

    "Map is denoted as generic type but Dictionary is denoted as non-generic type. Why?"

    Java6 API document describes them both as generic, hence I revised Dictionary as generic type Dictionary<K,V>.

     

    BTW, as far as I can trace, Dictionary has been introduced at JDK 1.0 and obsolete since J2SE 1.3.

    When was it marked as obsolete?

  6. David Svoboda

    Why is the severity high? AFAICT the worst that can arise from invoking these methods is a surprise exception.