1 <!-- 2 3 Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. 4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 6 This code is free software; you can redistribute it and/or modify it 7 under the terms of the GNU General Public License version 2 only, as 8 published by the Free Software Foundation. Oracle designates this 9 particular file as subject to the "Classpath" exception as provided 10 by Oracle in the LICENSE file that accompanied this code. 11 12 This code is distributed in the hope that it will be useful, but WITHOUT 13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 version 2 for more details (a copy is included in the LICENSE file that 16 accompanied this code). 17 18 You should have received a copy of the GNU General Public License version 19 2 along with this work; if not, write to the Free Software Foundation, 20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 or visit www.oracle.com if you need additional information or have any 24 questions. 25 26 --> 27 28 29 JDeprScan Internals 30 ----- 31 32 **EXPERIMENTAL OPTIONS** 33 34 --Xload-class CLASSNAME 35 36 Loads deprecation data from the class named CLASSNAME instead of from 37 the JDK image. 38 39 --Xload-csv CVSFILE 40 41 Loads deprecation data from file CSVFILE. 42 43 --Xload-dir DIR 44 45 Loads deprecation data from the class hierarchy rooted 46 at the directory named DIR. 47 48 --Xload-jar JARFILE 49 50 Loads deprecation data from the classes contained in the 51 jar file named JARFILE. 52 53 --Xload-jdk9 JAVA_HOME 54 55 Loads deprecation data from a modular JDK whose home 56 directory is at JAVA_HOME. This essentially adds the given 57 path to the system-modules location. 58 59 --Xload-old-jdk JAVA_HOME 60 61 Loads deprecation data from an old (non-modular) JDK whose 62 home directory is at JAVA_HOME. This essentially scans the 63 rt.jar file from that JDK. 64 65 --Xload-self 66 67 Loads deprecation data from the running JDK image by 68 traversing the entire jrt: filesystem. This differs from 69 -release 9, which traverses modules, packages, and classes by 70 starting from a set of root modules and using javax.lang.model 71 mechanisms (as opposed to filesystem mechanisms) for 72 traversing contained elements recursively. 73 74 --Xcompiler-arg ARG 75 76 Adds ARG to the list of arguments passed to the compiler. 77 78 --Xcsv-comment COMMENT 79 80 Adds a comment line containing COMMENT to the top of the CSV 81 that is emitted. Valid only when --Xprint-csv is 82 specified. More than one --Xcsv-comment option is permitted, 83 which will cause a corresponding number of comment lines to be 84 emitted to the CSV file. 85 86 --Xprint-csv 87 88 Prints out the loaded deprecation information in CSV format 89 to standard output. In this mode, no scanning is done, so 90 there must not be any additional directory, jar, or classname 91 arguments. 92 93 **CSV FILE SYNTAX** 94 95 The `-Xprint-csv` option causes **jdeprscan** to emit the loaded 96 deprecation data in CSV (comma-separated value) format. The general 97 syntax of CSV is documented in [RFC 4180][RFC] with supplemental 98 information in a [Wikipedia article][wiki]. 99 100 The file is encoded in UTF-8. 101 102 The file consists of a series of lines. Any of the standard line 103 separators CR (U+000D), LF (U+000A), or a CR immediately followed by 104 LF, are supported. Newlines are only supported between records and 105 are not supported within field values. 106 107 Comment lines start with a `#` (U+0023) character in the first 108 column. The entire line is ignored up until the next line separator 109 sequence. 110 111 Each line is divided into fields separated by the comma `,` (U+002C) 112 character. Horizontal whitespace is not treated specially; that is, 113 it is considered part of a field's value. An empty line is considered 114 to have one field which is the empty string. 115 116 A field value that contains a comma or a quote quotation mark `"` 117 (U+0022) must be surrounded by quotation marks. The surrounding 118 quotation marks are not considered part of the field value. Any 119 quotation marks that are part of a field value must be repeated in 120 addition to being surrounded by quotation marks. 121 122 It is a syntax error if a quotation mark appears within an unquoted field; 123 if a quoted field isn't immediately followed by a comma or line 124 separator; or if a quoted field is left unclosed at the end of the line. 125 126 For example, a record with the following four fields: 127 128 1. abcd 129 2. ef,gh 130 3. ij"kl 131 4. mnop 132 133 would be encoded as follows: 134 135 abcd,"ef,gh","ij""kl",mnop 136 137 **CSV FILE DATA** 138 139 The first line of output must be the following: 140 141 #jdepr1 142 143 This is strictly a comment line, but it serves as a file 144 identifier. The "1" indicates version 1 of this file. 145 146 Zero or more comment lines follow, containing text that is specified 147 by the `-Xcsv-comment` options. 148 149 Subsequent non-comment lines must have the following five fields: 150 151 kind,typeName,descOrName,since,forRemoval 152 153 Fields are defined as follows: 154 155 * _kind_ - one of CONSTRUCTOR, FIELD, METHOD, ENUM\_CONSTANT, 156 CLASS, INTERFACE, ENUM, or ANNOTATION\_TYPE. These correspond to 157 enumeration constants from the `javax.lang.model.element.ElementKind` 158 enum. 159 160 * _typeName_ - the fully qualified name of the type (if *kind* is 161 CLASS, INTERFACE, ENUM, or ANNOTATION\_TYPE) or of the enclosing 162 type (if _kind_ is CONSTRUCTOR, FIELD, METHOD, or 163 ENUM\_CONSTANT). This value is a _binary name_ [JLS 13.1][jls131] 164 using a slash character `/` (U+002F) to separate package and 165 top-level name components, and a dollar sign `$` (U+0024) to 166 separate nested name components. For example, the `Thread.State` 167 enum that appears in Java SE would have the following typeName: 168 169 java/lang/Thread$State 170 171 * _descOrName_ - if _kind_ is METHOD or CONSTRUCTOR, this is the method's 172 or constructor's descriptor [JVMS 4.3.3][jvms433]; if _kind_ is FIELD or 173 ENUM\_CONSTANT, this is its name; otherwise this field is empty. 174 A method's descriptor includes its name, parameter types, and return 175 type. For example, the method 176 177 public void String.getBytes(int srcBegin, 178 int srcEnd, 179 byte[] dst, 180 int dstBegin) 181 182 has the descriptor 183 184 getBytes(II[BI)V 185 186 * _since_ - the value of the `since` element of the `@Deprecated` 187 annotation, or empty if this element is not present. 188 189 * _forRemoval_ - the value of the `forRemoval` element of the 190 `@Deprecated` annotation, a boolean, either "true" or "false". 191 192 Note that the _since_ field can have arbitrary text (excluding 193 line separators) and is thus subject to quoting. 194 195 **EXAMPLE OUTPUT** 196 197 Given the following method declaration and annotation from the 198 `java.lang.Runtime` class, 199 200 @Deprecated(since="1.2", 201 forRemoval=true) 202 public static void runFinalizersOnExit(boolean value) 203 204 the following line will be emitted from **jdeprscan -Xprint-csv**: 205 206 METHOD,java/lang/Runtime,runFinalizersOnExit(Z)V,1.2,true 207 208 209 [RFC]: https://www.ietf.org/rfc/rfc4180.txt 210 211 [wiki]: https://en.wikipedia.org/wiki/Comma-separated_values 212 213 [jls131]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1 214 215 [jvms433]: http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3.3