Mercurial Mercurial > jdk-sandbox / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/jdk.jdeps/share/man/jdeprscan.1
changeset 55140 d4890c3721be 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.jdeps/share/man/jdeprscan.1	Fri May 31 17:27:28 2019 -0700
@@ -0,0 +1,273 @@
+.\" Copyright (c) 1994, 2019, 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" "2018" "JDK 13" "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]Oracle Solaris, 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
jdk-sandbox