home *** CD-ROM | disk | FTP | other *** search
/ Internet News 1999 October / INEWS_10_CD.ISO / pc / jdk / jdk1.2.2 / docs / tooldocs / javadoc / source / standard / AbstractSubWriter.java < prev    next >
Encoding:
Java Source  |  1999-09-19  |  13.4 KB  |  463 lines
  1. /*
  2.  * @(#)AbstractSubWriter.java    1.20 98/07/30
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package com.sun.tools.doclets.standard;
  16.  
  17. import com.sun.tools.doclets.*;
  18. import com.sun.javadoc.*;
  19. import java.util.*;
  20. import java.lang.reflect.Modifier;
  21.  
  22. /**
  23.  *
  24.  * @author Robert Field
  25.  * @author Atul M Dambalkar
  26.  */
  27. public abstract class AbstractSubWriter {
  28.  
  29.     protected final SubWriterHolderWriter writer;
  30.  
  31.     AbstractSubWriter(SubWriterHolderWriter writer) {
  32.         this.writer = writer;
  33.     }
  34.  
  35.     /*** abstracts ***/
  36.  
  37.     public abstract ProgramElementDoc[] members(ClassDoc cd);
  38.  
  39.     public abstract void printSummaryLabel(ClassDoc cd);
  40.  
  41.     public abstract void printInheritedSummaryLabel(ClassDoc cd);
  42.  
  43.     public abstract void printSummaryAnchor(ClassDoc cd);
  44.  
  45.     public abstract void printInheritedSummaryAnchor(ClassDoc cd);
  46.  
  47.     protected abstract void printSummaryType(ProgramElementDoc member);
  48.  
  49.     protected abstract void printSummaryLink(ClassDoc cd, 
  50.                                              ProgramElementDoc member);
  51.  
  52.     protected abstract void printInheritedSummaryLink(ClassDoc cd, 
  53.                                                       ProgramElementDoc member);
  54.  
  55.     protected abstract void printHeader(ClassDoc cd);
  56.  
  57.     protected abstract void printBodyHtmlEnd(ClassDoc cd);
  58.  
  59.     protected abstract void printMember(ProgramElementDoc elem);
  60.  
  61.     protected abstract void printDeprecatedLink(ProgramElementDoc member);
  62.  
  63.     protected abstract void printNavSummaryLink(ClassDoc cd, boolean link);
  64.  
  65.     protected abstract void printNavDetailLink(boolean link);
  66.  
  67.     /***  ***/
  68.  
  69.     protected void print(String str) {
  70.         writer.print(str);
  71.         writer.displayLength += str.length();
  72.     }
  73.  
  74.     protected void print(char ch) {
  75.         writer.print(ch);
  76.         writer.displayLength++;
  77.     }
  78.  
  79.     protected void bold(String str) {
  80.         writer.bold(str);
  81.         writer.displayLength += str.length();
  82.     }
  83.  
  84.     protected void printTypeLinkNoDimension(Type type) {
  85.         ClassDoc cd = type.asClassDoc();
  86.     if (cd == null) {
  87.         print(type.typeName()); 
  88.     } else {
  89.         writer.printClassLink(cd);
  90.     }
  91.     }
  92.  
  93.     protected void printTypeLink(Type type) {
  94.         printTypeLinkNoDimension(type);
  95.         print(type.dimension());
  96.     }
  97.  
  98.     /**
  99.      * Return a string describing the access modifier flags.
  100.      * Don't include native or synchronized.
  101.      *
  102.      * The modifier names are returned in canonical order, as
  103.      * specified by <em>The Java Language Specification</em>.
  104.      */
  105.     protected String modifierString(MemberDoc member) {
  106.         int ms = member.modifierSpecifier();
  107.         int no = Modifier.NATIVE | Modifier.SYNCHRONIZED;
  108.     return Modifier.toString(ms & ~no);
  109.     }
  110.  
  111.     protected String typeString(MemberDoc member) {
  112.         String type = "";
  113.         if (member instanceof MethodDoc) {
  114.             type = ((MethodDoc)member).returnType().toString();
  115.         } else if (member instanceof FieldDoc) {
  116.             type = ((FieldDoc)member).type().toString();
  117.         }
  118.         return type;
  119.     }
  120.  
  121.     protected void printModifiers(MemberDoc member) {
  122.         String mod;
  123.         mod = modifierString(member);
  124.         if(mod.length() > 0) {
  125.             print(mod);
  126.             print(' ');
  127.         }
  128.     }
  129.  
  130.     protected void printTypedName(Type type, String name) {
  131.         if (type != null) {
  132.             printTypeLink(type);
  133.         }
  134.         if(name.length() > 0) {
  135.             writer.space();
  136.             writer.print(name);
  137.         }
  138.     }
  139.  
  140.     protected String makeSpace(int len) {
  141.         if (len <= 0) {
  142.             return "";
  143.         }
  144.         StringBuffer sb = new StringBuffer(len);
  145.         for(int i = 0; i < len; i++) {
  146.             sb.append(' ');
  147.     }
  148.         return sb.toString();
  149.     }
  150.  
  151.     /**
  152.      * Print 'static' if static and type link.
  153.      */ 
  154.     protected void printStaticAndType(boolean isStatic, Type type) {
  155.         writer.printTypeSummaryHeader();
  156.         if (isStatic) {
  157.             print("static"); 
  158.         }
  159.         writer.space();
  160.         if (type != null) {
  161.             printTypeLink(type); 
  162.         }
  163.         writer.printTypeSummaryFooter();
  164.     }
  165.  
  166.     protected void printModifierAndType(ProgramElementDoc member, Type type) {
  167.         writer.printTypeSummaryHeader();
  168.         printModifier(member);
  169.         if (type == null) {
  170.         if (member.isOrdinaryClass()) {
  171.                 print("class");
  172.             } else {
  173.             print("interface");
  174.             }
  175.         } else {
  176.             printTypeLink(type); 
  177.         }
  178.         writer.printTypeSummaryFooter();
  179.     }
  180.  
  181.     protected void printModifier(ProgramElementDoc member) {
  182.         if (member.isProtected()) {
  183.             print("protected ");
  184.         } else if (member.isPrivate()) {
  185.             print("private ");
  186.         } else if (!member.isPublic()) { // Package private
  187.             writer.printText("doclet.Package_private");
  188.             print(" ");
  189.         }
  190.         if (member.isMethod() && ((MethodDoc)member).isAbstract()) {
  191.             print("abstract ");
  192.         }
  193.         if (member.isStatic()) {
  194.             print("static");
  195.         }
  196.         writer.space();
  197.     }
  198.  
  199.     protected void printComment(ProgramElementDoc member) {
  200.         if (member.inlineTags().length > 0) {
  201.             writer.dd();
  202.             writer.printInlineComment(member);
  203.         } 
  204.     }
  205.  
  206.     protected void printMemberCommentsFromInterfaces(ProgramElementDoc member) {
  207.         // N. A. for all except MethodDoc
  208.     }
  209.  
  210.     protected void printTags(ProgramElementDoc member) {
  211.         Tag[] since = member.tags("since");
  212.         if (member.seeTags().length + since.length > 0) {
  213.             writer.dd();
  214.             writer.dl();
  215.             writer.printSeeTags(member);
  216.             writer.printSinceTag(member);
  217.             writer.dlEnd();
  218.             writer.ddEnd();
  219.         }
  220.     }
  221.  
  222.     protected String name(ProgramElementDoc member) {
  223.         return member.name();
  224.     }
  225.  
  226.     protected void printDeprecated(ProgramElementDoc member) {
  227.         Tag[] deprs = member.tags("deprecated");
  228.         if (deprs.length > 0) {
  229.         writer.dd();
  230.             writer.boldText("doclet.Deprecated");
  231.             writer.space();
  232.             writer.printInlineDeprecatedComment(deprs[0]);
  233.         } else {
  234.             printDeprecatedClassComment(member);
  235.         }
  236.     }
  237.  
  238.     protected void printDeprecatedClassComment(ProgramElementDoc member) {
  239.         Tag[] deprs = member.containingClass().tags("deprecated");
  240.         if (deprs.length > 0) {
  241.             writer.dd();
  242.             writer.boldText("doclet.Deprecated");
  243.             writer.space();
  244.         }
  245.     }  
  246.   
  247.     protected void printHead(MemberDoc member) {
  248.         writer.h3();
  249.         writer.print(member.name());
  250.         writer.h3End();
  251.     }
  252.  
  253.     protected void printFullComment(ProgramElementDoc member) {
  254.         writer.dl();
  255.         printDeprecated(member);
  256.         printCommentAndTags(member);
  257.         writer.dlEnd();
  258.     }
  259.  
  260.     protected void printCommentAndTags(ProgramElementDoc member) {
  261.         printComment(member);
  262.         printTags(member);
  263.     }
  264.  
  265.     /**
  266.      * Forward to containing writer
  267.      */
  268.     public void printSummaryHeader(ClassDoc cd) {
  269.         writer.printSummaryHeader(this, cd);
  270.     }
  271.  
  272.     /**
  273.      * Forward to containing writer
  274.      */
  275.     public void printInheritedSummaryHeader(ClassDoc cd) {
  276.         writer.printInheritedSummaryHeader(this, cd);
  277.     }
  278.  
  279.     /**
  280.      * Forward to containing writer
  281.      */
  282.     public void printInheritedSummaryFooter(ClassDoc cd) {
  283.         writer.printInheritedSummaryFooter(this, cd);
  284.     }
  285.  
  286.     /**
  287.      * Forward to containing writer
  288.      */
  289.     public void printSummaryFooter(ClassDoc cd) {
  290.         writer.printSummaryFooter(this, cd);
  291.     }
  292.  
  293.     /**
  294.      * Forward to containing writer
  295.      */
  296.     public void printSummaryMember(ClassDoc cd, ProgramElementDoc member) {
  297.         writer.printSummaryMember(this, cd, member);
  298.     }
  299.  
  300.     /**
  301.      * Forward to containing writer
  302.      */
  303.     public void printInheritedSummaryMember(ClassDoc cd, 
  304.                                             ProgramElementDoc member) {
  305.         writer.printInheritedSummaryMember(this, cd, member);
  306.     }
  307.  
  308.     public void printMembersSummary(ClassDoc cd) {
  309.         ProgramElementDoc[] members = members(cd);
  310.         if (members.length > 0) {
  311.             Arrays.sort(members);
  312.             printSummaryHeader(cd);
  313.             for (int i = 0; i < members.length; ++i) {
  314.                 printSummaryMember(cd, members[i]);
  315.             }
  316.             printSummaryFooter(cd);
  317.         }
  318.     }
  319.  
  320.     public void printInheritedMembersSummary(ClassDoc cd) {
  321.         if (cd.isClass()) {
  322.             ClassDoc icd = cd.superclass();
  323.             while (icd != null) {
  324.                 printInheritedMembersInfo(icd);
  325.                 icd = icd.superclass();
  326.             }
  327.         } else { // this is an interface 
  328.             ClassDoc[] iin = cd.interfaces();
  329.             for (int i = 0; i < iin.length; i++) {
  330.                 printInheritedMembersInfo(iin[i]);
  331.             }
  332.             for (int i = 0; i < iin.length; i++) {
  333.                 printInheritedMembersSummary(iin[i]);
  334.             }
  335.         }
  336.     }
  337.  
  338.     protected void printInheritedMembersInfo(ClassDoc icd) {
  339.         ProgramElementDoc[] members = members(icd);
  340.         if (members.length > 0) {
  341.             Arrays.sort(members);
  342.             printInheritedSummaryHeader(icd);
  343.             printInheritedSummaryMember(icd, members[0]);
  344.             for (int i = 1; i < members.length; ++i) {
  345.                 print(", "); writer.println(' ');
  346.                 printInheritedSummaryMember(icd, members[i]);
  347.             }
  348.             printInheritedSummaryFooter(icd);
  349.         }
  350.     }
  351.  
  352.     public void printMembers(ClassDoc cd) {
  353.         ProgramElementDoc[] members = members(cd);
  354.         if (members.length > 0) {
  355.             printHeader(cd);
  356.             for (int i = 0; i < members.length; ++i) {
  357.                 if (i > 0) {
  358.                     writer.printMemberHeader();
  359.                 }
  360.                 writer.println("");
  361.                 printMember(members[i]);
  362.                 writer.printMemberFooter();
  363.             }
  364.             printBodyHtmlEnd(cd);
  365.         }
  366.     }
  367.  
  368.     /**
  369.      * Generate the code for listing the deprecated APIs. Create the table
  370.      * format for listing the API. Call methods from the sub-class to complete
  371.      * the generation.
  372.      */
  373.     protected void printDeprecatedAPI(List deprmembers, String headingKey) {
  374.         if (deprmembers.size() > 0) {
  375.             writer.tableIndexSummary();
  376.             writer.tableHeaderStart("#CCCCFF");
  377.             writer.boldText(headingKey);
  378.             writer.tableHeaderEnd();
  379.             for (int i = 0; i < deprmembers.size(); i++) {
  380.                 ProgramElementDoc member =(ProgramElementDoc)deprmembers.get(i);
  381.                 ClassDoc cd = member.containingClass();
  382.                 writer.trBgcolorStyle("white", "TableRowColor");
  383.                 writer.summaryRow(0);
  384.                 printDeprecatedLink(member);
  385.                 writer.br();
  386.                 writer.printNbsps();
  387.                 writer.printInlineDeprecatedComment(member.tags("deprecated")[0]);
  388.                 writer.space();
  389.                 writer.summaryRowEnd();
  390.                 writer.trEnd();
  391.             }
  392.             writer.tableEnd();
  393.             writer.space();
  394.             writer.p();
  395.         }
  396.     }
  397.  
  398.     /**
  399.      * Print use info.
  400.      */
  401.     protected void printUseInfo(Object mems, String heading) {
  402.         if (mems == null) {
  403.             return;
  404.         }
  405.         List members = (List)mems;
  406.         if (members.size() > 0) {
  407.             writer.tableIndexSummary();
  408.             writer.tableUseInfoHeaderStart("#CCCCFF");
  409.             writer.print(heading);
  410.             writer.tableHeaderEnd();
  411.             for (Iterator it = members.iterator(); it.hasNext(); ) {
  412.                 printSummaryMember(null, (ProgramElementDoc)it.next());
  413.             }
  414.             writer.tableEnd();
  415.             writer.space();
  416.             writer.p();
  417.         }
  418.     }
  419.  
  420.     protected void navSummaryLink(ClassDoc cd) {
  421.         ProgramElementDoc[] members = members(cd);
  422.         if (members.length > 0) {
  423.             printNavSummaryLink(null, true);
  424.             return;
  425.         } else {
  426.             ClassDoc icd = cd.superclass();
  427.             while (icd != null) {
  428.                 ProgramElementDoc[] inhmembers = members(icd);
  429.                 if (inhmembers.length > 0) {
  430.                     printNavSummaryLink(icd, true);
  431.                     return;
  432.                 }
  433.                 icd = icd.superclass();
  434.             }
  435.         }
  436.         printNavSummaryLink(null, false);
  437.     }
  438.    
  439.     protected void navDetailLink(ClassDoc cd) {
  440.         ProgramElementDoc[] members = members(cd);
  441.         printNavDetailLink(members.length > 0? true: false);
  442.     }           
  443.  
  444.     protected ProgramElementDoc[] eligibleMembers(ProgramElementDoc[] members) {
  445.         if (!Standard.configuration().nodeprecated) {
  446.             return members;
  447.         }
  448.         List list = new ArrayList();
  449.         for (int i = 0; i < members.length; i++) {
  450.             if (members[i].tags("deprecated").length == 0) {
  451.                 list.add(members[i]);
  452.             }
  453.         }
  454.         return (ProgramElementDoc[])list.
  455.                                toArray(new ProgramElementDoc[list.size()]); 
  456.     }
  457.  
  458.             
  459.         
  460. }  
  461.     
  462.     
  463.