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" "2018" "JDK 13" "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