Mercurial > jdk8-mips64-public > langtools / file revision
src/share/classes/com/sun/tools/javadoc/DocImpl.java@829dea15ff99
src/share/classes/com/sun/tools/javadoc/DocImpl.java
Thu, 18 Sep 2008 18:39:44 -0700
- author
- jjg
- date
- Thu, 18 Sep 2008 18:39:44 -0700
- changeset 115
- 829dea15ff99
- parent 1
- 9a66ca7c79fa
- child 197
- 1bf037016426
- permissions
- -rw-r--r--
6744408: Extra ouput is appearing in stderr
Reviewed-by: bpatel
1 /*
2 * Copyright 1997-2006 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.javadoc;
28 import com.sun.javadoc.*;
30 import java.io.InputStream;
31 import java.io.IOException;
32 import java.text.CollationKey;
33 import com.sun.tools.javac.util.Position;
35 /**
36 * abstract base class of all Doc classes. Doc item's are representations
37 * of java language constructs (class, package, method,...) which have
38 * comments and have been processed by this run of javadoc. All Doc items
39 * are unique, that is, they are == comparable.
40 *
41 * @since 1.2
42 * @author Robert Field
43 * @author Atul M Dambalkar
44 * @author Neal Gafter (rewrite)
45 */
46 abstract class DocImpl implements Doc, Comparable<Object> {
48 /**
49 * Doc environment
50 */
51 protected final DocEnv env; //### Rename this everywhere to 'docenv' ?
53 /**
54 * The complex comment object, lazily initialized.
55 */
56 private Comment comment;
58 /**
59 * The cached sort key, to take care of Natural Language Text sorting.
60 */
61 private CollationKey collationkey = null;
63 /**
64 * Raw documentation string.
65 */
66 protected String documentation; // Accessed in PackageDocImpl, RootDocImpl
68 /**
69 * Cached first sentence.
70 */
71 private Tag[] firstSentence;
73 /**
74 * Cached inline tags.
75 */
76 private Tag[] inlineTags;
78 /**
79 * Constructor.
80 */
81 DocImpl(DocEnv env, String documentation) {
82 this.documentation = documentation;
83 this.env = env;
84 }
86 /**
87 * So subclasses have the option to do lazy initialization of
88 * "documentation" string.
89 */
90 String documentation() {
91 if (documentation == null) documentation = "";
92 return documentation;
93 }
95 /**
96 * For lazy initialization of comment.
97 */
98 Comment comment() {
99 if (comment == null) {
100 comment = new Comment(this, documentation());
101 }
102 return comment;
103 }
105 /**
106 * Return the text of the comment for this doc item.
107 * TagImpls have been removed.
108 */
109 public String commentText() {
110 return comment().commentText();
111 }
113 /**
114 * Return all tags in this Doc item.
115 *
116 * @return an array of TagImpl containing all tags on this Doc item.
117 */
118 public Tag[] tags() {
119 return comment().tags();
120 }
122 /**
123 * Return tags of the specified kind in this Doc item.
124 *
125 * @param tagname name of the tag kind to search for.
126 * @return an array of TagImpl containing all tags whose 'kind()'
127 * matches 'tagname'.
128 */
129 public Tag[] tags(String tagname) {
130 return comment().tags(tagname);
131 }
133 /**
134 * Return the see also tags in this Doc item.
135 *
136 * @return an array of SeeTag containing all @see tags.
137 */
138 public SeeTag[] seeTags() {
139 return comment().seeTags();
140 }
142 public Tag[] inlineTags() {
143 if (inlineTags == null) {
144 inlineTags = Comment.getInlineTags(this, commentText());
145 }
146 return inlineTags;
147 }
149 public Tag[] firstSentenceTags() {
150 if (firstSentence == null) {
151 //Parse all sentences first to avoid duplicate warnings.
152 inlineTags();
153 try {
154 env.setSilent(true);
155 firstSentence = Comment.firstSentenceTags(this, commentText());
156 } finally {
157 env.setSilent(false);
158 }
159 }
160 return firstSentence;
161 }
163 /**
164 * Utility for subclasses which read HTML documentation files.
165 */
166 String readHTMLDocumentation(InputStream input, String filename) throws IOException {
167 int filesize = input.available();
168 byte[] filecontents = new byte[filesize];
169 input.read(filecontents, 0, filesize);
170 input.close();
171 String encoding = env.getEncoding();
172 String rawDoc = (encoding!=null)
173 ? new String(filecontents, encoding)
174 : new String(filecontents);
175 String upper = null;
176 int bodyIdx = rawDoc.indexOf("<body");
177 if (bodyIdx == -1) {
178 bodyIdx = rawDoc.indexOf("<BODY");
179 if (bodyIdx == -1) {
180 upper = rawDoc.toUpperCase();
181 bodyIdx = upper.indexOf("<BODY");
182 if (bodyIdx == -1) {
183 env.error(SourcePositionImpl.make(filename, Position.NOPOS, null),
184 "javadoc.Body_missing_from_html_file");
185 return "";
186 }
187 }
188 }
189 bodyIdx = rawDoc.indexOf('>', bodyIdx);
190 if (bodyIdx == -1) {
191 env.error(SourcePositionImpl.make(filename, Position.NOPOS, null),
192 "javadoc.Body_missing_from_html_file");
193 return "";
194 }
195 ++bodyIdx;
196 int endIdx = rawDoc.indexOf("</body", bodyIdx);
197 if (endIdx == -1) {
198 endIdx = rawDoc.indexOf("</BODY", bodyIdx);
199 if (endIdx == -1) {
200 if (upper == null) {
201 upper = rawDoc.toUpperCase();
202 }
203 endIdx = upper.indexOf("</BODY", bodyIdx);
204 if (endIdx == -1) {
205 env.error(SourcePositionImpl.make(filename, Position.NOPOS, null),
206 "javadoc.End_body_missing_from_html_file");
207 return "";
208 }
209 }
210 }
211 return rawDoc.substring(bodyIdx, endIdx);
212 }
214 /**
215 * Return the full unprocessed text of the comment. Tags
216 * are included as text. Used mainly for store and retrieve
217 * operations like internalization.
218 */
219 public String getRawCommentText() {
220 return documentation();
221 }
223 /**
224 * Set the full unprocessed text of the comment. Tags
225 * are included as text. Used mainly for store and retrieve
226 * operations like internalization.
227 */
228 public void setRawCommentText(String rawDocumentation) {
229 documentation = rawDocumentation;
230 comment = null;
231 }
233 /**
234 * return a key for sorting.
235 */
236 CollationKey key() {
237 if (collationkey == null) {
238 collationkey = generateKey();
239 }
240 return collationkey;
241 }
243 /**
244 * Generate a key for sorting.
245 * <p>
246 * Default is name().
247 */
248 CollationKey generateKey() {
249 String k = name();
250 // System.out.println("COLLATION KEY FOR " + this + " is \"" + k + "\"");
251 return env.doclocale.collator.getCollationKey(k);
252 }
254 /**
255 * Returns a string representation of this Doc item.
256 */
257 public String toString() {
258 return qualifiedName();
259 }
261 /**
262 * Returns the name of this Doc item.
263 *
264 * @return the name
265 */
266 public abstract String name();
268 /**
269 * Returns the qualified name of this Doc item.
270 *
271 * @return the name
272 */
273 public abstract String qualifiedName();
275 /**
276 * Compares this Object with the specified Object for order. Returns a
277 * negative integer, zero, or a positive integer as this Object is less
278 * than, equal to, or greater than the given Object.
279 * <p>
280 * Included so that Doc item are java.lang.Comparable.
281 *
282 * @param o the <code>Object</code> to be compared.
283 * @return a negative integer, zero, or a positive integer as this Object
284 * is less than, equal to, or greater than the given Object.
285 * @exception ClassCastException the specified Object's type prevents it
286 * from being compared to this Object.
287 */
288 public int compareTo(Object obj) {
289 // System.out.println("COMPARE \"" + this + "\" to \"" + obj + "\" = " + key().compareTo(((DocImpl)obj).key()));
290 return key().compareTo(((DocImpl)obj).key());
291 }
293 /**
294 * Is this Doc item a field? False until overridden.
295 *
296 * @return true if it represents a field
297 */
298 public boolean isField() {
299 return false;
300 }
302 /**
303 * Is this Doc item an enum constant? False until overridden.
304 *
305 * @return true if it represents an enum constant
306 */
307 public boolean isEnumConstant() {
308 return false;
309 }
311 /**
312 * Is this Doc item a constructor? False until overridden.
313 *
314 * @return true if it represents a constructor
315 */
316 public boolean isConstructor() {
317 return false;
318 }
320 /**
321 * Is this Doc item a method (but not a constructor or annotation
322 * type element)?
323 * False until overridden.
324 *
325 * @return true if it represents a method
326 */
327 public boolean isMethod() {
328 return false;
329 }
331 /**
332 * Is this Doc item an annotation type element?
333 * False until overridden.
334 *
335 * @return true if it represents an annotation type element
336 */
337 public boolean isAnnotationTypeElement() {
338 return false;
339 }
341 /**
342 * Is this Doc item a interface (but not an annotation type)?
343 * False until overridden.
344 *
345 * @return true if it represents a interface
346 */
347 public boolean isInterface() {
348 return false;
349 }
351 /**
352 * Is this Doc item a exception class? False until overridden.
353 *
354 * @return true if it represents a exception
355 */
356 public boolean isException() {
357 return false;
358 }
360 /**
361 * Is this Doc item a error class? False until overridden.
362 *
363 * @return true if it represents a error
364 */
365 public boolean isError() {
366 return false;
367 }
369 /**
370 * Is this Doc item an enum type? False until overridden.
371 *
372 * @return true if it represents an enum type
373 */
374 public boolean isEnum() {
375 return false;
376 }
378 /**
379 * Is this Doc item an annotation type? False until overridden.
380 *
381 * @return true if it represents an annotation type
382 */
383 public boolean isAnnotationType() {
384 return false;
385 }
387 /**
388 * Is this Doc item an ordinary class (i.e. not an interface,
389 * annotation type, enumeration, exception, or error)?
390 * False until overridden.
391 *
392 * @return true if it represents an ordinary class
393 */
394 public boolean isOrdinaryClass() {
395 return false;
396 }
398 /**
399 * Is this Doc item a class
400 * (and not an interface or annotation type)?
401 * This includes ordinary classes, enums, errors and exceptions.
402 * False until overridden.
403 *
404 * @return true if it represents a class
405 */
406 public boolean isClass() {
407 return false;
408 }
410 /**
411 * return true if this Doc is include in the active set.
412 */
413 public abstract boolean isIncluded();
415 /**
416 * Return the source position of the entity, or null if
417 * no position is available.
418 */
419 public SourcePosition position() { return null; }
420 }
