internals.md

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 with supplemental information in a Wikipedia article.

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 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; 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.Character class,

        @Deprecated(since="1.1")
        public static boolean isJavaLetter(char ch)

the following line will be emitted from jdeprscan -Xprint-csv:

        METHOD,java/lang/Character,isJavaLetter(C)Z,1.1,false