org.openjdk.tools.jdeprscan.readme.md Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javac-shaded Show documentation
A repackaged and shaded copy of javac
The newest version!



JDeprScan Tool Command Reference
-----

**NAME**

        jdeprscan - Java deprecation scanner

**SYNOPSIS**

        jdeprscan [options] {dir | jar | class} ...

**OPTIONS**

        --class-path PATH

            Sets the classpath to PATH.

        --for-removal

            Limit reporting to deprecations whose forRemoval element
            is true.

        --full-version

            Prints the full version string of the tool and exits.

        -h
        --help

            Prints a help message and exits.

        -l
        --list

            Prints out the set of deprecated APIs.

        --release 6|7|8|9

            Specifies the Java SE release that is the source of
            the list of deprecated APIs. If no --release option is
            provided, the latest release is used.

        -v
        --verbose

            Enables additional output.

        --version

            Prints the version string of the tool and exits.

**DESCRIPTION**

**jdeprscan** scans a class library for uses of deprecated APIs.
**jdeprscan** processes one or more arguments, which can be any
combination of a directory, a jar file, or a class name.

A directory argument must specify a path to a directory hierarchy that
reflects the Java package hierarchy of the classes it contains.
**jdeprscan** will scan each class found in the directory hierarchy
and report information about how those classes use deprecated APIs.

Given a jar file, **jdeprscan** will scan the classes found within
that jar file and report information about how those classes use
deprecated APIs.

Given a class file, **jdeprscan** will scan that class and report
its use of deprecated APIs.

Given a class name, **jdeprscan** will search for that class on the
classpath, scan that class, and report information about how that
class uses deprecated APIs. The class name must use the fully
qualified binary name of the class, as described in the
[Java Language Specification, section 13.1][jls131]. This form uses
the '$' character instead of '.' as the separator for nested class names.
For example, the `Thread.State` enum would be specified using the string

        java.lang.Thread$State

The `--class-path` option specifies the classpath used for
class searching. The classpath is used for classes named on the
command line, as well as for dependencies of the classes in jar file
or directory hierarchy to be scanned.

The `--for-removal` option limits output to uses of deprecated APIs
whose `@Deprecated` annotation includes the `forRemoval` element with
the value `true`. Note: the `forRemoval` attribute of the
`@Deprecated` annotation did not exist prior to Java SE 9, so this
option cannot be used with a release value of 6, 7, or 8.

The `--release` option specifies the Java SE specification version
that determines the set of deprecated APIs for which scanning is
done. This is useful if a deprecation report is desired that lists
uses of deprecated APIs as of a particular release in the past. If no
`--release` option is given, the latest release is used.

The `--list` and `-l` options will list the known set of deprecated
APIs instead of doing any scanning. Since no scanning is done,
no directory, jar, or class arguments should be provided. The set
of deprecated APIs listed is affected by the `--release` and the
`--for-removal` options.


**EXAMPLE OUTPUT**

The output is a report that lists program elements that use deprecated
APIs. Output is subject to change.

Consider the following declarations from Java SE 9:

        // java.lang.Boolean

        @Deprecated(since="9")
        public Boolean(boolean value)

        // java.lang.Runtime

        @Deprecated(since="1.2", forRemoval=true)
        public static void runFinalizersOnExit(boolean value)

Running **jdeprscan** over a class that calls these methods will result
in output something like the following:

        class Example uses method java/lang/Boolean.(Z)V deprecated
        class Example uses method java/lang/Runtime.runFinalizersOnExit(Z)V deprecated for removal

Running **jdeprscan** with the `--list` option will result in output
including something like the following:

        ...
        @Deprecated(since="9") java.lang.Boolean(boolean)
        @Deprecated(since="1.2", forRemoval=true) void java.lang.Runtime.runFinalizersOnExit(boolean)
        ...

**NOTES**

The **jdeprscan** tool operates by opening Java class files and
reading their structures directly, particularly the constant
pool. Because of this, **jdeprscan** can tell _that_ a deprecated API
is used, but it often cannot tell _where_ in the class that API is
used.

The **jdeprscan** tool doesn't follow the same set of rules for
emitting warnings as specified for Java compilers in [JLS section
9.6.4.6][jls9646]. In particular, **jdeprscan** does not respond to
the `@SuppressWarnings` annotation, as that is significant only in
source code, not in class files. In addition, **jdeprscan** emits
warnings even if the usage is within the API element that is
deprecated and when the use and declaration are within the same
outermost class.

[jls9646]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-9.html#jls-9.6.4.6

[jls131]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1