1 <!--
   2 
   3 Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
   4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5 
   6 This code is free software; you can redistribute it and/or modify it
   7 under the terms of the GNU General Public License version 2 only, as
   8 published by the Free Software Foundation.  Oracle designates this
   9 particular file as subject to the "Classpath" exception as provided
  10 by Oracle in the LICENSE file that accompanied this code.
  11 
  12 This code is distributed in the hope that it will be useful, but WITHOUT
  13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 version 2 for more details (a copy is included in the LICENSE file that
  16 accompanied this code).
  17 
  18 You should have received a copy of the GNU General Public License version
  19 2 along with this work; if not, write to the Free Software Foundation,
  20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  21 
  22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  23 or visit www.oracle.com if you need additional information or have any
  24 questions.
  25 
  26 -->
  27 
  28 
  29 JDeprScan Tool Command Reference
  30 -----
  31 
  32 **NAME**
  33 
  34         jdeprscan - Java deprecation scanner
  35 
  36 **SYNOPSIS**
  37 
  38         jdeprscan [options] {dir | jar | class} ...
  39 
  40 **OPTIONS**
  41 
  42         --class-path PATH
  43 
  44             Sets the classpath to PATH.
  45 
  46         --for-removal
  47 
  48             Limit reporting to deprecations whose forRemoval element
  49             is true.
  50 
  51         --full-version
  52 
  53             Prints the full version string of the tool and exits.
  54 
  55         -h
  56         --help
  57 
  58             Prints a help message and exits.
  59 
  60         -l
  61         --list
  62 
  63             Prints out the set of deprecated APIs.
  64 
  65         --release 6|7|8|9|10
  66 
  67             Specifies the Java SE release that is the source of
  68             the list of deprecated APIs. If no --release option is
  69             provided, the latest release is used.
  70 
  71         -v
  72         --verbose
  73 
  74             Enables additional output.
  75 
  76         --version
  77 
  78             Prints the version string of the tool and exits.
  79 
  80 **DESCRIPTION**
  81 
  82 **jdeprscan** scans a class library for uses of deprecated APIs.
  83 **jdeprscan** processes one or more arguments, which can be any
  84 combination of a directory, a jar file, or a class name.
  85 
  86 A directory argument must specify a path to a directory hierarchy that
  87 reflects the Java package hierarchy of the classes it contains.
  88 **jdeprscan** will scan each class found in the directory hierarchy
  89 and report information about how those classes use deprecated APIs.
  90 
  91 Given a jar file, **jdeprscan** will scan the classes found within
  92 that jar file and report information about how those classes use
  93 deprecated APIs.
  94 
  95 Given a class file, **jdeprscan** will scan that class and report
  96 its use of deprecated APIs.
  97 
  98 Given a class name, **jdeprscan** will search for that class on the
  99 classpath, scan that class, and report information about how that
 100 class uses deprecated APIs. The class name must use the fully
 101 qualified binary name of the class, as described in the
 102 [Java Language Specification, section 13.1][jls131]. This form uses
 103 the '$' character instead of '.' as the separator for nested class names.
 104 For example, the `Thread.State` enum would be specified using the string
 105 
 106         java.lang.Thread$State
 107 
 108 The `--class-path` option specifies the classpath used for
 109 class searching. The classpath is used for classes named on the
 110 command line, as well as for dependencies of the classes in jar file
 111 or directory hierarchy to be scanned.
 112 
 113 The `--for-removal` option limits output to uses of deprecated APIs
 114 whose `@Deprecated` annotation includes the `forRemoval` element with
 115 the value `true`. Note: the `forRemoval` attribute of the
 116 `@Deprecated` annotation did not exist prior to Java SE 9, so this
 117 option cannot be used with a release value of 6, 7, or 8.
 118 
 119 The `--release` option specifies the Java SE specification version
 120 that determines the set of deprecated APIs for which scanning is
 121 done. This is useful if a deprecation report is desired that lists
 122 uses of deprecated APIs as of a particular release in the past. If no
 123 `--release` option is given, the latest release is used.
 124 
 125 The `--list` and `-l` options will list the known set of deprecated
 126 APIs instead of doing any scanning. Since no scanning is done,
 127 no directory, jar, or class arguments should be provided. The set
 128 of deprecated APIs listed is affected by the `--release` and the
 129 `--for-removal` options.
 130 
 131 
 132 **EXAMPLE OUTPUT**
 133 
 134 The output is a report that lists program elements that use deprecated
 135 APIs. Output is subject to change.
 136 
 137 Consider the following declarations from Java SE 9:
 138 
 139         // java.lang.Boolean
 140 
 141         @Deprecated(since="9")
 142         public Boolean(boolean value)
 143 
 144         // java.lang.Runtime
 145 
 146         @Deprecated(since="1.2", forRemoval=true)
 147         public static void runFinalizersOnExit(boolean value)
 148 
 149 Running **jdeprscan** over a class that calls these methods will result
 150 in output something like the following:
 151 
 152         class Example uses method java/lang/Boolean.<init>(Z)V deprecated
 153         class Example uses method java/lang/Runtime.runFinalizersOnExit(Z)V deprecated for removal
 154 
 155 Running **jdeprscan** with the `--list` option will result in output
 156 including something like the following:
 157 
 158         ...
 159         @Deprecated(since="9") java.lang.Boolean(boolean)
 160         @Deprecated(since="1.2", forRemoval=true) void java.lang.Runtime.runFinalizersOnExit(boolean)
 161         ...
 162 
 163 **NOTES**
 164 
 165 The **jdeprscan** tool operates by opening Java class files and
 166 reading their structures directly, particularly the constant
 167 pool. Because of this, **jdeprscan** can tell _that_ a deprecated API
 168 is used, but it often cannot tell _where_ in the class that API is
 169 used.
 170 
 171 The **jdeprscan** tool doesn't follow the same set of rules for
 172 emitting warnings as specified for Java compilers in [JLS section
 173 9.6.4.6][jls9646]. In particular, **jdeprscan** does not respond to
 174 the `@SuppressWarnings` annotation, as that is significant only in
 175 source code, not in class files. In addition, **jdeprscan** emits
 176 warnings even if the usage is within the API element that is
 177 deprecated and when the use and declaration are within the same
 178 outermost class.
 179 
 180 [jls9646]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-9.html#jls-9.6.4.6
 181 
 182 [jls131]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1