Thu, 02 Oct 2008 19:58:40 -0700
6754988: Update copyright year
Summary: Update for files that have been modified starting July 2008
Reviewed-by: ohair, tbell
1 /*
2 * Copyright 2001-2003 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
26 package com.sun.tools.doclets.internal.toolkit.taglets;
28 import com.sun.javadoc.*;
29 import com.sun.tools.doclets.internal.toolkit.Configuration;
30 import com.sun.tools.doclets.internal.toolkit.util.*;
31 import java.util.*;
33 /**
34 * An inline Taglet representing the value tag. This tag should only be used with
35 * constant fields that have a value. It is used to access the value of constant
36 * fields. This inline tag has an optional field name parameter. If the name is
37 * specified, the constant value is retrieved from the specified field. A link
38 * is also created to the specified field. If a name is not specified, the value
39 * is retrieved for the field that the inline tag appears on. The name is specifed
40 * in the following format: [fully qualified class name]#[constant field name].
41 *
42 * This code is not part of an API.
43 * It is implementation that is subject to change.
44 * Do not use it as an API
45 *
46 * @author Jamie Ho
47 * @since 1.4
48 */
50 public class ValueTaglet extends BaseInlineTaglet {
52 /**
53 * Construct a new ValueTaglet.
54 */
55 public ValueTaglet() {
56 name = "value";
57 }
59 /**
60 * Will return false because this inline tag may
61 * only appear in Fields.
62 * @return false since this is not a method.
63 */
64 public boolean inMethod() {
65 return true;
66 }
68 /**
69 * Will return false because this inline tag may
70 * only appear in Fields.
71 * @return false since this is not a method.
72 */
73 public boolean inConstructor() {
74 return true;
75 }
77 /**
78 * Will return false because this inline tag may
79 * only appear in Fields.
80 * @return false since this is not a method.
81 */
82 public boolean inOverview() {
83 return true;
84 }
86 /**
87 * Will return false because this inline tag may
88 * only appear in Fields.
89 * @return false since this is not a method.
90 */
91 public boolean inPackage() {
92 return true;
93 }
95 /**
96 * Will return false because this inline tag may
97 * only appear in Fields.
98 * @return false since this is not a method.
99 */
100 public boolean inType() {
101 return true;
102 }
104 /**
105 * Given the name of the field, return the corresponding FieldDoc.
106 *
107 * @param config the current configuration of the doclet.
108 * @param tag the value tag.
109 * @param name the name of the field to search for. The name should be in
110 * <qualified class name>#<field name> format. If the class name is omitted,
111 * it is assumed that the field is in the current class.
112 *
113 * @return the corresponding FieldDoc. If the name is null or empty string,
114 * return field that the value tag was used in.
115 *
116 * @throws DocletAbortException if the value tag does not specify a name to
117 * a value field and it is not used within the comments of a valid field.
118 */
119 private FieldDoc getFieldDoc(Configuration config, Tag tag, String name) {
120 if (name == null || name.length() == 0) {
121 //Base case: no label.
122 if (tag.holder() instanceof FieldDoc) {
123 return (FieldDoc) tag.holder();
124 } else {
125 //This should never ever happen.
126 throw new DocletAbortException();
127 }
128 }
129 StringTokenizer st = new StringTokenizer(name, "#");
130 String memberName = null;
131 ClassDoc cd = null;
132 if (st.countTokens() == 1) {
133 //Case 2: @value in same class.
134 Doc holder = tag.holder();
135 if (holder instanceof MemberDoc) {
136 cd = ((MemberDoc) holder).containingClass();
137 } else if (holder instanceof ClassDoc) {
138 cd = (ClassDoc) holder;
139 }
140 memberName = st.nextToken();
141 } else {
142 //Case 3: @value in different class.
143 cd = config.root.classNamed(st.nextToken());
144 memberName = st.nextToken();
145 }
146 if (cd == null) {
147 return null;
148 }
149 FieldDoc[] fields = cd.fields();
150 for (int i = 0; i < fields.length; i++) {
151 if (fields[i].name().equals(memberName)) {
152 return fields[i];
153 }
154 }
155 return null;
156 }
158 /**
159 * {@inheritDoc}
160 */
161 public TagletOutput getTagletOutput(Tag tag, TagletWriter writer) {
162 FieldDoc field = getFieldDoc(
163 writer.configuration(), tag, tag.text());
164 if (field == null) {
165 //Reference is unknown.
166 writer.getMsgRetriever().warning(tag.holder().position(),
167 "doclet.value_tag_invalid_reference", tag.text());
168 } else if (field.constantValue() != null) {
169 return writer.valueTagOutput(field,
170 Util.escapeHtmlChars(field.constantValueExpression()),
171 ! field.equals(tag.holder()));
172 } else {
173 //Referenced field is not a constant.
174 writer.getMsgRetriever().warning(tag.holder().position(),
175 "doclet.value_tag_invalid_constant", field.name());
176 }
177 return writer.getOutputInstance();
178 }
179 }