1 <!--
2
3 Copyright (c) 2016, 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 -cp PATH
43 --class-path PATH
44
45 Sets the classpath to PATH.
46
47 --for-removal
48
49 Limit reporting to deprecations whose forRemoval element
50 is true.
51
52 --full-version
53
54 Prints the full version string of the tool and exits.
55
56 -h
57 --help
58
59 Prints a help message and exits.
60
61 -l
62 --list
63
64 Prints out the set of deprecated APIs.
65
66 --release 6|7|8|9
67
68 Specifies the Java SE release that is the source of
69 the list of deprecated APIs. If no --release option is
70 provided, the latest release is used.
71
72 -v
73 --verbose
74
75 Enables additional output.
76
77 --version
78
79 Prints the version string of the tool and exits.
80
81 **DESCRIPTION**
82
83 **jdeprscan** scans a class library for uses of deprecated APIs.
84 **jdeprscan** processes one or more arguments, which can be any
85 combination of a directory, a jar file, or a class name.
86
87 A directory argument must specify a path to a directory hierarchy that
88 reflects the Java package hierarchy of the classes it contains.
89 **jdeprscan** will scan each class found in the directory hierarchy
90 and report information about how those classes use deprecated APIs.
91
92 Given a jar file, **jdeprscan** will scan the classes found within
93 that jar file and report information about how those classes use
94 deprecated APIs.
95
96 Given a class name, **jdeprscan** will search for that class on the
97 classpath, scan that class, and report information about how that
98 class uses deprecated APIs. The class name must use the fully
99 qualified binary name of the class, as described in the
100 [Java Language Specification, section 13.1][jls131]. This form uses
101 the '$' character instead of '.' as the separator for nested class names.
102 For example, the `Thread.State` enum would be specified using the string
103
104 java.lang.Thread$State
105
106 The `--class-path` and `-cp` options specify the classpath used for
107 class searching. The classpath is used for classes named on the
108 command line, as well as for dependencies of the classes in jar file
109 or directory hierarchy to be scanned.
110
111 The `--for-removal` option limits output to uses of deprecated APIs
112 whose `@Deprecated` annotation includes the `forRemoval` element with
113 the value `true`. Note: the `forRemoval` attribute of the
114 `@Deprecated` annotation did not exist prior to Java SE 9, so this
115 option cannot be used with a release value of 6, 7, or 8.
116
117 The `--release` option specifies the Java SE specification version
118 that determines the set of deprecated APIs for which scanning is
119 done. This is useful if a deprecation report is desired that lists
120 uses of deprecated APIs as of a particular release in the past. If no
121 `--release` option is given, the latest release is used.
122
123 The `--list` and `-l` options will list the known set of deprecated
124 APIs instead of doing any scanning. Since no scanning is done,
125 no directory, jar, or class arguments should be provided. The set
126 of deprecated APIs listed is affected by the `--release` and the
127 `--for-removal` options.
128
129
130 **EXAMPLE OUTPUT**
131
132 The output is a report that lists program elements that use deprecated
133 APIs. Output is subject to change.
134
135 Consider the following declarations from Java SE 9:
136
137 // java.lang.Boolean
138
139 @Deprecated(since="9")
140 public Boolean(boolean value)
141
142 // java.lang.Runtime
143
144 @Deprecated(since="1.2", forRemoval=true)
145 public static void runFinalizersOnExit(boolean value)
146
147 Running **jdeprscan** over a class that calls these methods will result
148 in output something like the following:
149
150 class Example uses method java/lang/Boolean.<init>(Z)V deprecated
151 class Example uses method java/lang/Runtime.runFinalizersOnExit(Z)V deprecated for removal
152
153 Running **jdeprscan** with the `--list` option will result in output
154 including something like the following:
155
156 ...
157 @Deprecated(since="9") java.lang.Boolean(boolean)
158 @Deprecated(since="1.2", forRemoval=true) void java.lang.Runtime.runFinalizersOnExit(boolean)
159 ...
160
161 **NOTES**
162
163 The **jdeprscan** tool operates by opening Java class files and
164 reading their structures directly, particularly the constant
165 pool. Because of this, **jdeprscan** can tell _that_ a deprecated API
166 is used, but it often cannot tell _where_ in the class that API is
167 used.
168
169 The **jdeprscan** tool doesn't follow the same set of rules for
170 emitting warnings as specified for Java compilers in [JLS section
171 9.6.4.6][jls9646]. In particular, **jdeprscan** does not respond to
172 the `@SuppressWarnings` annotation, as that is significant only in
173 source code, not in class files. In addition, **jdeprscan** emits
174 warnings even if the usage is within the API element that is
175 deprecated and when the use and declaration are within the same
176 outermost class.
177
178 [jls9646]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-9.html#jls-9.6.4.6
179
180 [jls131]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1