1 /*

     2  * Copyright (c) 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  */

    25 

    26 package com.sun.tools.doclets.internal.toolkit.builders;

    27 

    28 import java.io.*;

    29 

    30 import com.sun.javadoc.*;

    31 import com.sun.tools.javac.jvm.Profile;

    32 import com.sun.tools.doclets.internal.toolkit.*;

    33 import com.sun.tools.doclets.internal.toolkit.util.*;

    34 

    35 /**

    36  * Builds the summary for a given profile.

    37  *

    38  *  <p><b>This is NOT part of any supported API.

    39  *  If you write code that depends on this, you do so at your own risk.

    40  *  This code and its internal interfaces are subject to change or

    41  *  deletion without notice.</b>

    42  *

    43  * @author Bhavesh Patel

    44  */

    45 public class ProfileSummaryBuilder extends AbstractBuilder {

    46     /**

    47      * The root element of the profile summary XML is {@value}.

    48      */

    49     public static final String ROOT = "ProfileDoc";

    50 

    51     /**

    52      * The profile being documented.

    53      */

    54     private final Profile profile;

    55 

    56     /**

    57      * The doclet specific writer that will output the result.

    58      */

    59     private final ProfileSummaryWriter profileWriter;

    60 

    61     /**

    62      * The content that will be added to the profile summary documentation tree.

    63      */

    64     private Content contentTree;

    65 

    66     /**

    67      * The profile package being documented.

    68      */

    69     private PackageDoc pkg;

    70 

    71     /**

    72      * Construct a new ProfileSummaryBuilder.

    73      *

    74      * @param context  the build context.

    75      * @param profile the profile being documented.

    76      * @param profileWriter the doclet specific writer that will output the

    77      *        result.

    78      */

    79     private ProfileSummaryBuilder(Context context,

    80             Profile profile, ProfileSummaryWriter profileWriter) {

    81         super(context);

    82         this.profile = profile;

    83         this.profileWriter = profileWriter;

    84     }

    85 

    86     /**

    87      * Construct a new ProfileSummaryBuilder.

    88      *

    89      * @param context  the build context.

    90      * @param profile the profile being documented.

    91      * @param profileWriter the doclet specific writer that will output the

    92      *        result.

    93      *

    94      * @return an instance of a ProfileSummaryBuilder.

    95      */

    96     public static ProfileSummaryBuilder getInstance(Context context,

    97             Profile profile, ProfileSummaryWriter profileWriter) {

    98         return new ProfileSummaryBuilder(context, profile, profileWriter);

    99     }

   100 

   101     /**

   102      * Build the profile summary.

   103      */

   104     public void build() throws IOException {

   105         if (profileWriter == null) {

   106             //Doclet does not support this output.

   107             return;

   108         }

   109         build(layoutParser.parseXML(ROOT), contentTree);

   110     }

   111 

   112     /**

   113      * {@inheritDoc}

   114      */

   115     public String getName() {

   116         return ROOT;

   117     }

   118 

   119     /**

   120      * Build the profile documentation.

   121      *

   122      * @param node the XML element that specifies which components to document

   123      * @param contentTree the content tree to which the documentation will be added

   124      */

   125     public void buildProfileDoc(XMLNode node, Content contentTree) throws Exception {

   126         contentTree = profileWriter.getProfileHeader(profile.name);

   127         buildChildren(node, contentTree);

   128         profileWriter.addProfileFooter(contentTree);

   129         profileWriter.printDocument(contentTree);

   130         profileWriter.close();

   131         Util.copyDocFiles(configuration, DocPaths.profileSummary(profile.name));

   132     }

   133 

   134     /**

   135      * Build the content for the profile doc.

   136      *

   137      * @param node the XML element that specifies which components to document

   138      * @param contentTree the content tree to which the profile contents

   139      *                    will be added

   140      */

   141     public void buildContent(XMLNode node, Content contentTree) {

   142         Content profileContentTree = profileWriter.getContentHeader();

   143         buildChildren(node, profileContentTree);

   144         contentTree.addContent(profileContentTree);

   145     }

   146 

   147     /**

   148      * Build the profile summary.

   149      *

   150      * @param node the XML element that specifies which components to document

   151      * @param profileContentTree the profile content tree to which the summaries will

   152      *                           be added

   153      */

   154     public void buildSummary(XMLNode node, Content profileContentTree) {

   155         Content summaryContentTree = profileWriter.getSummaryHeader();

   156         buildChildren(node, summaryContentTree);

   157         profileContentTree.addContent(profileWriter.getSummaryTree(summaryContentTree));

   158     }

   159 

   160     /**

   161      * Build the profile package summary.

   162      *

   163      * @param node the XML element that specifies which components to document

   164      * @param summaryContentTree the content tree to which the summaries will

   165      *                           be added

   166      */

   167     public void buildPackageSummary(XMLNode node, Content summaryContentTree) {

   168         PackageDoc[] packages = configuration.profilePackages.get(profile.name);

   169         for (int i = 0; i < packages.length; i++) {

   170             this.pkg = packages[i];

   171             Content packageSummaryContentTree = profileWriter.getPackageSummaryHeader(this.pkg);

   172             buildChildren(node, packageSummaryContentTree);

   173             summaryContentTree.addContent(profileWriter.getPackageSummaryTree(

   174                     packageSummaryContentTree));

   175         }

   176     }

   177 

   178     /**

   179      * Build the summary for the interfaces in the package.

   180      *

   181      * @param node the XML element that specifies which components to document

   182      * @param packageSummaryContentTree the tree to which the interface summary

   183      *                           will be added

   184      */

   185     public void buildInterfaceSummary(XMLNode node, Content packageSummaryContentTree) {

   186         String interfaceTableSummary =

   187                 configuration.getText("doclet.Member_Table_Summary",

   188                 configuration.getText("doclet.Interface_Summary"),

   189                 configuration.getText("doclet.interfaces"));

   190         String[] interfaceTableHeader = new String[] {

   191             configuration.getText("doclet.Interface"),

   192             configuration.getText("doclet.Description")

   193         };

   194         ClassDoc[] interfaces = pkg.interfaces();

   195         if (interfaces.length > 0) {

   196             profileWriter.addClassesSummary(

   197                     interfaces,

   198                     configuration.getText("doclet.Interface_Summary"),

   199                     interfaceTableSummary, interfaceTableHeader, packageSummaryContentTree);

   200         }

   201     }

   202 

   203     /**

   204      * Build the summary for the classes in the package.

   205      *

   206      * @param node the XML element that specifies which components to document

   207      * @param packageSummaryContentTree the tree to which the class summary will

   208      *                           be added

   209      */

   210     public void buildClassSummary(XMLNode node, Content packageSummaryContentTree) {

   211         String classTableSummary =

   212                 configuration.getText("doclet.Member_Table_Summary",

   213                 configuration.getText("doclet.Class_Summary"),

   214                 configuration.getText("doclet.classes"));

   215         String[] classTableHeader = new String[] {

   216             configuration.getText("doclet.Class"),

   217             configuration.getText("doclet.Description")

   218         };

   219         ClassDoc[] classes = pkg.ordinaryClasses();

   220         if (classes.length > 0) {

   221             profileWriter.addClassesSummary(

   222                     classes,

   223                     configuration.getText("doclet.Class_Summary"),

   224                     classTableSummary, classTableHeader, packageSummaryContentTree);

   225         }

   226     }

   227 

   228     /**

   229      * Build the summary for the enums in the package.

   230      *

   231      * @param node the XML element that specifies which components to document

   232      * @param packageSummaryContentTree the tree to which the enum summary will

   233      *                           be added

   234      */

   235     public void buildEnumSummary(XMLNode node, Content packageSummaryContentTree) {

   236         String enumTableSummary =

   237                 configuration.getText("doclet.Member_Table_Summary",

   238                 configuration.getText("doclet.Enum_Summary"),

   239                 configuration.getText("doclet.enums"));

   240         String[] enumTableHeader = new String[] {

   241             configuration.getText("doclet.Enum"),

   242             configuration.getText("doclet.Description")

   243         };

   244         ClassDoc[] enums = pkg.enums();

   245         if (enums.length > 0) {

   246             profileWriter.addClassesSummary(

   247                     enums,

   248                     configuration.getText("doclet.Enum_Summary"),

   249                     enumTableSummary, enumTableHeader, packageSummaryContentTree);

   250         }

   251     }

   252 

   253     /**

   254      * Build the summary for the exceptions in the package.

   255      *

   256      * @param node the XML element that specifies which components to document

   257      * @param packageSummaryContentTree the tree to which the exception summary will

   258      *                           be added

   259      */

   260     public void buildExceptionSummary(XMLNode node, Content packageSummaryContentTree) {

   261         String exceptionTableSummary =

   262                 configuration.getText("doclet.Member_Table_Summary",

   263                 configuration.getText("doclet.Exception_Summary"),

   264                 configuration.getText("doclet.exceptions"));

   265         String[] exceptionTableHeader = new String[] {

   266             configuration.getText("doclet.Exception"),

   267             configuration.getText("doclet.Description")

   268         };

   269         ClassDoc[] exceptions = pkg.exceptions();

   270         if (exceptions.length > 0) {

   271             profileWriter.addClassesSummary(

   272                     exceptions,

   273                     configuration.getText("doclet.Exception_Summary"),

   274                     exceptionTableSummary, exceptionTableHeader, packageSummaryContentTree);

   275         }

   276     }

   277 

   278     /**

   279      * Build the summary for the errors in the package.

   280      *

   281      * @param node the XML element that specifies which components to document

   282      * @param packageSummaryContentTree the tree to which the error summary will

   283      *                           be added

   284      */

   285     public void buildErrorSummary(XMLNode node, Content packageSummaryContentTree) {

   286         String errorTableSummary =

   287                 configuration.getText("doclet.Member_Table_Summary",

   288                 configuration.getText("doclet.Error_Summary"),

   289                 configuration.getText("doclet.errors"));

   290         String[] errorTableHeader = new String[] {

   291             configuration.getText("doclet.Error"),

   292             configuration.getText("doclet.Description")

   293         };

   294         ClassDoc[] errors = pkg.errors();

   295         if (errors.length > 0) {

   296             profileWriter.addClassesSummary(

   297                     errors,

   298                     configuration.getText("doclet.Error_Summary"),

   299                     errorTableSummary, errorTableHeader, packageSummaryContentTree);

   300         }

   301     }

   302 

   303     /**

   304      * Build the summary for the annotation type in the package.

   305      *

   306      * @param node the XML element that specifies which components to document

   307      * @param packageSummaryContentTree the tree to which the annotation type

   308      *                           summary will be added

   309      */

   310     public void buildAnnotationTypeSummary(XMLNode node, Content packageSummaryContentTree) {

   311         String annotationtypeTableSummary =

   312                 configuration.getText("doclet.Member_Table_Summary",

   313                 configuration.getText("doclet.Annotation_Types_Summary"),

   314                 configuration.getText("doclet.annotationtypes"));

   315         String[] annotationtypeTableHeader = new String[] {

   316             configuration.getText("doclet.AnnotationType"),

   317             configuration.getText("doclet.Description")

   318         };

   319         ClassDoc[] annotationTypes = pkg.annotationTypes();

   320         if (annotationTypes.length > 0) {

   321             profileWriter.addClassesSummary(

   322                     annotationTypes,

   323                     configuration.getText("doclet.Annotation_Types_Summary"),

   324                     annotationtypeTableSummary, annotationtypeTableHeader,

   325                     packageSummaryContentTree);

   326         }

   327     }

   328 }