Thu, 10 Jun 2010 17:09:56 -0700
6960407: Potential rebranding issues in openjdk/langtools repository sources
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1997, 2008, 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.doclets.formats.html;
28 import java.lang.reflect.Modifier;
29 import java.util.*;
31 import com.sun.javadoc.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
33 import com.sun.tools.doclets.internal.toolkit.taglets.*;
35 /**
36 * The base class for member writers.
37 *
38 * @author Robert Field
39 * @author Atul M Dambalkar
40 * @author Jamie Ho (Re-write)
41 * @author Bhavesh Patel (Modified)
42 */
43 public abstract class AbstractMemberWriter {
45 protected boolean printedSummaryHeader = false;
46 protected final SubWriterHolderWriter writer;
47 protected final ClassDoc classdoc;
48 public final boolean nodepr;
50 public AbstractMemberWriter(SubWriterHolderWriter writer,
51 ClassDoc classdoc) {
52 this.writer = writer;
53 this.nodepr = configuration().nodeprecated;
54 this.classdoc = classdoc;
55 }
57 public AbstractMemberWriter(SubWriterHolderWriter writer) {
58 this(writer, null);
59 }
61 /*** abstracts ***/
63 public abstract void printSummaryLabel();
65 public abstract void printTableSummary();
67 public abstract void printSummaryTableHeader(ProgramElementDoc member);
69 public abstract void printInheritedSummaryLabel(ClassDoc cd);
71 public abstract void printSummaryAnchor(ClassDoc cd);
73 public abstract void printInheritedSummaryAnchor(ClassDoc cd);
75 protected abstract void printSummaryType(ProgramElementDoc member);
77 protected void writeSummaryLink(ClassDoc cd, ProgramElementDoc member) {
78 writeSummaryLink(LinkInfoImpl.CONTEXT_MEMBER, cd, member);
79 }
81 protected abstract void writeSummaryLink(int context,
82 ClassDoc cd,
83 ProgramElementDoc member);
85 protected abstract void writeInheritedSummaryLink(ClassDoc cd,
86 ProgramElementDoc member);
88 protected abstract void writeDeprecatedLink(ProgramElementDoc member);
90 protected abstract void printNavSummaryLink(ClassDoc cd, boolean link);
92 protected abstract void printNavDetailLink(boolean link);
94 /*** ***/
96 protected void print(String str) {
97 writer.print(str);
98 writer.displayLength += str.length();
99 }
101 protected void print(char ch) {
102 writer.print(ch);
103 writer.displayLength++;
104 }
106 protected void strong(String str) {
107 writer.strong(str);
108 writer.displayLength += str.length();
109 }
111 /**
112 * Return a string describing the access modifier flags.
113 * Don't include native or synchronized.
114 *
115 * The modifier names are returned in canonical order, as
116 * specified by <em>The Java Language Specification</em>.
117 */
118 protected String modifierString(MemberDoc member) {
119 int ms = member.modifierSpecifier();
120 int no = Modifier.NATIVE | Modifier.SYNCHRONIZED;
121 return Modifier.toString(ms & ~no);
122 }
124 protected String typeString(MemberDoc member) {
125 String type = "";
126 if (member instanceof MethodDoc) {
127 type = ((MethodDoc)member).returnType().toString();
128 } else if (member instanceof FieldDoc) {
129 type = ((FieldDoc)member).type().toString();
130 }
131 return type;
132 }
134 protected void printModifiers(MemberDoc member) {
135 String mod = modifierString(member);
136 // According to JLS, we should not be showing public modifier for
137 // interface methods.
138 if ((member.isField() || member.isMethod()) &&
139 writer instanceof ClassWriterImpl &&
140 ((ClassWriterImpl) writer).getClassDoc().isInterface()) {
141 mod = Util.replaceText(mod, "public", "").trim();
142 }
143 if(mod.length() > 0) {
144 print(mod);
145 print(' ');
146 }
147 }
149 protected String makeSpace(int len) {
150 if (len <= 0) {
151 return "";
152 }
153 StringBuffer sb = new StringBuffer(len);
154 for(int i = 0; i < len; i++) {
155 sb.append(' ');
156 }
157 return sb.toString();
158 }
160 /**
161 * Print 'static' if static and type link.
162 */
163 protected void printStaticAndType(boolean isStatic, Type type) {
164 writer.printTypeSummaryHeader();
165 if (isStatic) {
166 print("static");
167 }
168 writer.space();
169 if (type != null) {
170 writer.printLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
171 type));
172 }
173 writer.printTypeSummaryFooter();
174 }
176 /**
177 * Print the modifier and type for the member in the member summary.
178 *
179 * @param member the member to print the type for.
180 * @param type the type to print.
181 */
182 protected void printModifierAndType(ProgramElementDoc member, Type type) {
183 writer.printTypeSummaryHeader();
184 printModifier(member);
185 if (type == null) {
186 writer.space();
187 if (member.isClass()) {
188 print("class");
189 } else {
190 print("interface");
191 }
192 } else {
193 if (member instanceof ExecutableMemberDoc &&
194 ((ExecutableMemberDoc) member).typeParameters().length > 0) {
195 //Code to avoid ugly wrapping in member summary table.
196 writer.table(0,0,0);
197 writer.trAlignVAlign("right", "");
198 writer.tdNowrap();
199 writer.font("-1");
200 writer.code();
201 int displayLength = ((AbstractExecutableMemberWriter) this).
202 writeTypeParameters((ExecutableMemberDoc) member);
203 if (displayLength > 10) {
204 writer.br();
205 }
206 writer.printLink(new LinkInfoImpl(
207 LinkInfoImpl.CONTEXT_SUMMARY_RETURN_TYPE, type));
208 writer.codeEnd();
209 writer.fontEnd();
210 writer.tdEnd();
211 writer.trEnd();
212 writer.tableEnd();
213 } else {
214 writer.space();
215 writer.printLink(new LinkInfoImpl(
216 LinkInfoImpl.CONTEXT_SUMMARY_RETURN_TYPE, type));
217 }
219 }
220 writer.printTypeSummaryFooter();
221 }
223 private void printModifier(ProgramElementDoc member) {
224 if (member.isProtected()) {
225 print("protected ");
226 } else if (member.isPrivate()) {
227 print("private ");
228 } else if (!member.isPublic()) { // Package private
229 writer.printText("doclet.Package_private");
230 print(" ");
231 }
232 if (member.isMethod() && ((MethodDoc)member).isAbstract()) {
233 print("abstract ");
234 }
235 if (member.isStatic()) {
236 print("static");
237 }
238 }
240 /**
241 * Print the deprecated output for the given member.
242 *
243 * @param member the member being documented.
244 */
245 protected void printDeprecated(ProgramElementDoc member) {
246 String output = (new DeprecatedTaglet()).getTagletOutput(member,
247 writer.getTagletWriterInstance(false)).toString().trim();
248 if (!output.isEmpty()) {
249 writer.printMemberDetailsListStartTag();
250 writer.print(output);
251 }
252 }
254 protected void printComment(ProgramElementDoc member) {
255 if (member.inlineTags().length > 0) {
256 writer.printMemberDetailsListStartTag();
257 writer.dd();
258 writer.printInlineComment(member);
259 writer.ddEnd();
260 }
261 }
263 protected String name(ProgramElementDoc member) {
264 return member.name();
265 }
267 protected void printHead(MemberDoc member) {
268 writer.h3();
269 writer.print(member.name());
270 writer.h3End();
271 }
273 protected void printFullComment(ProgramElementDoc member) {
274 if(configuration().nocomment){
275 return;
276 }
277 writer.dl();
278 print(((TagletOutputImpl)
279 (new DeprecatedTaglet()).getTagletOutput(member,
280 writer.getTagletWriterInstance(false))).toString());
281 printCommentAndTags(member);
282 writer.dlEnd();
283 }
285 protected void printCommentAndTags(ProgramElementDoc member) {
286 printComment(member);
287 writer.printTags(member);
288 }
290 /**
291 * Write the member footer.
292 */
293 protected void printMemberFooter() {
294 writer.printMemberDetailsListEndTag();
295 assert !writer.getMemberDetailsListPrinted();
296 }
298 /**
299 * Forward to containing writer
300 */
301 public void printSummaryHeader(ClassDoc cd) {
302 printedSummaryHeader = true;
303 writer.printSummaryHeader(this, cd);
304 }
306 /**
307 * Forward to containing writer
308 */
309 public void printInheritedSummaryHeader(ClassDoc cd) {
310 writer.printInheritedSummaryHeader(this, cd);
311 }
313 /**
314 * Forward to containing writer
315 */
316 public void printInheritedSummaryFooter(ClassDoc cd) {
317 writer.printInheritedSummaryFooter(this, cd);
318 }
320 /**
321 * Forward to containing writer
322 */
323 public void printSummaryFooter(ClassDoc cd) {
324 writer.printSummaryFooter(this, cd);
325 }
327 /**
328 * Return true if the given <code>ProgramElement</code> is inherited
329 * by the class that is being documented.
330 *
331 * @param ped The <code>ProgramElement</code> being checked.
332 * return true if the <code>ProgramElement</code> is being inherited and
333 * false otherwise.
334 */
335 protected boolean isInherited(ProgramElementDoc ped){
336 if(ped.isPrivate() || (ped.isPackagePrivate() &&
337 ! ped.containingPackage().equals(classdoc.containingPackage()))){
338 return false;
339 }
340 return true;
341 }
344 /**
345 * Generate the code for listing the deprecated APIs. Create the table
346 * format for listing the API. Call methods from the sub-class to complete
347 * the generation.
348 */
349 protected void printDeprecatedAPI(List<Doc> deprmembers, String headingKey, String tableSummary, String[] tableHeader) {
350 if (deprmembers.size() > 0) {
351 writer.tableIndexSummary(tableSummary);
352 writer.tableCaptionStart();
353 writer.printText(headingKey);
354 writer.tableCaptionEnd();
355 writer.summaryTableHeader(tableHeader, "col");
356 for (int i = 0; i < deprmembers.size(); i++) {
357 ProgramElementDoc member =(ProgramElementDoc)deprmembers.get(i);
358 writer.trBgcolorStyle("white", "TableRowColor");
359 writer.summaryRow(0);
360 writeDeprecatedLink(member);
361 writer.br();
362 writer.printNbsps();
363 if (member.tags("deprecated").length > 0)
364 writer.printInlineDeprecatedComment(member, member.tags("deprecated")[0]);
365 writer.space();
366 writer.summaryRowEnd();
367 writer.trEnd();
368 }
369 writer.tableEnd();
370 writer.space();
371 writer.p();
372 }
373 }
375 /**
376 * Print use info.
377 */
378 protected void printUseInfo(List<? extends ProgramElementDoc> mems, String heading, String tableSummary) {
379 if (mems == null) {
380 return;
381 }
382 List<? extends ProgramElementDoc> members = mems;
383 boolean printedUseTableHeader = false;
384 if (members.size() > 0) {
385 writer.tableIndexSummary(tableSummary);
386 writer.tableSubCaptionStart();
387 writer.print(heading);
388 writer.tableCaptionEnd();
389 for (Iterator<? extends ProgramElementDoc> it = members.iterator(); it.hasNext(); ) {
390 ProgramElementDoc pgmdoc = it.next();
391 ClassDoc cd = pgmdoc.containingClass();
392 if (!printedUseTableHeader) {
393 // Passing ProgramElementDoc helps decides printing
394 // interface or class header in case of nested classes.
395 this.printSummaryTableHeader(pgmdoc);
396 printedUseTableHeader = true;
397 }
399 writer.printSummaryLinkType(this, pgmdoc);
400 if (cd != null && !(pgmdoc instanceof ConstructorDoc)
401 && !(pgmdoc instanceof ClassDoc)) {
402 // Add class context
403 writer.strong(cd.name() + ".");
404 }
405 writeSummaryLink(
406 pgmdoc instanceof ClassDoc ?
407 LinkInfoImpl.CONTEXT_CLASS_USE : LinkInfoImpl.CONTEXT_MEMBER,
408 cd, pgmdoc);
409 writer.printSummaryLinkComment(this, pgmdoc);
410 }
411 writer.tableEnd();
412 writer.space();
413 writer.p();
414 }
415 }
417 protected void navDetailLink(List<?> members) {
418 printNavDetailLink(members.size() > 0? true: false);
419 }
422 protected void navSummaryLink(List<?> members,
423 VisibleMemberMap visibleMemberMap) {
424 if (members.size() > 0) {
425 printNavSummaryLink(null, true);
426 return;
427 } else {
428 ClassDoc icd = classdoc.superclass();
429 while (icd != null) {
430 List<?> inhmembers = visibleMemberMap.getMembersFor(icd);
431 if (inhmembers.size() > 0) {
432 printNavSummaryLink(icd, true);
433 return;
434 }
435 icd = icd.superclass();
436 }
437 }
438 printNavSummaryLink(null, false);
439 }
441 protected void serialWarning(SourcePosition pos, String key, String a1, String a2) {
442 if (configuration().serialwarn) {
443 ConfigurationImpl.getInstance().getDocletSpecificMsg().warning(pos, key, a1, a2);
444 }
445 }
447 public ProgramElementDoc[] eligibleMembers(ProgramElementDoc[] members) {
448 return nodepr? Util.excludeDeprecatedMembers(members): members;
449 }
451 public ConfigurationImpl configuration() {
452 return writer.configuration;
453 }
455 /**
456 * {@inheritDoc}
457 */
458 public void writeMemberSummary(ClassDoc classDoc, ProgramElementDoc member,
459 Tag[] firstSentenceTags, boolean isFirst, boolean isLast) {
460 writer.printSummaryLinkType(this, member);
461 writeSummaryLink(classDoc, member);
462 writer.printSummaryLinkComment(this, member, firstSentenceTags);
463 }
464 }