1 /*

     2  * Copyright (c) 1998, 2019, 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 jdk.javadoc.internal.doclets.formats.html;

    27 

    28 import java.util.*;

    29 

    30 import javax.lang.model.element.PackageElement;

    31 import javax.lang.model.element.TypeElement;

    32 

    33 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;

    34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;

    35 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;

    36 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;

    37 import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;

    38 import jdk.javadoc.internal.doclets.toolkit.Content;

    39 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;

    40 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;

    41 

    42 /**

    43  * Class to generate file for each package contents in the left-hand bottom

    44  * frame. This will list all the Class Kinds in the package. A click on any

    45  * class-kind will update the right-hand frame with the clicked class-kind page.

    46  *

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

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

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

    50  *  deletion without notice.</b>

    51  *

    52  * @author Atul M Dambalkar

    53  * @author Bhavesh Patel (Modified)

    54  */

    55 public class PackageFrameWriter extends HtmlDocletWriter {

    56 

    57     /**

    58      * The package being documented.

    59      */

    60     private final PackageElement packageElement;

    61 

    62     /**

    63      * The classes to be documented.  Use this to filter out classes

    64      * that will not be documented.

    65      */

    66     private SortedSet<TypeElement> documentedClasses;

    67 

    68     /**

    69      * Constructor to construct PackageFrameWriter object and to generate

    70      * "package-frame.html" file in the respective package directory.

    71      * For example for package "java.lang" this will generate file

    72      * "package-frame.html" file in the "java/lang" directory. It will also

    73      * create "java/lang" directory in the current or the destination directory

    74      * if it doesn't exist.

    75      *

    76      * @param configuration the configuration of the doclet.

    77      * @param packageElement PackageElement under consideration.

    78      */

    79     public PackageFrameWriter(HtmlConfiguration configuration, PackageElement packageElement) {

    80         super(configuration,

    81                 configuration.docPaths.forPackage(packageElement).resolve(DocPaths.PACKAGE_FRAME));

    82         this.packageElement = packageElement;

    83         if (configuration.getSpecifiedPackageElements().isEmpty()) {

    84             documentedClasses = new TreeSet<>(utils.makeGeneralPurposeComparator());

    85             documentedClasses.addAll(configuration.getIncludedTypeElements());

    86         }

    87     }

    88 

    89     /**

    90      * Generate a package summary page for the left-hand bottom frame. Construct

    91      * the PackageFrameWriter object and then use it generate the file.

    92      *

    93      * @param configuration the current configuration of the doclet.

    94      * @param packageElement The package for which "pacakge-frame.html" is to be generated.

    95      * @throws DocFileIOException if there is a problem generating the package summary page

    96      */

    97     public static void generate(HtmlConfiguration configuration, PackageElement packageElement)

    98             throws DocFileIOException {

    99         PackageFrameWriter packgen = new PackageFrameWriter(configuration, packageElement);

   100         String pkgName = configuration.utils.getPackageName(packageElement);

   101         HtmlTree body = packgen.getBody(false, packgen.getWindowTitle(pkgName));

   102         Content pkgNameContent = new StringContent(pkgName);

   103         HtmlTree htmlTree = HtmlTree.MAIN();

   104         Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.bar,

   105                 packgen.getTargetPackageLink(packageElement, "classFrame", pkgNameContent));

   106         htmlTree.add(heading);

   107         HtmlTree div = new HtmlTree(HtmlTag.DIV);

   108         div.setStyle(HtmlStyle.indexContainer);

   109         packgen.addClassListing(div);

   110         htmlTree.add(div);

   111         body.add(htmlTree);

   112         packgen.printHtmlDocument(

   113                 configuration.metakeywords.getMetaKeywords(packageElement),

   114                 getDescription("package summary (frame)", packageElement),

   115                 body);

   116     }

   117 

   118     /**

   119      * Add class listing for all the classes in this package. Divide class

   120      * listing as per the class kind and generate separate listing for

   121      * Classes, Interfaces, Exceptions and Errors.

   122      *

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

   124      */

   125     protected void addClassListing(HtmlTree contentTree) {

   126         BaseConfiguration config = configuration;

   127         if (utils.isSpecified(packageElement)) {

   128             addClassKindListing(utils.getInterfaces(packageElement),

   129                 contents.interfaces, contentTree);

   130             addClassKindListing(utils.getOrdinaryClasses(packageElement),

   131                 contents.classes, contentTree);

   132             addClassKindListing(utils.getEnums(packageElement),

   133                 contents.enums, contentTree);

   134             addClassKindListing(utils.getExceptions(packageElement),

   135                 contents.exceptions, contentTree);

   136             addClassKindListing(utils.getErrors(packageElement),

   137                 contents.errors, contentTree);

   138             addClassKindListing(utils.getAnnotationTypes(packageElement),

   139                 contents.annotationTypes, contentTree);

   140         } else {

   141             addClassKindListing(config.typeElementCatalog.interfaces(packageElement),

   142                 contents.interfaces, contentTree);

   143             addClassKindListing(config.typeElementCatalog.ordinaryClasses(packageElement),

   144                 contents.classes, contentTree);

   145             addClassKindListing(config.typeElementCatalog.enums(packageElement),

   146                 contents.enums, contentTree);

   147             addClassKindListing(config.typeElementCatalog.exceptions(packageElement),

   148                 contents.exceptions, contentTree);

   149             addClassKindListing(config.typeElementCatalog.errors(packageElement),

   150                 contents.errors, contentTree);

   151             addClassKindListing(config.typeElementCatalog.annotationTypes(packageElement),

   152                 contents.annotationTypes, contentTree);

   153         }

   154     }

   155 

   156     /**

   157      * Add specific class kind listing. Also add label to the listing.

   158      *

   159      * @param list list of specific class kinds, namely Class or Interface or Exception or Error

   160      * @param labelContent content tree of the label to be added

   161      * @param contentTree the content tree to which the class kind listing will be added

   162      */

   163     protected void addClassKindListing(Iterable<TypeElement> list, Content labelContent,

   164             HtmlTree contentTree) {

   165         SortedSet<TypeElement> tset = utils.filterOutPrivateClasses(list, configuration.javafx);

   166         if(!tset.isEmpty()) {

   167             boolean printedHeader = false;

   168             HtmlTree htmlTree = HtmlTree.SECTION();

   169             HtmlTree ul = new HtmlTree(HtmlTag.UL);

   170             ul.setTitle(labelContent);

   171             for (TypeElement typeElement : tset) {

   172                 if (documentedClasses != null && !documentedClasses.contains(typeElement)) {

   173                     continue;

   174                 }

   175                 if (!utils.isCoreClass(typeElement) || !configuration.isGeneratedDoc(typeElement)) {

   176                     continue;

   177                 }

   178                 if (!printedHeader) {

   179                     Content heading = HtmlTree.HEADING(Headings.CONTENT_HEADING,

   180                                                        true, labelContent);

   181                     htmlTree.add(heading);

   182                     printedHeader = true;

   183                 }

   184                 Content arr_i_name = new StringContent(utils.getSimpleName(typeElement));

   185                 if (utils.isInterface(typeElement))

   186                     arr_i_name = HtmlTree.SPAN(HtmlStyle.interfaceName, arr_i_name);

   187                 Content link = getLink(new LinkInfoImpl(configuration,

   188                                                         LinkInfoImpl.Kind.PACKAGE_FRAME, typeElement).label(arr_i_name).target("classFrame"));

   189                 Content li = HtmlTree.LI(link);

   190                 ul.add(li);

   191             }

   192             htmlTree.add(ul);

   193             contentTree.add(htmlTree);

   194         }

   195     }

   196 }