| .\" Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved. |
| .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| .\" |
| .\" This code is free software; you can redistribute it and/or modify it |
| .\" under the terms of the GNU General Public License version 2 only, as |
| .\" published by the Free Software Foundation. |
| .\" |
| .\" This code is distributed in the hope that it will be useful, but WITHOUT |
| .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| .\" version 2 for more details (a copy is included in the LICENSE file that |
| .\" accompanied this code). |
| .\" |
| .\" You should have received a copy of the GNU General Public License version |
| .\" 2 along with this work; if not, write to the Free Software Foundation, |
| .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| .\" |
| .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| .\" or visit www.oracle.com if you need additional information or have any |
| .\" questions. |
| .\" |
| .\" Automatically generated by Pandoc 2.3.1 |
| .\" |
| .TH "JDEPRSCAN" "1" "2021" "JDK 17" "JDK Commands" |
| .hy |
| .SH NAME |
| .PP |
| jdeprscan \- static analysis tool that scans a jar file (or some other |
| aggregation of class files) for uses of deprecated API elements |
| .SH SYNOPSIS |
| .PP |
| \f[CB]jdeprscan\f[R] [\f[I]options\f[R]] |
| {\f[I]dir\f[R]|\f[I]jar\f[R]|\f[I]class\f[R]} |
| .TP |
| .B \f[I]options\f[R] |
| See \f[B]Options for the jdeprscan Command\f[R] |
| .RS |
| .RE |
| .TP |
| .B \f[I]dir\f[R]|\f[I]jar\f[R]|\f[I]class\f[R] |
| \f[CB]jdeprscan\f[R] command scans each argument for usages of deprecated |
| APIs. |
| The arguments can be a: |
| .RS |
| .IP \[bu] 2 |
| \f[I]dir\f[R]: Directory |
| .IP \[bu] 2 |
| \f[I]jar\f[R]: JAR file |
| .IP \[bu] 2 |
| \f[I]class\f[R]: Class name or class file |
| .PP |
| The class name should use a dot (\f[CB]\&.\f[R]) as a separator. |
| For example: |
| .PP |
| \f[CB]java.lang.Thread\f[R] |
| .PP |
| For nested classes, the dollar sign \f[CB]$\f[R] separator character |
| should be used. |
| For example: |
| .PP |
| \f[CB]java.lang.Thread$State\f[R] |
| .PP |
| A class file can also be named. |
| For example: |
| .PP |
| \f[CB]build/classes/java/lang/Thread$State.class\f[R] |
| .RE |
| .SH DESCRIPTION |
| .PP |
| The \f[CB]jdeprscan\f[R] tool is a static analysis tool provided by the |
| JDK that scans a JAR file or some other aggregation of class files for |
| uses of deprecated API elements. |
| The deprecated APIs identified by the \f[CB]jdeprscan\f[R] tool are only |
| those that are defined by Java SE. |
| Deprecated APIs defined by third\-party libraries aren\[aq]t reported. |
| .PP |
| To scan a JAR file or a set of class files, you must first ensure that |
| all of the classes that the scanned classes depend upon are present in |
| the class path. |
| Set the class path using the \f[CB]\-\-class\-path\f[R] option described |
| in \f[B]Options for the jdeprscan Command\f[R]. |
| Typically, you would use the same class path as the one that you use |
| when invoking your application. |
| .PP |
| If the \f[CB]jdeprscan\f[R] can\[aq]t find all the dependent classes, it |
| will generate an error message for each class that\[aq]s missing. |
| These error messages are typically of the form: |
| .RS |
| .PP |
| \f[CB]error:\ cannot\ find\ class\ ...\f[R] |
| .RE |
| .PP |
| If these errors occur, then you must adjust the class path so that it |
| includes all dependent classes. |
| .SH OPTIONS FOR THE JDEPRSCAN COMMAND |
| .PP |
| The following options are available: |
| .TP |
| .B \f[CB]\-\-class\-path\f[R] \f[I]path\f[R] |
| Provides a search path for resolution of dependent classes. |
| .RS |
| .PP |
| \f[I]path\f[R] can be a search path that consists of one or more |
| directories separated by the system\-specific path separator. |
| For example: |
| .IP \[bu] 2 |
| \f[B]Linux and OS X:\f[R] |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-\-class\-path\ /some/directory:/another/different/dir\f[R] |
| .RE |
| .RE |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| On Windows, use a semicolon (\f[CB];\f[R]) as the separator instead of a |
| colon (\f[CB]:\f[R]). |
| .IP \[bu] 2 |
| \f[B]Windows:\f[R] |
| .RS 2 |
| .RS |
| .PP |
| \f[CB]\-\-class\-path\ \\some\\directory;\\another\\different\\dir\f[R] |
| .RE |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-\-for\-removal\f[R] |
| Limits scanning or listing to APIs that are deprecated for removal. |
| Can\[aq]t be used with a release value of 6, 7, or 8. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-full\-version\f[R] |
| Prints out the full version string of the tool. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-help\f[R] or \f[CB]\-h\f[R] |
| Prints out a full help message. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-list\f[R] or \f[CB]\-l\f[R] |
| Prints the set of deprecated APIs. |
| No scanning is done, so no directory, jar, or class arguments should be |
| provided. |
| .RS |
| .RE |
| .TP |
| .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] |
| Specifies the Java SE release that provides the set of deprecated APIs |
| for scanning. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-verbose\f[R] or \f[CB]\-v\f[R] |
| Enables additional message output during processing. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-\-version\f[R] |
| Prints out the abbreviated version string of the tool. |
| .RS |
| .RE |
| .SH EXAMPLE OF JDEPRSCAN OUTPUT |
| .PP |
| The JAR file for this library will be named something similar to |
| \f[CB]commons\-math3\-3.6.1.jar\f[R]. |
| To scan this JAR file for the use of deprecated APIs, run the following |
| command: |
| .RS |
| .PP |
| \f[CB]jdeprscan\ commons\-math3\-3.6.1.jar\f[R] |
| .RE |
| .PP |
| This command produces several lines of output. |
| For example, one line of output might be: |
| .IP |
| .nf |
| \f[CB] |
| class\ org/apache/commons/math3/util/MathUtils\ uses\ deprecated\ method\ java/lang/Double::<init>(D)V |
| \f[R] |
| .fi |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| The class name is specified using the slash\-separated binary name as |
| described in JVMS 4.2.1. |
| This is the form used internally in class files. |
| .PP |
| The deprecated API it uses is a method on the \f[CB]java.lang.Double\f[R] |
| class. |
| .PP |
| The name of the deprecated method is \f[CB]<init>\f[R], which is a special |
| name that means that the method is actually a constructor. |
| Another special name is \f[CB]<clinit>\f[R], which indicates a class |
| static initializer. |
| .PP |
| Other methods are listed just by their method name. |
| Following the method name is the argument list and return type: |
| .RS |
| .PP |
| \f[CB](D)V\f[R] |
| .RE |
| .PP |
| This indicates that it takes just one double value (a primitive) and |
| returns void. |
| The argument and return types can become cryptic. |
| For example, another line of output might be: |
| .IP |
| .nf |
| \f[CB] |
| class\ org/apache/commons/math3/util/Precision\ uses\ deprecated\ method\ java/math/BigDecimal::setScale(II)Ljava/math/BigDecimal; |
| \f[R] |
| .fi |
| .PP |
| In this line of output, the deprecated method is on class |
| \f[CB]java.math.BigDecimal\f[R], and the method is \f[CB]setScale()\f[R]. |
| In this case, the \f[CB](II)\f[R] means that it takes two \f[CB]int\f[R] |
| arguments. |
| The \f[CB]Ljava/math/BigDecimal;\f[R] after the parentheses means that it |
| returns a reference to \f[CB]java.math.BigDecimal\f[R]. |
| .SH JDEPRSCAN ANALYSIS CAN BE VERSION\-SPECIFIC |
| .PP |
| You can use \f[CB]jdeprscan\f[R] relative to the previous three JDK |
| releases. |
| For example, if you are running JDK 9, then you can check against JDK 8, |
| 7, and 6. |
| .PP |
| As an example, look at this code snippet: |
| .IP |
| .nf |
| \f[CB] |
| public\ class\ Deprecations\ { |
| \ \ \ SecurityManager\ sm\ =\ new\ RMISecurityManager();\ \ \ \ //\ deprecated\ in\ 8 |
| \ \ \ Boolean\ b2\ =\ new\ Boolean(true);\ \ \ \ \ \ \ \ \ \ //\ deprecated\ in\ 9 |
| } |
| \f[R] |
| .fi |
| .PP |
| The complete class compiles without warnings in JDK 7. |
| .PP |
| If you run \f[CB]jdeprscan\f[R] on a system with JDK 9, then you see: |
| .IP |
| .nf |
| \f[CB] |
| $\ jdeprscan\ \-\-class\-path\ classes\ \-\-release\ 7\ example.Deprecations |
| (no\ output) |
| \f[R] |
| .fi |
| .PP |
| Run \f[CB]jdeprscan\f[R] with a release value of 8: |
| .IP |
| .nf |
| \f[CB] |
| $\ jdeprscan\ \-\-class\-path\ classes\ \-\-release\ 8\ example.Deprecations |
| class\ example/Deprecations\ uses\ type\ java/rmi/RMISecurityManager\ deprecated |
| class\ example/Deprecations\ uses\ method\ in\ type\ java/rmi/RMISecurityManager\ deprecated |
| \f[R] |
| .fi |
| .PP |
| Run \f[CB]jdeprscan\f[R] on JDK 9: |
| .IP |
| .nf |
| \f[CB] |
| $\ jdeprscan\ \-\-class\-path\ classes\ example.Deprecations |
| class\ example/Deprecations\ uses\ type\ java/rmi/RMISecurityManager\ deprecated |
| class\ example/Deprecations\ uses\ method\ in\ type\ java/rmi/RMISecurityManager\ deprecated |
| class\ example/Deprecations\ uses\ method\ java/lang/Boolean\ <init>\ (Z)V\ deprecated |
| \f[R] |
| .fi |