1 .\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
   2 .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3 .\"
   4 .\" This code is free software; you can redistribute it and/or modify it
   5 .\" under the terms of the GNU General Public License version 2 only, as
   6 .\" published by the Free Software Foundation.
   7 .\"
   8 .\" This code is distributed in the hope that it will be useful, but WITHOUT
   9 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  11 .\" version 2 for more details (a copy is included in the LICENSE file that
  12 .\" accompanied this code).
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License version
  15 .\" 2 along with this work; if not, write to the Free Software Foundation,
  16 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  17 .\"
  18 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  19 .\" or visit www.oracle.com if you need additional information or have any
  20 .\" questions.
  21 .\"
  22 .\" Automatically generated by Pandoc 2.3.1
  23 .\"
  24 .TH "JDEPRSCAN" "1" "2020" "JDK 14" "JDK Commands"
  25 .hy
  26 .SH NAME
  27 .PP
  28 jdeprscan \- static analysis tool that scans a jar file (or some other
  29 aggregation of class files) for uses of deprecated API elements
  30 .SH SYNOPSIS
  31 .PP
  32 \f[CB]jdeprscan\f[R] [\f[I]options\f[R]]
  33 {\f[I]dir\f[R]|\f[I]jar\f[R]|\f[I]class\f[R]}
  34 .TP
  35 .B \f[I]options\f[R]
  36 See \f[B]Options for the jdeprscan Command\f[R]
  37 .RS
  38 .RE
  39 .TP
  40 .B \f[I]dir\f[R]|\f[I]jar\f[R]|\f[I]class\f[R]
  41 \f[CB]jdeprscan\f[R] command scans each argument for usages of deprecated
  42 APIs.
  43 The arguments can be a:
  44 .RS
  45 .IP \[bu] 2
  46 \f[I]dir\f[R]: Directory
  47 .IP \[bu] 2
  48 \f[I]jar\f[R]: JAR file
  49 .IP \[bu] 2
  50 \f[I]class\f[R]: Class name or class file
  51 .PP
  52 The class name should use a dot (\f[CB]\&.\f[R]) as a separator.
  53 For example:
  54 .PP
  55 \f[CB]java.lang.Thread\f[R]
  56 .PP
  57 For nested classes, the dollar sign \f[CB]$\f[R] separator character
  58 should be used.
  59 For example:
  60 .PP
  61 \f[CB]java.lang.Thread$State\f[R]
  62 .PP
  63 A class file can also be named.
  64 For example:
  65 .PP
  66 \f[CB]build/classes/java/lang/Thread$State.class\f[R]
  67 .RE
  68 .SH DESCRIPTION
  69 .PP
  70 The \f[CB]jdeprscan\f[R] tool is a static analysis tool provided by the
  71 JDK that scans a JAR file or some other aggregation of class files for
  72 uses of deprecated API elements.
  73 The deprecated APIs identified by the \f[CB]jdeprscan\f[R] tool are only
  74 those that are defined by Java SE.
  75 Deprecated APIs defined by third\-party libraries aren\[aq]t reported.
  76 .PP
  77 To scan a JAR file or a set of class files, you must first ensure that
  78 all of the classes that the scanned classes depend upon are present in
  79 the class path.
  80 Set the class path using the \f[CB]\-\-class\-path\f[R] option described
  81 in \f[B]Options for the jdeprscan Command\f[R].
  82 Typically, you would use the same class path as the one that you use
  83 when invoking your application.
  84 .PP
  85 If the \f[CB]jdeprscan\f[R] can\[aq]t find all the dependent classes, it
  86 will generate an error message for each class that\[aq]s missing.
  87 These error messages are typically of the form:
  88 .RS
  89 .PP
  90 \f[CB]error:\ cannot\ find\ class\ ...\f[R]
  91 .RE
  92 .PP
  93 If these errors occur, then you must adjust the class path so that it
  94 includes all dependent classes.
  95 .SH OPTIONS FOR THE JDEPRSCAN COMMAND
  96 .PP
  97 The following options are available:
  98 .TP
  99 .B \f[CB]\-\-class\-path\f[R] \f[I]path\f[R]
 100 Provides a search path for resolution of dependent classes.
 101 .RS
 102 .PP
 103 \f[I]path\f[R] can be a search path that consists of one or more
 104 directories separated by the system\-specific path separator.
 105 For example:
 106 .IP \[bu] 2
 107 \f[B]Oracle Solaris, Linux, and OS X:\f[R]
 108 .RS 2
 109 .RS
 110 .PP
 111 \f[CB]\-\-class\-path\ /some/directory:/another/different/dir\f[R]
 112 .RE
 113 .RE
 114 .PP
 115 \f[B]Note:\f[R]
 116 .PP
 117 On Windows, use a semicolon (\f[CB];\f[R]) as the separator instead of a
 118 colon (\f[CB]:\f[R]).
 119 .IP \[bu] 2
 120 \f[B]Windows:\f[R]
 121 .RS 2
 122 .RS
 123 .PP
 124 \f[CB]\-\-class\-path\ \\some\\directory;\\another\\different\\dir\f[R]
 125 .RE
 126 .RE
 127 .RE
 128 .TP
 129 .B \f[CB]\-\-for\-removal\f[R]
 130 Limits scanning or listing to APIs that are deprecated for removal.
 131 Can\[aq]t be used with a release value of 6, 7, or 8.
 132 .RS
 133 .RE
 134 .TP
 135 .B \f[CB]\-\-full\-version\f[R]
 136 Prints out the full version string of the tool.
 137 .RS
 138 .RE
 139 .TP
 140 .B \f[CB]\-\-help\f[R] or \f[CB]\-h\f[R]
 141 Prints out a full help message.
 142 .RS
 143 .RE
 144 .TP
 145 .B \f[CB]\-\-list\f[R] or \f[CB]\-l\f[R]
 146 Prints the set of deprecated APIs.
 147 No scanning is done, so no directory, jar, or class arguments should be
 148 provided.
 149 .RS
 150 .RE
 151 .TP
 152 .B \f[CB]\-\-release\f[R] \f[CB]6\f[R]|\f[CB]7\f[R]|\f[CB]8\f[R]|\f[CB]9\f[R]
 153 Specifies the Java SE release that provides the set of deprecated APIs
 154 for scanning.
 155 .RS
 156 .RE
 157 .TP
 158 .B \f[CB]\-\-verbose\f[R] or \f[CB]\-v\f[R]
 159 Enables additional message output during processing.
 160 .RS
 161 .RE
 162 .TP
 163 .B \f[CB]\-\-version\f[R]
 164 Prints out the abbreviated version string of the tool.
 165 .RS
 166 .RE
 167 .SH EXAMPLE OF JDEPRSCAN OUTPUT
 168 .PP
 169 The JAR file for this library will be named something similar to
 170 \f[CB]commons\-math3\-3.6.1.jar\f[R].
 171 To scan this JAR file for the use of deprecated APIs, run the following
 172 command:
 173 .RS
 174 .PP
 175 \f[CB]jdeprscan\ commons\-math3\-3.6.1.jar\f[R]
 176 .RE
 177 .PP
 178 This command produces several lines of output.
 179 For example, one line of output might be:
 180 .IP
 181 .nf
 182 \f[CB]
 183 class\ org/apache/commons/math3/util/MathUtils\ uses\ deprecated\ method\ java/lang/Double::<init>(D)V
 184 \f[R]
 185 .fi
 186 .PP
 187 \f[B]Note:\f[R]
 188 .PP
 189 The class name is specified using the slash\-separated binary name as
 190 described in JVMS 4.2.1.
 191 This is the form used internally in class files.
 192 .PP
 193 The deprecated API it uses is a method on the \f[CB]java.lang.Double\f[R]
 194 class.
 195 .PP
 196 The name of the deprecated method is \f[CB]<init>\f[R], which is a special
 197 name that means that the method is actually a constructor.
 198 Another special name is \f[CB]<clinit>\f[R], which indicates a class
 199 static initializer.
 200 .PP
 201 Other methods are listed just by their method name.
 202 Following the method name is the argument list and return type:
 203 .RS
 204 .PP
 205 \f[CB](D)V\f[R]
 206 .RE
 207 .PP
 208 This indicates that it takes just one double value (a primitive) and
 209 returns void.
 210 The argument and return types can become cryptic.
 211 For example, another line of output might be:
 212 .IP
 213 .nf
 214 \f[CB]
 215 class\ org/apache/commons/math3/util/Precision\ uses\ deprecated\ method\ java/math/BigDecimal::setScale(II)Ljava/math/BigDecimal;
 216 \f[R]
 217 .fi
 218 .PP
 219 In this line of output, the deprecated method is on class
 220 \f[CB]java.math.BigDecimal\f[R], and the method is \f[CB]setScale()\f[R].
 221 In this case, the \f[CB](II)\f[R] means that it takes two \f[CB]int\f[R]
 222 arguments.
 223 The \f[CB]Ljava/math/BigDecimal;\f[R] after the parentheses means that it
 224 returns a reference to \f[CB]java.math.BigDecimal\f[R].
 225 .SH JDEPRSCAN ANALYSIS CAN BE VERSION\-SPECIFIC
 226 .PP
 227 You can use \f[CB]jdeprscan\f[R] relative to the previous three JDK
 228 releases.
 229 For example, if you are running JDK 9, then you can check against JDK 8,
 230 7, and 6.
 231 .PP
 232 As an example, look at this code snippet:
 233 .IP
 234 .nf
 235 \f[CB]
 236 public\ class\ Deprecations\ {
 237 \ \ \ SecurityManager\ sm\ =\ new\ RMISecurityManager();\ \ \ \ //\ deprecated\ in\ 8
 238 \ \ \ Boolean\ b2\ =\ new\ Boolean(true);\ \ \ \ \ \ \ \ \ \ //\ deprecated\ in\ 9
 239 }
 240 \f[R]
 241 .fi
 242 .PP
 243 The complete class compiles without warnings in JDK 7.
 244 .PP
 245 If you run \f[CB]jdeprscan\f[R] on a system with JDK 9, then you see:
 246 .IP
 247 .nf
 248 \f[CB]
 249 $\ jdeprscan\ \-\-class\-path\ classes\ \-\-release\ 7\ example.Deprecations
 250 (no\ output)
 251 \f[R]
 252 .fi
 253 .PP
 254 Run \f[CB]jdeprscan\f[R] with a release value of 8:
 255 .IP
 256 .nf
 257 \f[CB]
 258 $\ jdeprscan\ \-\-class\-path\ classes\ \-\-release\ 8\ example.Deprecations
 259 class\ example/Deprecations\ uses\ type\ java/rmi/RMISecurityManager\ deprecated
 260 class\ example/Deprecations\ uses\ method\ in\ type\ java/rmi/RMISecurityManager\ deprecated
 261 \f[R]
 262 .fi
 263 .PP
 264 Run \f[CB]jdeprscan\f[R] on JDK 9:
 265 .IP
 266 .nf
 267 \f[CB]
 268 $\ jdeprscan\ \-\-class\-path\ classes\ example.Deprecations
 269 class\ example/Deprecations\ uses\ type\ java/rmi/RMISecurityManager\ deprecated
 270 class\ example/Deprecations\ uses\ method\ in\ type\ java/rmi/RMISecurityManager\ deprecated
 271 class\ example/Deprecations\ uses\ method\ java/lang/Boolean\ <init>\ (Z)V\ deprecated
 272 \f[R]
 273 .fi