1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,338 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclets.formats.html.markup;
1.30 +
1.31 +import java.io.*;
1.32 +import java.util.*;
1.33 +
1.34 +import com.sun.javadoc.*;
1.35 +import com.sun.tools.doclets.formats.html.ConfigurationImpl;
1.36 +import com.sun.tools.doclets.formats.html.SectionName;
1.37 +import com.sun.tools.doclets.internal.toolkit.*;
1.38 +import com.sun.tools.doclets.internal.toolkit.util.DocFile;
1.39 +import com.sun.tools.doclets.internal.toolkit.util.DocLink;
1.40 +import com.sun.tools.doclets.internal.toolkit.util.DocPath;
1.41 +
1.42 +
1.43 +/**
1.44 + * Class for the Html Format Code Generation specific to JavaDoc.
1.45 + * This Class contains methods related to the Html Code Generation which
1.46 + * are used by the Sub-Classes in the package com.sun.tools.doclets.standard
1.47 + * and com.sun.tools.doclets.oneone.
1.48 + *
1.49 + * <p><b>This is NOT part of any supported API.
1.50 + * If you write code that depends on this, you do so at your own risk.
1.51 + * This code and its internal interfaces are subject to change or
1.52 + * deletion without notice.</b>
1.53 + *
1.54 + * @since 1.2
1.55 + * @author Atul M Dambalkar
1.56 + * @author Robert Field
1.57 + */
1.58 +public abstract class HtmlDocWriter extends HtmlWriter {
1.59 +
1.60 + public static final String CONTENT_TYPE = "text/html";
1.61 +
1.62 + /**
1.63 + * Constructor. Initializes the destination file name through the super
1.64 + * class HtmlWriter.
1.65 + *
1.66 + * @param filename String file name.
1.67 + */
1.68 + public HtmlDocWriter(Configuration configuration, DocPath filename)
1.69 + throws IOException {
1.70 + super(configuration, filename);
1.71 + configuration.message.notice("doclet.Generating_0",
1.72 + DocFile.createFileForOutput(configuration, filename).getPath());
1.73 + }
1.74 +
1.75 + /**
1.76 + * Accessor for configuration.
1.77 + */
1.78 + public abstract Configuration configuration();
1.79 +
1.80 + public Content getHyperLink(DocPath link, String label) {
1.81 + return getHyperLink(link, new StringContent(label), false, "", "", "");
1.82 + }
1.83 +
1.84 + /**
1.85 + * Get Html Hyper Link Content.
1.86 + *
1.87 + * @param where Position of the link in the file. Character '#' is not
1.88 + * needed.
1.89 + * @param label Tag for the link.
1.90 + * @return a content tree for the hyper link
1.91 + */
1.92 + public Content getHyperLink(String where,
1.93 + Content label) {
1.94 + return getHyperLink(getDocLink(where), label, "", "");
1.95 + }
1.96 +
1.97 + /**
1.98 + * Get Html Hyper Link Content.
1.99 + *
1.100 + * @param sectionName The section name to which the link will be created.
1.101 + * @param label Tag for the link.
1.102 + * @return a content tree for the hyper link
1.103 + */
1.104 + public Content getHyperLink(SectionName sectionName,
1.105 + Content label) {
1.106 + return getHyperLink(getDocLink(sectionName), label, "", "");
1.107 + }
1.108 +
1.109 + /**
1.110 + * Get Html Hyper Link Content.
1.111 + *
1.112 + * @param sectionName The section name combined with where to which the link
1.113 + * will be created.
1.114 + * @param where The fragment combined with sectionName to which the link
1.115 + * will be created.
1.116 + * @param label Tag for the link.
1.117 + * @return a content tree for the hyper link
1.118 + */
1.119 + public Content getHyperLink(SectionName sectionName, String where,
1.120 + Content label) {
1.121 + return getHyperLink(getDocLink(sectionName, where), label, "", "");
1.122 + }
1.123 +
1.124 + /**
1.125 + * Get the link.
1.126 + *
1.127 + * @param where Position of the link in the file.
1.128 + * @return a DocLink object for the hyper link
1.129 + */
1.130 + public DocLink getDocLink(String where) {
1.131 + return DocLink.fragment(getName(where));
1.132 + }
1.133 +
1.134 + /**
1.135 + * Get the link.
1.136 + *
1.137 + * @param sectionName The section name to which the link will be created.
1.138 + * @return a DocLink object for the hyper link
1.139 + */
1.140 + public DocLink getDocLink(SectionName sectionName) {
1.141 + return DocLink.fragment(sectionName.getName());
1.142 + }
1.143 +
1.144 + /**
1.145 + * Get the link.
1.146 + *
1.147 + * @param sectionName The section name combined with where to which the link
1.148 + * will be created.
1.149 + * @param where The fragment combined with sectionName to which the link
1.150 + * will be created.
1.151 + * @return a DocLink object for the hyper link
1.152 + */
1.153 + public DocLink getDocLink(SectionName sectionName, String where) {
1.154 + return DocLink.fragment(sectionName.getName() + getName(where));
1.155 + }
1.156 +
1.157 + /**
1.158 + * Convert the name to a valid HTML name.
1.159 + *
1.160 + * @param name the name that needs to be converted to valid HTML name.
1.161 + * @return a valid HTML name string.
1.162 + */
1.163 + public String getName(String name) {
1.164 + StringBuilder sb = new StringBuilder();
1.165 + char ch;
1.166 + /* The HTML 4 spec at http://www.w3.org/TR/html4/types.html#h-6.2 mentions
1.167 + * that the name/id should begin with a letter followed by other valid characters.
1.168 + * The HTML 5 spec (draft) is more permissive on names/ids where the only restriction
1.169 + * is that it should be at least one character long and should not contain spaces.
1.170 + * The spec draft is @ http://www.w3.org/html/wg/drafts/html/master/dom.html#the-id-attribute.
1.171 + *
1.172 + * For HTML 4, we need to check for non-characters at the beginning of the name and
1.173 + * substitute it accordingly, "_" and "$" can appear at the beginning of a member name.
1.174 + * The method substitutes "$" with "Z:Z:D" and will prefix "_" with "Z:Z".
1.175 + */
1.176 + for (int i = 0; i < name.length(); i++) {
1.177 + ch = name.charAt(i);
1.178 + switch (ch) {
1.179 + case '(':
1.180 + case ')':
1.181 + case '<':
1.182 + case '>':
1.183 + case ',':
1.184 + sb.append('-');
1.185 + break;
1.186 + case ' ':
1.187 + case '[':
1.188 + break;
1.189 + case ']':
1.190 + sb.append(":A");
1.191 + break;
1.192 + // Any appearance of $ needs to be substituted with ":D" and not with hyphen
1.193 + // since a field name "P$$ and a method P(), both valid member names, can end
1.194 + // up as "P--". A member name beginning with $ needs to be substituted with
1.195 + // "Z:Z:D".
1.196 + case '$':
1.197 + if (i == 0)
1.198 + sb.append("Z:Z");
1.199 + sb.append(":D");
1.200 + break;
1.201 + // A member name beginning with _ needs to be prefixed with "Z:Z" since valid anchor
1.202 + // names can only begin with a letter.
1.203 + case '_':
1.204 + if (i == 0)
1.205 + sb.append("Z:Z");
1.206 + sb.append(ch);
1.207 + break;
1.208 + default:
1.209 + sb.append(ch);
1.210 + }
1.211 + }
1.212 + return sb.toString();
1.213 + }
1.214 +
1.215 + /**
1.216 + * Get Html hyperlink.
1.217 + *
1.218 + * @param link path of the file.
1.219 + * @param label Tag for the link.
1.220 + * @return a content tree for the hyper link
1.221 + */
1.222 + public Content getHyperLink(DocPath link, Content label) {
1.223 + return getHyperLink(link, label, "", "");
1.224 + }
1.225 +
1.226 + public Content getHyperLink(DocLink link, Content label) {
1.227 + return getHyperLink(link, label, "", "");
1.228 + }
1.229 +
1.230 + public Content getHyperLink(DocPath link,
1.231 + Content label, boolean strong,
1.232 + String stylename, String title, String target) {
1.233 + return getHyperLink(new DocLink(link), label, strong,
1.234 + stylename, title, target);
1.235 + }
1.236 +
1.237 + public Content getHyperLink(DocLink link,
1.238 + Content label, boolean strong,
1.239 + String stylename, String title, String target) {
1.240 + Content body = label;
1.241 + if (strong) {
1.242 + body = HtmlTree.SPAN(HtmlStyle.typeNameLink, body);
1.243 + }
1.244 + if (stylename != null && stylename.length() != 0) {
1.245 + HtmlTree t = new HtmlTree(HtmlTag.FONT, body);
1.246 + t.addAttr(HtmlAttr.CLASS, stylename);
1.247 + body = t;
1.248 + }
1.249 + HtmlTree l = HtmlTree.A(link.toString(), body);
1.250 + if (title != null && title.length() != 0) {
1.251 + l.addAttr(HtmlAttr.TITLE, title);
1.252 + }
1.253 + if (target != null && target.length() != 0) {
1.254 + l.addAttr(HtmlAttr.TARGET, target);
1.255 + }
1.256 + return l;
1.257 + }
1.258 +
1.259 + /**
1.260 + * Get Html Hyper Link.
1.261 + *
1.262 + * @param link String name of the file.
1.263 + * @param label Tag for the link.
1.264 + * @param title String that describes the link's content for accessibility.
1.265 + * @param target Target frame.
1.266 + * @return a content tree for the hyper link.
1.267 + */
1.268 + public Content getHyperLink(DocPath link,
1.269 + Content label, String title, String target) {
1.270 + return getHyperLink(new DocLink(link), label, title, target);
1.271 + }
1.272 +
1.273 + public Content getHyperLink(DocLink link,
1.274 + Content label, String title, String target) {
1.275 + HtmlTree anchor = HtmlTree.A(link.toString(), label);
1.276 + if (title != null && title.length() != 0) {
1.277 + anchor.addAttr(HtmlAttr.TITLE, title);
1.278 + }
1.279 + if (target != null && target.length() != 0) {
1.280 + anchor.addAttr(HtmlAttr.TARGET, target);
1.281 + }
1.282 + return anchor;
1.283 + }
1.284 +
1.285 + /**
1.286 + * Get the name of the package, this class is in.
1.287 + *
1.288 + * @param cd ClassDoc.
1.289 + */
1.290 + public String getPkgName(ClassDoc cd) {
1.291 + String pkgName = cd.containingPackage().name();
1.292 + if (pkgName.length() > 0) {
1.293 + pkgName += ".";
1.294 + return pkgName;
1.295 + }
1.296 + return "";
1.297 + }
1.298 +
1.299 + public boolean getMemberDetailsListPrinted() {
1.300 + return memberDetailsListPrinted;
1.301 + }
1.302 +
1.303 + /**
1.304 + * Print the frameset version of the Html file header.
1.305 + * Called only when generating an HTML frameset file.
1.306 + *
1.307 + * @param title Title of this HTML document
1.308 + * @param noTimeStamp If true, don't print time stamp in header
1.309 + * @param frameset the frameset to be added to the HTML document
1.310 + */
1.311 + public void printFramesetDocument(String title, boolean noTimeStamp,
1.312 + Content frameset) throws IOException {
1.313 + Content htmlDocType = DocType.FRAMESET;
1.314 + Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
1.315 + Content head = new HtmlTree(HtmlTag.HEAD);
1.316 + head.addContent(getGeneratedBy(!noTimeStamp));
1.317 + if (configuration.charset.length() > 0) {
1.318 + Content meta = HtmlTree.META("Content-Type", CONTENT_TYPE,
1.319 + configuration.charset);
1.320 + head.addContent(meta);
1.321 + }
1.322 + Content windowTitle = HtmlTree.TITLE(new StringContent(title));
1.323 + head.addContent(windowTitle);
1.324 + head.addContent(getFramesetJavaScript());
1.325 + Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
1.326 + head, frameset);
1.327 + Content htmlDocument = new HtmlDocument(htmlDocType,
1.328 + htmlComment, htmlTree);
1.329 + write(htmlDocument);
1.330 + }
1.331 +
1.332 + protected Comment getGeneratedBy(boolean timestamp) {
1.333 + String text = "Generated by javadoc"; // marker string, deliberately not localized
1.334 + if (timestamp) {
1.335 + Calendar calendar = new GregorianCalendar(TimeZone.getDefault());
1.336 + Date today = calendar.getTime();
1.337 + text += " ("+ configuration.getDocletSpecificBuildDate() + ") on " + today;
1.338 + }
1.339 + return new Comment(text);
1.340 + }
1.341 +}
