author | mchung |
Fri, 23 Feb 2018 12:10:56 -0800 | |
changeset 48942 | a6c4b85163c1 |
parent 47216 | 71c04702a3d5 |
permissions | -rw-r--r-- |
40596 | 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 |
|
48942
a6c4b85163c1
8198249: Remove deprecated Runtime::runFinalizersOnExit and System::runFinalizersOnExit
mchung
parents:
47216
diff
changeset
|
198 |
`java.lang.Character` class, |
40596 | 199 |
|
48942
a6c4b85163c1
8198249: Remove deprecated Runtime::runFinalizersOnExit and System::runFinalizersOnExit
mchung
parents:
47216
diff
changeset
|
200 |
@Deprecated(since="1.1") |
a6c4b85163c1
8198249: Remove deprecated Runtime::runFinalizersOnExit and System::runFinalizersOnExit
mchung
parents:
47216
diff
changeset
|
201 |
public static boolean isJavaLetter(char ch) |
40596 | 202 |
|
203 |
the following line will be emitted from **jdeprscan -Xprint-csv**: |
|
204 |
||
48942
a6c4b85163c1
8198249: Remove deprecated Runtime::runFinalizersOnExit and System::runFinalizersOnExit
mchung
parents:
47216
diff
changeset
|
205 |
METHOD,java/lang/Character,isJavaLetter(C)Z,1.1,false |
40596 | 206 |
|
207 |
||
208 |
[RFC]: https://www.ietf.org/rfc/rfc4180.txt |
|
209 |
||
210 |
[wiki]: https://en.wikipedia.org/wiki/Comma-separated_values |
|
211 |
||
212 |
[jls131]: http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.1 |
|
213 |
||
214 |
[jvms433]: http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3.3 |