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