Tue, 14 May 2013 10:14:52 -0700
8011650: reduce use of RawHtml nodes in doclet
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2003, 2013, 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 */
27 package com.sun.tools.doclets.formats.html;
29 import com.sun.javadoc.*;
30 import com.sun.tools.doclets.formats.html.markup.ContentBuilder;
31 import com.sun.tools.doclets.formats.html.markup.StringContent;
32 import com.sun.tools.doclets.internal.toolkit.Content;
33 import com.sun.tools.doclets.internal.toolkit.util.*;
34 import com.sun.tools.doclets.internal.toolkit.util.links.*;
36 /**
37 * <p><b>This is NOT part of any supported API.
38 * If you write code that depends on this, you do so at your own risk.
39 * This code and its internal interfaces are subject to change or
40 * deletion without notice.</b>
41 */
42 public class LinkInfoImpl extends LinkInfo {
44 public enum Kind {
45 DEFAULT,
47 /**
48 * Indicate that the link appears in a class list.
49 */
50 ALL_CLASSES_FRAME,
52 /**
53 * Indicate that the link appears in a class documentation.
54 */
55 CLASS,
57 /**
58 * Indicate that the link appears in member documentation.
59 */
60 MEMBER,
62 /**
63 * Indicate that the link appears in class use documentation.
64 */
65 CLASS_USE,
67 /**
68 * Indicate that the link appears in index documentation.
69 */
70 INDEX,
72 /**
73 * Indicate that the link appears in constant value summary.
74 */
75 CONSTANT_SUMMARY,
77 /**
78 * Indicate that the link appears in serialized form documentation.
79 */
80 SERIALIZED_FORM,
82 /**
83 * Indicate that the link appears in serial member documentation.
84 */
85 SERIAL_MEMBER,
87 /**
88 * Indicate that the link appears in package documentation.
89 */
90 PACKAGE,
92 /**
93 * Indicate that the link appears in see tag documentation.
94 */
95 SEE_TAG,
97 /**
98 * Indicate that the link appears in value tag documentation.
99 */
100 VALUE_TAG,
102 /**
103 * Indicate that the link appears in tree documentation.
104 */
105 TREE,
107 /**
108 * Indicate that the link appears in a class list.
109 */
110 PACKAGE_FRAME,
112 /**
113 * The header in the class documentation.
114 */
115 CLASS_HEADER,
117 /**
118 * The signature in the class documentation.
119 */
120 CLASS_SIGNATURE,
122 /**
123 * The return type of a method.
124 */
125 RETURN_TYPE,
127 /**
128 * The return type of a method in a member summary.
129 */
130 SUMMARY_RETURN_TYPE,
132 /**
133 * The type of a method/constructor parameter.
134 */
135 EXECUTABLE_MEMBER_PARAM,
137 /**
138 * Super interface links.
139 */
140 SUPER_INTERFACES,
142 /**
143 * Implemented interface links.
144 */
145 IMPLEMENTED_INTERFACES,
147 /**
148 * Implemented class links.
149 */
150 IMPLEMENTED_CLASSES,
152 /**
153 * Subinterface links.
154 */
155 SUBINTERFACES,
157 /**
158 * Subclasses links.
159 */
160 SUBCLASSES,
162 /**
163 * The signature in the class documentation (implements/extends portion).
164 */
165 CLASS_SIGNATURE_PARENT_NAME,
167 /**
168 * The header for method documentation copied from parent.
169 */
170 METHOD_DOC_COPY,
172 /**
173 * Method "specified by" link.
174 */
175 METHOD_SPECIFIED_BY,
177 /**
178 * Method "overrides" link.
179 */
180 METHOD_OVERRIDES,
182 /**
183 * Annotation link.
184 */
185 ANNOTATION,
187 /**
188 * The header for field documentation copied from parent.
189 */
190 FIELD_DOC_COPY,
192 /**
193 * The parent nodes in the class tree.
194 */
195 CLASS_TREE_PARENT,
197 /**
198 * The type parameters of a method or constructor.
199 */
200 MEMBER_TYPE_PARAMS,
202 /**
203 * Indicate that the link appears in class use documentation.
204 */
205 CLASS_USE_HEADER,
207 /**
208 * The header for property documentation copied from parent.
209 */
210 PROPERTY_DOC_COPY
211 }
213 public final ConfigurationImpl configuration;
215 /**
216 * The location of the link.
217 */
218 public Kind context = Kind.DEFAULT;
220 /**
221 * The value of the marker #.
222 */
223 public String where = "";
225 /**
226 * String style of text defined in style sheet.
227 */
228 public String styleName = "";
230 /**
231 * The value of the target.
232 */
233 public String target = "";
235 /**
236 * Construct a LinkInfo object.
237 *
238 * @param configuration the configuration data for the doclet
239 * @param context the context of the link.
240 * @param classDoc the class to link to.
241 * @param label the label for the link.
242 * @param target the value of the target attribute.
243 */
244 public LinkInfoImpl(ConfigurationImpl configuration,
245 Kind context, ClassDoc classDoc, Content label, String target) {
246 this.configuration = configuration;
247 this.classDoc = classDoc;
248 this.label = label;
249 this.target = target;
250 setContext(context);
251 }
253 /**
254 * {@inherotDoc}
255 */
256 protected Content newContent() {
257 return new ContentBuilder();
258 }
260 /**
261 * Construct a LinkInfo object.
262 *
263 * @param configuration the configuration data for the doclet
264 * @param context the context of the link.
265 * @param classDoc the class to link to.
266 * @param where the value of the marker #.
267 * @param label the label for the link.
268 * @param isStrong true if the link should be strong.
269 * @param styleName String style of text defined in style sheet.
270 */
271 public LinkInfoImpl(ConfigurationImpl configuration,
272 Kind context, ClassDoc classDoc, String where, Content label,
273 boolean isStrong, String styleName) {
274 this.configuration = configuration;
275 this.classDoc = classDoc;
276 this.where = where;
277 this.label = label;
278 this.isStrong = isStrong;
279 this.styleName = styleName;
280 setContext(context);
281 }
283 /**
284 * Construct a LinkInfo object.
285 *
286 * @param configuration the configuration data for the doclet
287 * @param context the context of the link.
288 * @param classDoc the class to link to.
289 * @param where the value of the marker #.
290 * @param label the plain-text label for the link.
291 * @param isStrong true if the link should be strong.
292 */
293 public LinkInfoImpl(ConfigurationImpl configuration,
294 Kind context, ClassDoc classDoc, String where, String label,
295 boolean isStrong) {
296 this(configuration, context, classDoc, where, new StringContent(label),
297 isStrong, "");
298 }
300 /**
301 * Construct a LinkInfo object.
302 *
303 * @param configuration the configuration data for the doclet
304 * @param context the context of the link.
305 * @param classDoc the class to link to.
306 * @param where the value of the marker #.
307 * @param label the label for the link.
308 * @param isStrong true if the link should be strong.
309 */
310 public LinkInfoImpl(ConfigurationImpl configuration,
311 Kind context, ClassDoc classDoc, String where, Content label,
312 boolean isStrong) {
313 this(configuration, context, classDoc, where, label,
314 isStrong, "");
315 }
317 /**
318 * Construct a LinkInfo object.
319 *
320 * @param configuration the configuration data for the doclet
321 * @param classDoc the class to link to.
322 * @param label the label for the link.
323 */
324 public LinkInfoImpl(ConfigurationImpl configuration,
325 ClassDoc classDoc, Content label) {
326 this.configuration = configuration;
327 this.classDoc = classDoc;
328 this.label = label;
329 setContext(context);
330 }
332 /**
333 * Construct a LinkInfo object.
334 *
335 * @param configuration the configuration data for the doclet
336 * @param classDoc the class to link to.
337 * @param label the label for the link.
338 */
339 public LinkInfoImpl(ConfigurationImpl configuration,
340 ClassDoc classDoc, String label) {
341 this.configuration = configuration;
342 this.classDoc = classDoc;
343 this.label = new StringContent(label);
344 setContext(context);
345 }
347 /**
348 * Construct a LinkInfo object.
349 *
350 * @param configuration the configuration data for the doclet
351 * @param context the context of the link.
352 * @param executableMemberDoc the member to link to.
353 * @param isStrong true if the link should be strong.
354 */
355 public LinkInfoImpl(ConfigurationImpl configuration,
356 Kind context, ExecutableMemberDoc executableMemberDoc,
357 boolean isStrong) {
358 this.configuration = configuration;
359 this.executableMemberDoc = executableMemberDoc;
360 this.isStrong = isStrong;
361 setContext(context);
362 }
364 /**
365 * Construct a LinkInfo object.
366 *
367 * @param configuration the configuration data for the doclet
368 * @param context the context of the link.
369 * @param classDoc the class to link to.
370 * @param isStrong true if the link should be strong.
371 */
372 public LinkInfoImpl(ConfigurationImpl configuration,
373 Kind context, ClassDoc classDoc, boolean isStrong) {
374 this.configuration = configuration;
375 this.classDoc = classDoc;
376 this.isStrong = isStrong;
377 setContext(context);
378 }
380 /**
381 * Construct a LinkInfo object.
382 *
383 * @param configuration the configuration data for the doclet
384 * @param context the context of the link.
385 * @param type the class to link to.
386 */
387 public LinkInfoImpl(ConfigurationImpl configuration,
388 Kind context, Type type) {
389 this.configuration = configuration;
390 this.type = type;
391 setContext(context);
392 }
394 /**
395 * Construct a LinkInfo object.
396 *
397 * @param configuration the configuration data for the doclet
398 * @param context the context of the link.
399 * @param type the class to link to.
400 * @param isVarArg true if this is a link to a var arg.
401 */
402 public LinkInfoImpl(ConfigurationImpl configuration,
403 Kind context, Type type, boolean isVarArg) {
404 this.configuration = configuration;
405 this.type = type;
406 this.isVarArg = isVarArg;
407 setContext(context);
408 }
410 /**
411 * Construct a LinkInfo object.
412 *
413 * @param configuration the configuration data for the doclet
414 * @param context the context of the link.
415 * @param type the class to link to.
416 * @param label plain-text label for the link.
417 * @param isStrong true if the link should be strong.
418 */
419 public LinkInfoImpl(ConfigurationImpl configuration,
420 Kind context, Type type, String label,
421 boolean isStrong) {
422 this(configuration, context, type, new StringContent(label), isStrong);
423 }
425 /**
426 * Construct a LinkInfo object.
427 *
428 * @param configuration the configuration data for the doclet
429 * @param context the context of the link.
430 * @param type the class to link to.
431 * @param label the label for the link.
432 * @param isStrong true if the link should be strong.
433 */
434 public LinkInfoImpl(ConfigurationImpl configuration,
435 Kind context, Type type, Content label,
436 boolean isStrong) {
437 this.configuration = configuration;
438 this.type = type;
439 this.label = label;
440 this.isStrong = isStrong;
441 setContext(context);
442 }
444 /**
445 * Construct a LinkInfo object.
446 *
447 * @param configuration the configuration data for the doclet
448 * @param context the context of the link.
449 * @param classDoc the class to link to.
450 * @param label plain-text label for the link.
451 * @param isStrong true if the link should be strong.
452 */
453 public LinkInfoImpl(ConfigurationImpl configuration,
454 Kind context, ClassDoc classDoc, String label,
455 boolean isStrong) {
456 this(configuration, context, classDoc, new StringContent(label), isStrong);
457 }
459 /**
460 * Construct a LinkInfo object.
461 *
462 * @param configuration the configuration data for the doclet
463 * @param context the context of the link.
464 * @param classDoc the class to link to.
465 * @param label the label for the link.
466 * @param isStrong true if the link should be strong.
467 */
468 public LinkInfoImpl(ConfigurationImpl configuration,
469 Kind context, ClassDoc classDoc, Content label,
470 boolean isStrong) {
471 this.configuration = configuration;
472 this.classDoc = classDoc;
473 this.label = label;
474 this.isStrong = isStrong;
475 setContext(context);
476 }
478 /**
479 * {@inheritDoc}
480 */
481 public Kind getContext() {
482 return context;
483 }
485 /**
486 * {@inheritDoc}
487 *
488 * This method sets the link attributes to the appropriate values
489 * based on the context.
490 *
491 * @param c the context id to set.
492 */
493 public final void setContext(Kind c) {
494 //NOTE: Put context specific link code here.
495 switch (c) {
496 case ALL_CLASSES_FRAME:
497 case PACKAGE_FRAME:
498 case IMPLEMENTED_CLASSES:
499 case SUBCLASSES:
500 case METHOD_DOC_COPY:
501 case FIELD_DOC_COPY:
502 case PROPERTY_DOC_COPY:
503 case CLASS_USE_HEADER:
504 includeTypeInClassLinkLabel = false;
505 break;
507 case ANNOTATION:
508 excludeTypeParameterLinks = true;
509 excludeTypeBounds = true;
510 break;
512 case IMPLEMENTED_INTERFACES:
513 case SUPER_INTERFACES:
514 case SUBINTERFACES:
515 case CLASS_TREE_PARENT:
516 case TREE:
517 case CLASS_SIGNATURE_PARENT_NAME:
518 excludeTypeParameterLinks = true;
519 excludeTypeBounds = true;
520 includeTypeInClassLinkLabel = false;
521 includeTypeAsSepLink = true;
522 break;
524 case PACKAGE:
525 case CLASS_USE:
526 case CLASS_HEADER:
527 case CLASS_SIGNATURE:
528 excludeTypeParameterLinks = true;
529 includeTypeAsSepLink = true;
530 includeTypeInClassLinkLabel = false;
531 break;
533 case MEMBER_TYPE_PARAMS:
534 includeTypeAsSepLink = true;
535 includeTypeInClassLinkLabel = false;
536 break;
538 case RETURN_TYPE:
539 case SUMMARY_RETURN_TYPE:
540 excludeTypeBounds = true;
541 break;
542 case EXECUTABLE_MEMBER_PARAM:
543 excludeTypeBounds = true;
544 break;
545 }
546 context = c;
547 if (type != null &&
548 type.asTypeVariable()!= null &&
549 type.asTypeVariable().owner() instanceof ExecutableMemberDoc){
550 excludeTypeParameterLinks = true;
551 }
552 }
554 /**
555 * Return true if this link is linkable and false if we can't link to the
556 * desired place.
557 *
558 * @return true if this link is linkable and false if we can't link to the
559 * desired place.
560 */
561 public boolean isLinkable() {
562 return Util.isLinkable(classDoc, configuration);
563 }
564 }