1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/javadoc/SerialFieldTagImpl.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,259 @@
1.4 +/*
1.5 + * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.javadoc;
1.30 +
1.31 +import com.sun.javadoc.*;
1.32 +
1.33 +/**
1.34 + * Documents a Serializable field defined by an ObjectStreamField.
1.35 + * <pre>
1.36 + * The class parses and stores the three serialField tag parameters:
1.37 + *
1.38 + * - field name
1.39 + * - field type name
1.40 + * (fully-qualified or visible from the current import context)
1.41 + * - description of the valid values for the field
1.42 +
1.43 + * </pre>
1.44 + * This tag is only allowed in the javadoc for the special member
1.45 + * serialPersistentFields.
1.46 + *
1.47 + * @author Joe Fialli
1.48 + * @author Neal Gafter
1.49 + *
1.50 + * @see java.io.ObjectStreamField
1.51 + */
1.52 +class SerialFieldTagImpl
1.53 + extends TagImpl
1.54 + implements SerialFieldTag, Comparable<Object>
1.55 +{
1.56 + //### These could be final, except that the constructor
1.57 + //### does not set them directly.
1.58 +
1.59 + private String fieldName; // Required Argument 1 of serialField
1.60 + private String fieldType; // Required Argument 2 of serialField
1.61 + private String description; // Optional Remaining Arguments of serialField
1.62 +
1.63 + private ClassDoc containingClass; // Class containing serialPersistentField member
1.64 + private ClassDoc fieldTypeDoc; // ClassDocImpl of fieldType
1.65 + private FieldDocImpl matchingField; // FieldDocImpl with same name as fieldName
1.66 +
1.67 + /* Constructor. */
1.68 + SerialFieldTagImpl(DocImpl holder, String name, String text) {
1.69 + super(holder, name, text);
1.70 + parseSerialFieldString();
1.71 + if (holder instanceof MemberDoc) {
1.72 + containingClass = ((MemberDocImpl)holder).containingClass();
1.73 + }
1.74 + }
1.75 +
1.76 + /*
1.77 + * The serialField tag is composed of three entities.
1.78 + *
1.79 + * serialField serializableFieldName serisliableFieldType
1.80 + * description of field.
1.81 + *
1.82 + * The fieldName and fieldType must be legal Java Identifiers.
1.83 + */
1.84 + private void parseSerialFieldString() {
1.85 + int len = text.length();
1.86 +
1.87 + // if no white space found
1.88 + /* Skip white space. */
1.89 + int inx = 0;
1.90 + int cp;
1.91 + for (; inx < len; inx += Character.charCount(cp)) {
1.92 + cp = text.codePointAt(inx);
1.93 + if (!Character.isWhitespace(cp)) {
1.94 + break;
1.95 + }
1.96 + }
1.97 +
1.98 + /* find first word. */
1.99 + int first = inx;
1.100 + int last = inx;
1.101 + cp = text.codePointAt(inx);
1.102 + if (! Character.isJavaIdentifierStart(cp)) {
1.103 + docenv().warning(holder,
1.104 + "tag.serialField.illegal_character",
1.105 + new String(Character.toChars(cp)), text);
1.106 + return;
1.107 + }
1.108 +
1.109 + for (inx += Character.charCount(cp); inx < len; inx += Character.charCount(cp)) {
1.110 + cp = text.codePointAt(inx);
1.111 + if (!Character.isJavaIdentifierPart(cp)) {
1.112 + break;
1.113 + }
1.114 + }
1.115 +
1.116 + if (inx < len && ! Character.isWhitespace(cp = text.codePointAt(inx))) {
1.117 + docenv().warning(holder,
1.118 + "tag.serialField.illegal_character",
1.119 + new String(Character.toChars(cp)), text);
1.120 + return;
1.121 + }
1.122 +
1.123 + last = inx;
1.124 + fieldName = text.substring(first, last);
1.125 +
1.126 + /* Skip white space. */
1.127 + for (; inx < len; inx += Character.charCount(cp)) {
1.128 + cp = text.codePointAt(inx);
1.129 + if (!Character.isWhitespace(cp)) {
1.130 + break;
1.131 + }
1.132 + }
1.133 +
1.134 + /* find second word. */
1.135 + first = inx;
1.136 + last = inx;
1.137 +
1.138 + for (; inx < len; inx += Character.charCount(cp)) {
1.139 + cp = text.codePointAt(inx);
1.140 + if (Character.isWhitespace(cp)) {
1.141 + break;
1.142 + }
1.143 + }
1.144 + if (inx < len && ! Character.isWhitespace(cp = text.codePointAt(inx))) {
1.145 + docenv().warning(holder,
1.146 + "tag.serialField.illegal_character",
1.147 + new String(Character.toChars(cp)), text);
1.148 + return;
1.149 + }
1.150 + last = inx;
1.151 + fieldType = text.substring(first, last);
1.152 +
1.153 + /* Skip leading white space. Rest of string is description for serialField.*/
1.154 + for (; inx < len; inx += Character.charCount(cp)) {
1.155 + cp = text.codePointAt(inx);
1.156 + if (!Character.isWhitespace(cp)) {
1.157 + break;
1.158 + }
1.159 + }
1.160 + description = text.substring(inx);
1.161 + }
1.162 +
1.163 + /**
1.164 + * return a key for sorting.
1.165 + */
1.166 + String key() {
1.167 + return fieldName;
1.168 + }
1.169 +
1.170 + /*
1.171 + * Optional. Link this serialField tag to its corrsponding
1.172 + * field in the class. Note: there is no requirement that
1.173 + * there be a field in the class that matches serialField tag.
1.174 + */
1.175 + void mapToFieldDocImpl(FieldDocImpl fd) {
1.176 + matchingField = fd;
1.177 + }
1.178 +
1.179 + /**
1.180 + * Return the serialziable field name.
1.181 + */
1.182 + public String fieldName() {
1.183 + return fieldName;
1.184 + }
1.185 +
1.186 + /**
1.187 + * Return the field type string.
1.188 + */
1.189 + public String fieldType() {
1.190 + return fieldType;
1.191 + }
1.192 +
1.193 + /**
1.194 + * Return the ClassDocImpl for field type.
1.195 + *
1.196 + * @returns null if no ClassDocImpl for field type is visible from
1.197 + * containingClass context.
1.198 + */
1.199 + public ClassDoc fieldTypeDoc() {
1.200 + if (fieldTypeDoc == null && containingClass != null) {
1.201 + fieldTypeDoc = containingClass.findClass(fieldType);
1.202 + }
1.203 + return fieldTypeDoc;
1.204 + }
1.205 +
1.206 + /**
1.207 + * Return the corresponding FieldDocImpl for this SerialFieldTagImpl.
1.208 + *
1.209 + * @returns null if no matching FieldDocImpl.
1.210 + */
1.211 + FieldDocImpl getMatchingField() {
1.212 + return matchingField;
1.213 + }
1.214 +
1.215 + /**
1.216 + * Return the field comment. If there is no serialField comment, return
1.217 + * javadoc comment of corresponding FieldDocImpl.
1.218 + */
1.219 + public String description() {
1.220 + if (description.length() == 0 && matchingField != null) {
1.221 +
1.222 + //check for javadoc comment of corresponding field.
1.223 + Comment comment = matchingField.comment();
1.224 + if (comment != null) {
1.225 + return comment.commentText();
1.226 + }
1.227 + }
1.228 + return description;
1.229 + }
1.230 +
1.231 + /**
1.232 + * Return the kind of this tag.
1.233 + */
1.234 + public String kind() {
1.235 + return "@serialField";
1.236 + }
1.237 +
1.238 + /**
1.239 + * Convert this object to a string.
1.240 + */
1.241 + public String toString() {
1.242 + return name + ":" + text;
1.243 + }
1.244 +
1.245 + /**
1.246 + * Compares this Object with the specified Object for order. Returns a
1.247 + * negative integer, zero, or a positive integer as this Object is less
1.248 + * than, equal to, or greater than the given Object.
1.249 + * <p>
1.250 + * Included to make SerialFieldTagImpl items java.lang.Comparable.
1.251 + *
1.252 + * @param obj the <code>Object</code> to be compared.
1.253 + * @return a negative integer, zero, or a positive integer as this Object
1.254 + * is less than, equal to, or greater than the given Object.
1.255 + * @exception ClassCastException the specified Object's type prevents it
1.256 + * from being compared to this Object.
1.257 + * @since 1.2
1.258 + */
1.259 + public int compareTo(Object obj) {
1.260 + return key().compareTo(((SerialFieldTagImpl)obj).key());
1.261 + }
1.262 +}
