1 /*
2 * Copyright (c) 1997, 2020, 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.ModuleElement;
31 import javax.lang.model.element.PackageElement;
32 import javax.lang.model.element.TypeElement;
33
34 import jdk.javadoc.doclet.Doclet;
35 import jdk.javadoc.doclet.DocletEnvironment;
36 import jdk.javadoc.doclet.Reporter;
37 import jdk.javadoc.internal.doclets.toolkit.AbstractDoclet;
38 import jdk.javadoc.internal.doclets.toolkit.DocletException;
39 import jdk.javadoc.internal.doclets.toolkit.Messages;
40 import jdk.javadoc.internal.doclets.toolkit.builders.AbstractBuilder;
41 import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
42 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
43 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
44 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
45 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
46 import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
47
48 /**
49 * The class with "start" method, calls individual Writers.
50 *
51 * <p><b>This is NOT part of any supported API.
52 * If you write code that depends on this, you do so at your own risk.
53 * This code and its internal interfaces are subject to change or
54 * deletion without notice.</b>
55 */
56 public class HtmlDoclet extends AbstractDoclet {
57
58 public HtmlDoclet(Doclet parent) {
59 configuration = new HtmlConfiguration(parent);
60 }
61
62 @Override // defined by Doclet
63 public String getName() {
64 return "Html";
65 }
66
67 /**
68 * The global configuration information for this run.
69 */
70 private final HtmlConfiguration configuration;
71
72 private Messages messages;
73
74
75 private static final DocPath DOCLET_RESOURCES = DocPath
76 .create("/jdk/javadoc/internal/doclets/formats/html/resources");
77
78 @Override // defined by Doclet
79 public void init(Locale locale, Reporter reporter) {
80 configuration.reporter = reporter;
81 configuration.locale = locale;
82 messages = configuration.getMessages();
83 }
84
85 /**
86 * Create the configuration instance.
87 * Override this method to use a different
88 * configuration.
89 *
90 * @return the configuration
91 */
92 @Override // defined by AbstractDoclet
93 public HtmlConfiguration getConfiguration() {
94 return configuration;
95 }
96
97 /**
98 * Start the generation of files. Call generate methods in the individual
99 * writers, which will in turn generate the documentation files. Call the
100 * TreeWriter generation first to ensure the Class Hierarchy is built
101 * first and then can be used in the later generation.
102 *
103 * For new format.
104 *
105 * @throws DocletException if there is a problem while writing the other files
106 */
107 @Override // defined by AbstractDoclet
108 protected void generateOtherFiles(DocletEnvironment docEnv, ClassTree classtree)
109 throws DocletException {
110 super.generateOtherFiles(docEnv, classtree);
111 HtmlOptions options = configuration.getOptions();
112 if (options.linkSource()) {
113 SourceToHTMLConverter.convertRoot(configuration,
114 docEnv, DocPaths.SOURCE_OUTPUT);
115 }
116 // Modules with no documented classes may be specified on the
117 // command line to specify a service provider, allow these.
118 if (configuration.getSpecifiedModuleElements().isEmpty() &&
119 configuration.topFile.isEmpty()) {
120 messages.error("doclet.No_Non_Deprecated_Classes_To_Document");
121 return;
122 }
123 boolean nodeprecated = options.noDeprecated();
124 performCopy(options.helpFile());
125 performCopy(options.stylesheetFile());
126 for (String stylesheet : options.additionalStylesheets()) {
127 performCopy(stylesheet);
128 }
129 // do early to reduce memory footprint
130 if (options.classUse()) {
131 ClassUseWriter.generate(configuration, classtree);
132 }
133 IndexBuilder indexbuilder = new IndexBuilder(configuration, nodeprecated);
134
135 if (options.createTree()) {
136 TreeWriter.generate(configuration, classtree);
137 }
138
139 if (!(options.noDeprecatedList() || nodeprecated)) {
140 DeprecatedListWriter.generate(configuration);
141 }
142
143 if (options.createOverview()) {
144 if (configuration.showModules) {
145 ModuleIndexWriter.generate(configuration);
146 } else {
147 PackageIndexWriter.generate(configuration);
148 }
149 }
150
151 if (options.createIndex()) {
152 configuration.buildSearchTagIndex();
153 if (options.splitIndex()) {
154 SplitIndexWriter.generate(configuration, indexbuilder);
155 } else {
156 SingleIndexWriter.generate(configuration, indexbuilder);
157 }
158 AllClassesIndexWriter.generate(configuration,
159 new IndexBuilder(configuration, nodeprecated, true));
160 if (!configuration.packages.isEmpty()) {
161 AllPackagesIndexWriter.generate(configuration);
162 }
163 SystemPropertiesWriter.generate(configuration);
164 }
165
166 if (options.createOverview()) {
167 IndexRedirectWriter.generate(configuration, DocPaths.OVERVIEW_SUMMARY, DocPaths.INDEX);
168 } else {
169 IndexRedirectWriter.generate(configuration);
170 }
171
172 if (options.helpFile().isEmpty() && !options.noHelp()) {
173 HelpWriter.generate(configuration);
174 }
175 // If a stylesheet file is not specified, copy the default stylesheet
176 // and replace newline with platform-specific newline.
177 DocFile f;
178 if (options.stylesheetFile().length() == 0) {
179 f = DocFile.createFileForOutput(configuration, DocPaths.STYLESHEET);
180 f.copyResource(DocPaths.RESOURCES.resolve(DocPaths.STYLESHEET), true, true);
181 }
182 f = DocFile.createFileForOutput(configuration, DocPaths.JAVASCRIPT);
183 f.copyResource(DocPaths.RESOURCES.resolve(DocPaths.JAVASCRIPT), true, true);
184 if (options.createIndex()) {
185 f = DocFile.createFileForOutput(configuration, DocPaths.SEARCH_JS);
186 f.copyResource(DOCLET_RESOURCES.resolve(DocPaths.SEARCH_JS), true, true);
187
188 f = DocFile.createFileForOutput(configuration, DocPaths.RESOURCES.resolve(DocPaths.GLASS_IMG));
189 f.copyResource(DOCLET_RESOURCES.resolve(DocPaths.GLASS_IMG), true, false);
190
191 f = DocFile.createFileForOutput(configuration, DocPaths.RESOURCES.resolve(DocPaths.X_IMG));
192 f.copyResource(DOCLET_RESOURCES.resolve(DocPaths.X_IMG), true, false);
193 copyJqueryFiles();
194 }
195 }
196
197 private void copyJqueryFiles() throws DocletException {
198 List<String> files = Arrays.asList(
199 "jquery-3.4.1.js",
200 "jquery-ui.js",
201 "jquery-ui.css",
202 "jquery-ui.min.js",
203 "jquery-ui.min.css",
204 "jquery-ui.structure.min.css",
205 "jquery-ui.structure.css",
206 "external/jquery/jquery.js",
207 "jszip/dist/jszip.js",
208 "jszip/dist/jszip.min.js",
209 "jszip-utils/dist/jszip-utils.js",
210 "jszip-utils/dist/jszip-utils.min.js",
211 "jszip-utils/dist/jszip-utils-ie.js",
212 "jszip-utils/dist/jszip-utils-ie.min.js",
213 "images/ui-bg_glass_65_dadada_1x400.png",
214 "images/ui-icons_454545_256x240.png",
215 "images/ui-bg_glass_95_fef1ec_1x400.png",
216 "images/ui-bg_glass_75_dadada_1x400.png",
217 "images/ui-bg_highlight-soft_75_cccccc_1x100.png",
218 "images/ui-icons_888888_256x240.png",
219 "images/ui-icons_2e83ff_256x240.png",
220 "images/ui-icons_cd0a0a_256x240.png",
221 "images/ui-bg_glass_55_fbf9ee_1x400.png",
222 "images/ui-icons_222222_256x240.png",
223 "images/ui-bg_glass_75_e6e6e6_1x400.png");
224 DocFile f;
225 for (String file : files) {
226 DocPath filePath = DocPaths.JQUERY_FILES.resolve(file);
227 f = DocFile.createFileForOutput(configuration, filePath);
228 f.copyResource(DOCLET_RESOURCES.resolve(filePath), true, false);
229 }
230 }
231
232 /**
233 * {@inheritDoc}
234 */
235 @Override // defined by AbstractDoclet
236 protected void generateClassFiles(SortedSet<TypeElement> typeElems, ClassTree classTree)
237 throws DocletException {
238 for (TypeElement te : typeElems) {
239 if (utils.hasHiddenTag(te) ||
240 !(configuration.isGeneratedDoc(te) && utils.isIncluded(te))) {
241 continue;
242 }
243 if (utils.isAnnotationType(te)) {
244 AbstractBuilder annotationTypeBuilder =
245 configuration.getBuilderFactory()
246 .getAnnotationTypeBuilder(te);
247 annotationTypeBuilder.build();
248 } else {
249 AbstractBuilder classBuilder =
250 configuration.getBuilderFactory().getClassBuilder(te, classTree);
251 classBuilder.build();
252 }
253 }
254 }
255
256 /**
257 * {@inheritDoc}
258 */
259 @Override // defined by AbstractDoclet
260 protected void generateModuleFiles() throws DocletException {
261 if (configuration.showModules) {
262 List<ModuleElement> mdles = new ArrayList<>(configuration.modulePackages.keySet());
263 for (ModuleElement mdle : mdles) {
264 AbstractBuilder moduleSummaryBuilder =
265 configuration.getBuilderFactory().getModuleSummaryBuilder(mdle);
266 moduleSummaryBuilder.build();
267 }
268 }
269 }
270
271 /**
272 * {@inheritDoc}
273 */
274 @Override // defined by AbstractDoclet
275 protected void generatePackageFiles(ClassTree classtree) throws DocletException {
276 HtmlOptions options = configuration.getOptions();
277 Set<PackageElement> packages = configuration.packages;
278 List<PackageElement> pList = new ArrayList<>(packages);
279 for (PackageElement pkg : pList) {
280 // if -nodeprecated option is set and the package is marked as
281 // deprecated, do not generate the package-summary.html, package-frame.html
282 // and package-tree.html pages for that package.
283 if (!(options.noDeprecated() && utils.isDeprecated(pkg))) {
284 AbstractBuilder packageSummaryBuilder =
285 configuration.getBuilderFactory().getPackageSummaryBuilder(pkg);
286 packageSummaryBuilder.build();
287 if (options.createTree()) {
288 PackageTreeWriter.generate(configuration, pkg, options.noDeprecated());
289 }
290 }
291 }
292 }
293
294 @Override // defined by Doclet
295 public Set<? extends Option> getSupportedOptions() {
296 return configuration.getOptions().getSupportedOptions();
297 }
298
299 private void performCopy(String filename) throws DocFileIOException {
300 if (filename.isEmpty())
301 return;
302
303 DocFile fromfile = DocFile.createFileForInput(configuration, filename);
304 DocPath path = DocPath.create(fromfile.getName());
305 DocFile toFile = DocFile.createFileForOutput(configuration, path);
306 if (toFile.isSameFile(fromfile))
307 return;
308
309 messages.notice("doclet.Copying_File_0_To_File_1",
310 fromfile.toString(), path.getPath());
311 toFile.copyFile(fromfile);
312 }
313 }