Mercurial > jdk8-mips64-public > langtools / file revision
src/share/classes/com/sun/tools/javadoc/SerialFieldTagImpl.java@959103a6100f
src/share/classes/com/sun/tools/javadoc/SerialFieldTagImpl.java
Wed, 27 Apr 2016 01:34:52 +0800
- author
- aoqi
- date
- Wed, 27 Apr 2016 01:34:52 +0800
- changeset 0
- 959103a6100f
- child 2525
- 2eb010b6cb22
- permissions
- -rw-r--r--
Initial load
http://hg.openjdk.java.net/jdk8u/jdk8u/langtools/
changeset: 2573:53ca196be1ae
tag: jdk8u25-b17
1 /*
2 * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package com.sun.tools.javadoc;
28 import com.sun.javadoc.*;
30 /**
31 * Documents a Serializable field defined by an ObjectStreamField.
32 * <pre>
33 * The class parses and stores the three serialField tag parameters:
34 *
35 * - field name
36 * - field type name
37 * (fully-qualified or visible from the current import context)
38 * - description of the valid values for the field
40 * </pre>
41 * This tag is only allowed in the javadoc for the special member
42 * serialPersistentFields.
43 *
44 * <p><b>This is NOT part of any supported API.
45 * If you write code that depends on this, you do so at your own risk.
46 * This code and its internal interfaces are subject to change or
47 * deletion without notice.</b>
48 *
49 * @author Joe Fialli
50 * @author Neal Gafter
51 *
52 * @see java.io.ObjectStreamField
53 */
54 class SerialFieldTagImpl
55 extends TagImpl
56 implements SerialFieldTag, Comparable<Object>
57 {
58 //### These could be final, except that the constructor
59 //### does not set them directly.
61 private String fieldName; // Required Argument 1 of serialField
62 private String fieldType; // Required Argument 2 of serialField
63 private String description; // Optional Remaining Arguments of serialField
65 private ClassDoc containingClass; // Class containing serialPersistentField member
66 private ClassDoc fieldTypeDoc; // ClassDocImpl of fieldType
67 private FieldDocImpl matchingField; // FieldDocImpl with same name as fieldName
69 /* Constructor. */
70 SerialFieldTagImpl(DocImpl holder, String name, String text) {
71 super(holder, name, text);
72 parseSerialFieldString();
73 if (holder instanceof MemberDoc) {
74 containingClass = ((MemberDocImpl)holder).containingClass();
75 }
76 }
78 /*
79 * The serialField tag is composed of three entities.
80 *
81 * serialField serializableFieldName serisliableFieldType
82 * description of field.
83 *
84 * The fieldName and fieldType must be legal Java Identifiers.
85 */
86 private void parseSerialFieldString() {
87 int len = text.length();
88 if (len == 0) {
89 return;
90 }
92 // if no white space found
93 /* Skip white space. */
94 int inx = 0;
95 int cp;
96 for (; inx < len; inx += Character.charCount(cp)) {
97 cp = text.codePointAt(inx);
98 if (!Character.isWhitespace(cp)) {
99 break;
100 }
101 }
103 /* find first word. */
104 int first = inx;
105 int last = inx;
106 cp = text.codePointAt(inx);
107 if (! Character.isJavaIdentifierStart(cp)) {
108 docenv().warning(holder,
109 "tag.serialField.illegal_character",
110 new String(Character.toChars(cp)), text);
111 return;
112 }
114 for (inx += Character.charCount(cp); inx < len; inx += Character.charCount(cp)) {
115 cp = text.codePointAt(inx);
116 if (!Character.isJavaIdentifierPart(cp)) {
117 break;
118 }
119 }
121 if (inx < len && ! Character.isWhitespace(cp = text.codePointAt(inx))) {
122 docenv().warning(holder,
123 "tag.serialField.illegal_character",
124 new String(Character.toChars(cp)), text);
125 return;
126 }
128 last = inx;
129 fieldName = text.substring(first, last);
131 /* Skip white space. */
132 for (; inx < len; inx += Character.charCount(cp)) {
133 cp = text.codePointAt(inx);
134 if (!Character.isWhitespace(cp)) {
135 break;
136 }
137 }
139 /* find second word. */
140 first = inx;
141 last = inx;
143 for (; inx < len; inx += Character.charCount(cp)) {
144 cp = text.codePointAt(inx);
145 if (Character.isWhitespace(cp)) {
146 break;
147 }
148 }
149 if (inx < len && ! Character.isWhitespace(cp = text.codePointAt(inx))) {
150 docenv().warning(holder,
151 "tag.serialField.illegal_character",
152 new String(Character.toChars(cp)), text);
153 return;
154 }
155 last = inx;
156 fieldType = text.substring(first, last);
158 /* Skip leading white space. Rest of string is description for serialField.*/
159 for (; inx < len; inx += Character.charCount(cp)) {
160 cp = text.codePointAt(inx);
161 if (!Character.isWhitespace(cp)) {
162 break;
163 }
164 }
165 description = text.substring(inx);
166 }
168 /**
169 * return a key for sorting.
170 */
171 String key() {
172 return fieldName;
173 }
175 /*
176 * Optional. Link this serialField tag to its corrsponding
177 * field in the class. Note: there is no requirement that
178 * there be a field in the class that matches serialField tag.
179 */
180 void mapToFieldDocImpl(FieldDocImpl fd) {
181 matchingField = fd;
182 }
184 /**
185 * Return the serialziable field name.
186 */
187 public String fieldName() {
188 return fieldName;
189 }
191 /**
192 * Return the field type string.
193 */
194 public String fieldType() {
195 return fieldType;
196 }
198 /**
199 * Return the ClassDocImpl for field type.
200 *
201 * @returns null if no ClassDocImpl for field type is visible from
202 * containingClass context.
203 */
204 public ClassDoc fieldTypeDoc() {
205 if (fieldTypeDoc == null && containingClass != null) {
206 fieldTypeDoc = containingClass.findClass(fieldType);
207 }
208 return fieldTypeDoc;
209 }
211 /**
212 * Return the corresponding FieldDocImpl for this SerialFieldTagImpl.
213 *
214 * @returns null if no matching FieldDocImpl.
215 */
216 FieldDocImpl getMatchingField() {
217 return matchingField;
218 }
220 /**
221 * Return the field comment. If there is no serialField comment, return
222 * javadoc comment of corresponding FieldDocImpl.
223 */
224 public String description() {
225 if (description.length() == 0 && matchingField != null) {
227 //check for javadoc comment of corresponding field.
228 Comment comment = matchingField.comment();
229 if (comment != null) {
230 return comment.commentText();
231 }
232 }
233 return description;
234 }
236 /**
237 * Return the kind of this tag.
238 */
239 public String kind() {
240 return "@serialField";
241 }
243 /**
244 * Convert this object to a string.
245 */
246 public String toString() {
247 return name + ":" + text;
248 }
250 /**
251 * Compares this Object with the specified Object for order. Returns a
252 * negative integer, zero, or a positive integer as this Object is less
253 * than, equal to, or greater than the given Object.
254 * <p>
255 * Included to make SerialFieldTagImpl items java.lang.Comparable.
256 *
257 * @param obj the <code>Object</code> to be compared.
258 * @return a negative integer, zero, or a positive integer as this Object
259 * is less than, equal to, or greater than the given Object.
260 * @exception ClassCastException the specified Object's type prevents it
261 * from being compared to this Object.
262 * @since 1.2
263 */
264 public int compareTo(Object obj) {
265 return key().compareTo(((SerialFieldTagImpl)obj).key());
266 }
267 }
