jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java@6f0746b6de9f

     1 /*

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

    26 package com.sun.tools.doclets.formats.html.markup;

    28 import java.io.*;

    29 import java.util.*;

    31 import com.sun.javadoc.*;

    32 import com.sun.tools.doclets.formats.html.ConfigurationImpl;

    33 import com.sun.tools.doclets.formats.html.SectionName;

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

    35 import com.sun.tools.doclets.internal.toolkit.util.DocFile;

    36 import com.sun.tools.doclets.internal.toolkit.util.DocLink;

    37 import com.sun.tools.doclets.internal.toolkit.util.DocPath;

    40 /**

    41  * Class for the Html Format Code Generation specific to JavaDoc.

    42  * This Class contains methods related to the Html Code Generation which

    43  * are used by the Sub-Classes in the package com.sun.tools.doclets.standard

    44  * and com.sun.tools.doclets.oneone.

    45  *

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

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

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

    49  *  deletion without notice.</b>

    50  *

    51  * @since 1.2

    52  * @author Atul M Dambalkar

    53  * @author Robert Field

    54  */

    55 public abstract class HtmlDocWriter extends HtmlWriter {

    57     public static final String CONTENT_TYPE = "text/html";

    59     /**

    60      * Constructor. Initializes the destination file name through the super

    61      * class HtmlWriter.

    62      *

    63      * @param filename String file name.

    64      */

    65     public HtmlDocWriter(Configuration configuration, DocPath filename)

    66             throws IOException {

    67         super(configuration, filename);

    68         configuration.message.notice("doclet.Generating_0",

    69             DocFile.createFileForOutput(configuration, filename).getPath());

    70     }

    72     /**

    73      * Accessor for configuration.

    74      */

    75     public abstract Configuration configuration();

    77     public Content getHyperLink(DocPath link, String label) {

    78         return getHyperLink(link, new StringContent(label), false, "", "", "");

    79     }

    81     /**

    82      * Get Html Hyper Link Content.

    83      *

    84      * @param where      Position of the link in the file. Character '#' is not

    85      *                   needed.

    86      * @param label      Tag for the link.

    87      * @return a content tree for the hyper link

    88      */

    89     public Content getHyperLink(String where,

    90                                Content label) {

    91         return getHyperLink(getDocLink(where), label, "", "");

    92     }

    94     /**

    95      * Get Html Hyper Link Content.

    96      *

    97      * @param sectionName      The section name to which the link will be created.

    98      * @param label            Tag for the link.

    99      * @return a content tree for the hyper link

   100      */

   101     public Content getHyperLink(SectionName sectionName,

   102                                Content label) {

   103         return getHyperLink(getDocLink(sectionName), label, "", "");

   104     }

   106     /**

   107      * Get Html Hyper Link Content.

   108      *

   109      * @param sectionName      The section name combined with where to which the link

   110      *                         will be created.

   111      * @param where            The fragment combined with sectionName to which the link

   112      *                         will be created.

   113      * @param label            Tag for the link.

   114      * @return a content tree for the hyper link

   115      */

   116     public Content getHyperLink(SectionName sectionName, String where,

   117                                Content label) {

   118         return getHyperLink(getDocLink(sectionName, where), label, "", "");

   119     }

   121     /**

   122      * Get the link.

   123      *

   124      * @param where      Position of the link in the file.

   125      * @return a DocLink object for the hyper link

   126      */

   127     public DocLink getDocLink(String where) {

   128         return DocLink.fragment(getName(where));

   129     }

   131     /**

   132      * Get the link.

   133      *

   134      * @param sectionName      The section name to which the link will be created.

   135      * @return a DocLink object for the hyper link

   136      */

   137     public DocLink getDocLink(SectionName sectionName) {

   138         return DocLink.fragment(sectionName.getName());

   139     }

   141     /**

   142      * Get the link.

   143      *

   144      * @param sectionName      The section name combined with where to which the link

   145      *                         will be created.

   146      * @param where            The fragment combined with sectionName to which the link

   147      *                         will be created.

   148      * @return a DocLink object for the hyper link

   149      */

   150     public DocLink getDocLink(SectionName sectionName, String where) {

   151         return DocLink.fragment(sectionName.getName() + getName(where));

   152     }

   154     /**

   155      * Convert the name to a valid HTML name.

   156      *

   157      * @param name the name that needs to be converted to valid HTML name.

   158      * @return a valid HTML name string.

   159      */

   160     public String getName(String name) {

   161         StringBuilder sb = new StringBuilder();

   162         char ch;

   163         /* The HTML 4 spec at http://www.w3.org/TR/html4/types.html#h-6.2 mentions

   164          * that the name/id should begin with a letter followed by other valid characters.

   165          * The HTML 5 spec (draft) is more permissive on names/ids where the only restriction

   166          * is that it should be at least one character long and should not contain spaces.

   167          * The spec draft is @ http://www.w3.org/html/wg/drafts/html/master/dom.html#the-id-attribute.

   168          *

   169          * For HTML 4, we need to check for non-characters at the beginning of the name and

   170          * substitute it accordingly, "_" and "$" can appear at the beginning of a member name.

   171          * The method substitutes "$" with "Z:Z:D" and will prefix "_" with "Z:Z".

   172          */

   173         for (int i = 0; i < name.length(); i++) {

   174             ch = name.charAt(i);

   175             switch (ch) {

   176                 case '(':

   177                 case ')':

   178                 case '<':

   179                 case '>':

   180                 case ',':

   181                     sb.append('-');

   182                     break;

   183                 case ' ':

   184                 case '[':

   185                     break;

   186                 case ']':

   187                     sb.append(":A");

   188                     break;

   189                 // Any appearance of $ needs to be substituted with ":D" and not with hyphen

   190                 // since a field name "P$$ and a method P(), both valid member names, can end

   191                 // up as "P--". A member name beginning with $ needs to be substituted with

   192                 // "Z:Z:D".

   193                 case '$':

   194                     if (i == 0)

   195                         sb.append("Z:Z");

   196                     sb.append(":D");

   197                     break;

   198                 // A member name beginning with _ needs to be prefixed with "Z:Z" since valid anchor

   199                 // names can only begin with a letter.

   200                 case '_':

   201                     if (i == 0)

   202                         sb.append("Z:Z");

   203                     sb.append(ch);

   204                     break;

   205                 default:

   206                     sb.append(ch);

   207             }

   208         }

   209         return sb.toString();

   210     }

   212     /**

   213      * Get Html hyperlink.

   214      *

   215      * @param link       path of the file.

   216      * @param label      Tag for the link.

   217      * @return a content tree for the hyper link

   218      */

   219     public Content getHyperLink(DocPath link, Content label) {

   220         return getHyperLink(link, label, "", "");

   221     }

   223     public Content getHyperLink(DocLink link, Content label) {

   224         return getHyperLink(link, label, "", "");

   225     }

   227     public Content getHyperLink(DocPath link,

   228                                Content label, boolean strong,

   229                                String stylename, String title, String target) {

   230         return getHyperLink(new DocLink(link), label, strong,

   231                 stylename, title, target);

   232     }

   234     public Content getHyperLink(DocLink link,

   235                                Content label, boolean strong,

   236                                String stylename, String title, String target) {

   237         Content body = label;

   238         if (strong) {

   239             body = HtmlTree.SPAN(HtmlStyle.typeNameLink, body);

   240         }

   241         if (stylename != null && stylename.length() != 0) {

   242             HtmlTree t = new HtmlTree(HtmlTag.FONT, body);

   243             t.addAttr(HtmlAttr.CLASS, stylename);

   244             body = t;

   245         }

   246         HtmlTree l = HtmlTree.A(link.toString(), body);

   247         if (title != null && title.length() != 0) {

   248             l.addAttr(HtmlAttr.TITLE, title);

   249         }

   250         if (target != null && target.length() != 0) {

   251             l.addAttr(HtmlAttr.TARGET, target);

   252         }

   253         return l;

   254     }

   256     /**

   257      * Get Html Hyper Link.

   258      *

   259      * @param link       String name of the file.

   260      * @param label      Tag for the link.

   261      * @param title      String that describes the link's content for accessibility.

   262      * @param target     Target frame.

   263      * @return a content tree for the hyper link.

   264      */

   265     public Content getHyperLink(DocPath link,

   266             Content label, String title, String target) {

   267         return getHyperLink(new DocLink(link), label, title, target);

   268     }

   270     public Content getHyperLink(DocLink link,

   271             Content label, String title, String target) {

   272         HtmlTree anchor = HtmlTree.A(link.toString(), label);

   273         if (title != null && title.length() != 0) {

   274             anchor.addAttr(HtmlAttr.TITLE, title);

   275         }

   276         if (target != null && target.length() != 0) {

   277             anchor.addAttr(HtmlAttr.TARGET, target);

   278         }

   279         return anchor;

   280     }

   282     /**

   283      * Get the name of the package, this class is in.

   284      *

   285      * @param cd    ClassDoc.

   286      */

   287     public String getPkgName(ClassDoc cd) {

   288         String pkgName = cd.containingPackage().name();

   289         if (pkgName.length() > 0) {

   290             pkgName += ".";

   291             return pkgName;

   292         }

   293         return "";

   294     }

   296     public boolean getMemberDetailsListPrinted() {

   297         return memberDetailsListPrinted;

   298     }

   300     /**

   301      * Print the frameset version of the Html file header.

   302      * Called only when generating an HTML frameset file.

   303      *

   304      * @param title Title of this HTML document

   305      * @param noTimeStamp If true, don't print time stamp in header

   306      * @param frameset the frameset to be added to the HTML document

   307      */

   308     public void printFramesetDocument(String title, boolean noTimeStamp,

   309             Content frameset) throws IOException {

   310         Content htmlDocType = DocType.FRAMESET;

   311         Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));

   312         Content head = new HtmlTree(HtmlTag.HEAD);

   313         head.addContent(getGeneratedBy(!noTimeStamp));

   314         if (configuration.charset.length() > 0) {

   315             Content meta = HtmlTree.META("Content-Type", CONTENT_TYPE,

   316                     configuration.charset);

   317             head.addContent(meta);

   318         }

   319         Content windowTitle = HtmlTree.TITLE(new StringContent(title));

   320         head.addContent(windowTitle);

   321         head.addContent(getFramesetJavaScript());

   322         Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),

   323                 head, frameset);

   324         Content htmlDocument = new HtmlDocument(htmlDocType,

   325                 htmlComment, htmlTree);

   326         write(htmlDocument);

   327     }

   329     protected Comment getGeneratedBy(boolean timestamp) {

   330         String text = "Generated by javadoc"; // marker string, deliberately not localized

   331         if (timestamp) {

   332             Calendar calendar = new GregorianCalendar(TimeZone.getDefault());

   333             Date today = calendar.getTime();

   334             text += " ("+ configuration.getDocletSpecificBuildDate() + ") on " + today;

   335         }

   336         return new Comment(text);

   337     }

   338 }

Mercurial > jdk8-mips64-public > langtools / file revision

src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java@6f0746b6de9f

src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java