com.sun.tools.jdeprscan.internals.md Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javac Show documentation
Show all versions of javac Show documentation
A repackaged copy of javac for Error Prone to depend on
JDeprScan Internals
-----
**EXPERIMENTAL OPTIONS**
--Xload-class CLASSNAME
Loads deprecation data from the class named CLASSNAME instead of from
the JDK image.
--Xload-csv CVSFILE
Loads deprecation data from file CSVFILE.
--Xload-dir DIR
Loads deprecation data from the class hierarchy rooted
at the directory named DIR.
--Xload-jar JARFILE
Loads deprecation data from the classes contained in the
jar file named JARFILE.
--Xload-jdk9 JAVA_HOME
Loads deprecation data from a modular JDK whose home
directory is at JAVA_HOME. This essentially adds the given
path to the system-modules location.
--Xload-old-jdk JAVA_HOME
Loads deprecation data from an old (non-modular) JDK whose
home directory is at JAVA_HOME. This essentially scans the
rt.jar file from that JDK.
--Xload-self
Loads deprecation data from the running JDK image by
traversing the entire jrt: filesystem. This differs from
-release 9, which traverses modules, packages, and classes by
starting from a set of root modules and using javax.lang.model
mechanisms (as opposed to filesystem mechanisms) for
traversing contained elements recursively.
--Xcompiler-arg ARG
Adds ARG to the list of arguments passed to the compiler.
--Xcsv-comment COMMENT
Adds a comment line containing COMMENT to the top of the CSV
that is emitted. Valid only when --Xprint-csv is
specified. More than one --Xcsv-comment option is permitted,
which will cause a corresponding number of comment lines to be
emitted to the CSV file.
--Xprint-csv
Prints out the loaded deprecation information in CSV format
to standard output. In this mode, no scanning is done, so
there must not be any additional directory, jar, or classname
arguments.
**CSV FILE SYNTAX**
The `-Xprint-csv` option causes **jdeprscan** to emit the loaded
deprecation data in CSV (comma-separated value) format. The general
syntax of CSV is documented in [RFC 4180][RFC] with supplemental
information in a [Wikipedia article][wiki].
The file is encoded in UTF-8.
The file consists of a series of lines. Any of the standard line
separators CR (U+000D), LF (U+000A), or a CR immediately followed by
LF, are supported. Newlines are only supported between records and
are not supported within field values.
Comment lines start with a `#` (U+0023) character in the first
column. The entire line is ignored up until the next line separator
sequence.
Each line is divided into fields separated by the comma `,` (U+002C)
character. Horizontal whitespace is not treated specially; that is,
it is considered part of a field's value. An empty line is considered
to have one field which is the empty string.
A field value that contains a comma or a quote quotation mark `"`
(U+0022) must be surrounded by quotation marks. The surrounding
quotation marks are not considered part of the field value. Any
quotation marks that are part of a field value must be repeated in
addition to being surrounded by quotation marks.
It is a syntax error if a quotation mark appears within an unquoted field;
if a quoted field isn't immediately followed by a comma or line
separator; or if a quoted field is left unclosed at the end of the line.
For example, a record with the following four fields:
1. abcd
2. ef,gh
3. ij"kl
4. mnop
would be encoded as follows:
abcd,"ef,gh","ij""kl",mnop
**CSV FILE DATA**
The first line of output must be the following:
#jdepr1
This is strictly a comment line, but it serves as a file
identifier. The "1" indicates version 1 of this file.
Zero or more comment lines follow, containing text that is specified
by the `-Xcsv-comment` options.
Subsequent non-comment lines must have the following five fields:
kind,typeName,descOrName,since,forRemoval
Fields are defined as follows:
* _kind_ - one of CONSTRUCTOR, FIELD, METHOD, ENUM\_CONSTANT,
CLASS, INTERFACE, ENUM, or ANNOTATION\_TYPE. These correspond to
enumeration constants from the `javax.lang.model.element.ElementKind`
enum.
* _typeName_ - the fully qualified name of the type (if *kind* is
CLASS, INTERFACE, ENUM, or ANNOTATION\_TYPE) or of the enclosing
type (if _kind_ is CONSTRUCTOR, FIELD, METHOD, or
ENUM\_CONSTANT). This value is a _binary name_ [JLS 13.1][jls131]
using a slash character `/` (U+002F) to separate package and
top-level name components, and a dollar sign `$` (U+0024) to
separate nested name components. For example, the `Thread.State`
enum that appears in Java SE would have the following typeName:
java/lang/Thread$State
* _descOrName_ - if _kind_ is METHOD or CONSTRUCTOR, this is the method's
or constructor's descriptor [JVMS 4.3.3][jvms433]; if _kind_ is FIELD or
ENUM\_CONSTANT, this is its name; otherwise this field is empty.
A method's descriptor includes its name, parameter types, and return
type. For example, the method
public void String.getBytes(int srcBegin,
int srcEnd,
byte[] dst,
int dstBegin)
has the descriptor
getBytes(II[BI)V
* _since_ - the value of the `since` element of the `@Deprecated`
annotation, or empty if this element is not present.
* _forRemoval_ - the value of the `forRemoval` element of the
`@Deprecated` annotation, a boolean, either "true" or "false".
Note that the _since_ field can have arbitrary text (excluding
line separators) and is thus subject to quoting.
**EXAMPLE OUTPUT**
Given the following method declaration and annotation from the
`java.lang.Runtime` class,
@Deprecated(since="1.2",
forRemoval=true)
public static void runFinalizersOnExit(boolean value)
the following line will be emitted from **jdeprscan -Xprint-csv**:
METHOD,java/lang/Runtime,runFinalizersOnExit(Z)V,1.2,true
[RFC]: https://www.ietf.org/rfc/rfc4180.txt
[wiki]: https://en.wikipedia.org/wiki/Comma-separated_values
[jls131]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1
[jvms433]: http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3.3