1 /*
2 * Copyright (c) 1998, 2017, 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.toolkit.util;
27
28 import javax.lang.model.element.ModuleElement;
29 import javax.lang.model.element.PackageElement;
30 import javax.lang.model.element.TypeElement;
31
32 /**
33 * Standard DocPath objects.
34 *
35 * <p><b>This is NOT part of any supported API.
36 * If you write code that depends on this, you do so at your own risk.
37 * This code and its internal interfaces are subject to change or
38 * deletion without notice.</b>
39 *
40 */
41 public class DocPaths {
42 private final boolean useModuleDirectories;
43 private final String moduleSeparator;
44 private final Utils utils;
45
46 public DocPaths(Utils utils, boolean useModuleDirectories) {
47 this.utils = utils;
48 this.useModuleDirectories = useModuleDirectories;
49 moduleSeparator = useModuleDirectories ? "/module-" : "-";
50 }
51
52 /** The name of the file for all classes, without using frames, when --no-frames is specified. */
53 public static final DocPath ALLCLASSES = DocPath.create("allclasses.html");
54
55 /** The name of the file for all classes, using frames. */
56 public static final DocPath ALLCLASSES_FRAME = DocPath.create("allclasses-frame.html");
57
58 /** The name of the file for all classes, without using frames. */
59 public static final DocPath ALLCLASSES_NOFRAME = DocPath.create("allclasses-noframe.html");
60
61 public static DocPath AllClasses(boolean frames) {
62 return frames ? ALLCLASSES_NOFRAME : ALLCLASSES;
63 }
64
65 /** The name of the sub-directory for storing class usage info. */
66 public static final DocPath CLASS_USE = DocPath.create("class-use");
67
68 /** The name of the file for constant values. */
69 public static final DocPath CONSTANT_VALUES = DocPath.create("constant-values.html");
70
71 /** The name of the fie for deprecated elements. */
72 public static final DocPath DEPRECATED_LIST = DocPath.create("deprecated-list.html");
73
74 /** The name of the subdirectory for user-provided additional documentation files. */
75 public static final DocPath DOC_FILES = DocPath.create("doc-files");
76
77 /** The name of the file for the element list. */
78 public static final DocPath ELEMENT_LIST = DocPath.create("element-list");
79
80 /** The name of the image file showing a magnifying glass on the search box. */
81 public static final DocPath GLASS_IMG = DocPath.create("glass.png");
82
83 /** The name of the file for help info. */
84 public static final DocPath HELP_DOC = DocPath.create("help-doc.html");
85
86 /** The name of the main index file. */
87 public static final DocPath INDEX = DocPath.create("index.html");
88
89 /** The name of the single index file for all classes. */
90 public static final DocPath INDEX_ALL = DocPath.create("index-all.html");
91
92 /** The name of the directory for the split index files. */
93 public static final DocPath INDEX_FILES = DocPath.create("index-files");
94
95 /**
96 * Generate the name of one of the files in the split index.
97 * @param n the position in the index
98 * @return the path
99 */
100 public static DocPath indexN(int n) {
101 return DocPath.create("index-" + n + ".html");
102 }
103
104 /** The name of the default javascript file. */
105 public static final DocPath JAVASCRIPT = DocPath.create("script.js");
106
107 /** The name of the directory for the jQuery. */
108 public static final DocPath JQUERY_FILES = DocPath.create("jquery");
109
110 /** The name of the default jQuery stylesheet file. */
111 public static final DocPath JQUERY_STYLESHEET_FILE = DocPath.create("jquery-ui.css");
112
113 /** The name of the default jQuery javascript file. */
114 public static final DocPath JQUERY_JS_1_10 = DocPath.create("jquery-1.10.2.js");
115
116 /** The name of the default jQuery javascript file. */
117 public static final DocPath JQUERY_JS = DocPath.create("jquery-ui.js");
118
119 /** The name of the default jszip javascript file. */
120 public static final DocPath JSZIP = DocPath.create("jszip/dist/jszip.js");
121
122 /** The name of the default jszip javascript file. */
123 public static final DocPath JSZIP_MIN = DocPath.create("jszip/dist/jszip.min.js");
124
125 /** The name of the default jszip-utils javascript file. */
126 public static final DocPath JSZIPUTILS = DocPath.create("jszip-utils/dist/jszip-utils.js");
127
128 /** The name of the default jszip-utils javascript file. */
129 public static final DocPath JSZIPUTILS_MIN = DocPath.create("jszip-utils/dist/jszip-utils.min.js");
130
131 /** The name of the default jszip-utils javascript file. */
132 public static final DocPath JSZIPUTILS_IE = DocPath.create("jszip-utils/dist/jszip-utils-ie.js");
133
134 /** The name of the default jszip-utils javascript file. */
135 public static final DocPath JSZIPUTILS_IE_MIN = DocPath.create("jszip-utils/dist/jszip-utils-ie.min.js");
136
137 /** The name of the member search index file. */
138 public static final DocPath MEMBER_SEARCH_INDEX_JSON = DocPath.create("member-search-index.json");
139
140 /** The name of the member search index zip file. */
141 public static final DocPath MEMBER_SEARCH_INDEX_ZIP = DocPath.create("member-search-index.zip");
142
143 /** The name of the member search index js file. */
144 public static final DocPath MEMBER_SEARCH_INDEX_JS = DocPath.create("member-search-index.js");
145
146 /** The name of the module search index file. */
147 public static final DocPath MODULE_SEARCH_INDEX_JSON = DocPath.create("module-search-index.json");
148
149 /** The name of the module search index zip file. */
150 public static final DocPath MODULE_SEARCH_INDEX_ZIP = DocPath.create("module-search-index.zip");
151
152 /** The name of the module search index js file. */
153 public static final DocPath MODULE_SEARCH_INDEX_JS = DocPath.create("module-search-index.js");
154
155 /** The name of the file for the overview frame. */
156 public static final DocPath OVERVIEW_FRAME = DocPath.create("overview-frame.html");
157
158 /** The name of the file for the overview summary. */
159 public static final DocPath OVERVIEW_SUMMARY = DocPath.create("overview-summary.html");
160
161 public static DocPath overviewSummary(boolean frames) {
162 return frames ? OVERVIEW_SUMMARY : INDEX;
163 }
164
165 /** The name of the file for the overview tree. */
166 public static final DocPath OVERVIEW_TREE = DocPath.create("overview-tree.html");
167
168 /** The name of the file for the package frame. */
169 public static final DocPath PACKAGE_FRAME = DocPath.create("package-frame.html");
170
171 /** The name of the file for the package list. This is to support the legacy mode. */
172 public static final DocPath PACKAGE_LIST = DocPath.create("package-list");
173
174 /** The name of the package search index file. */
175 public static final DocPath PACKAGE_SEARCH_INDEX_JSON = DocPath.create("package-search-index.json");
176
177 /** The name of the package search index zip file. */
178 public static final DocPath PACKAGE_SEARCH_INDEX_ZIP = DocPath.create("package-search-index.zip");
179
180 /** The name of the package search index js file. */
181 public static final DocPath PACKAGE_SEARCH_INDEX_JS = DocPath.create("package-search-index.js");
182
183 /** The name of the file for the package summary. */
184 public static final DocPath PACKAGE_SUMMARY = DocPath.create("package-summary.html");
185
186 /** The name of the file for the package tree. */
187 public static final DocPath PACKAGE_TREE = DocPath.create("package-tree.html");
188
189 /** The name of the file for the package usage info. */
190 public static final DocPath PACKAGE_USE = DocPath.create("package-use.html");
191
192 /**
193 * Returns the path for a type element.
194 * For example, if the type element is {@code java.lang.Object},
195 * the path is {@code java/lang/Object.html}.
196 *
197 * @param typeElement the type element
198 * @return the path
199 */
200 public DocPath forClass(TypeElement typeElement) {
201 return (typeElement == null)
202 ? DocPath.empty
203 : forPackage(utils.containingPackage(typeElement)).resolve(forName(typeElement));
204 }
205
206 /**
207 * Returns the path for the simple name of a type element.
208 * For example, if the type element is {@code java.lang.Object},
209 * the path is {@code Object.html}.
210 *
211 * @param typeElement the type element
212 * @return the path
213 */
214 public DocPath forName(TypeElement typeElement) {
215 return (typeElement == null)
216 ? DocPath.empty
217 : new DocPath(utils.getSimpleName(typeElement) + ".html");
218 }
219
220 public static DocPath forModule(ModuleElement mdle) {
221 return mdle == null || mdle.isUnnamed()
222 ? DocPath.empty
223 : DocPath.create(mdle.getQualifiedName().toString());
224 }
225
226 /**
227 * Returns the path for the package of a type element.
228 * For example, if the type element is {@code java.lang.Object},
229 * the path is {@code java/lang}.
230 *
231 * @param typeElement the type element
232 * @return the path
233 */
234 public DocPath forPackage(TypeElement typeElement) {
235 return (typeElement == null) ? DocPath.empty : forPackage(utils.containingPackage(typeElement));
236 }
237
238 /**
239 * Returns the path for a package.
240 * For example, if the package is {@code java.lang},
241 * the path is {@code java/lang}.
242 *
243 * @param pkgElement the package element
244 * @return the path
245 */
246 public DocPath forPackage(PackageElement pkgElement) {
247 if (pkgElement == null || pkgElement.isUnnamed()) {
248 return DocPath.empty;
249 }
250
251 DocPath pkgPath = DocPath.create(pkgElement.getQualifiedName().toString().replace('.', '/'));
252 if (useModuleDirectories) {
253 ModuleElement mdle = (ModuleElement) pkgElement.getEnclosingElement();
254 return forModule(mdle).resolve(pkgPath);
255 } else {
256 return pkgPath;
257 }
258 }
259
260 /**
261 * Returns the inverse path for a package.
262 * For example, if the package is {@code java.lang},
263 * the inverse path is {@code ../..}.
264 *
265 * @param pkgElement the package element
266 * @return the path
267 */
268 public static DocPath forRoot(PackageElement pkgElement) {
269 String name = (pkgElement == null || pkgElement.isUnnamed())
270 ? ""
271 : pkgElement.getQualifiedName().toString();
272 return new DocPath(name.replace('.', '/').replaceAll("[^/]+", ".."));
273 }
274
275 /**
276 * Returns a relative path from one package to another.
277 *
278 * @param from the origin of the relative path
279 * @param to the destination of the relative path
280 * @return the path
281 */
282 public DocPath relativePath(PackageElement from, PackageElement to) {
283 return forRoot(from).resolve(forPackage(to));
284 }
285
286 /**
287 * The path for the output directory for module documentation files.
288 * @param mdle the module
289 * @return the path
290 */
291 public DocPath moduleDocFiles(ModuleElement mdle) {
292 return createModulePath(mdle, "doc-files");
293 }
294
295 /**
296 * The path for the file for a module's frame page.
297 * @param mdle the module
298 * @return the path
299 */
300 public DocPath moduleFrame(ModuleElement mdle) {
301 return createModulePath(mdle, "frame.html");
302 }
303
304 /**
305 * The path for the file for a module's summary page.
306 * @param mdle the module
307 * @return the path
308 */
309 public DocPath moduleSummary(ModuleElement mdle) {
310 return createModulePath(mdle, "summary.html");
311 }
312
313 /**
314 * The path for the file for a module's summary page.
315 * @param mdleName the module
316 * @return the path
317 */
318 public DocPath moduleSummary(String mdleName) {
319 return createModulePath(mdleName, "summary.html");
320 }
321
322 /**
323 * The path for the file for a module's type frame page.
324 * @param mdle the module
325 * @return the path
326 */
327 public DocPath moduleTypeFrame(ModuleElement mdle) {
328 return createModulePath(mdle, "type-frame.html");
329 }
330
331 private DocPath createModulePath(ModuleElement mdle, String path) {
332 return DocPath.create(mdle.getQualifiedName() + moduleSeparator + path);
333 }
334
335 private DocPath createModulePath(String moduleName, String path) {
336 return DocPath.create(moduleName + moduleSeparator + path);
337 }
338
339 /** The name of the file for the module overview frame. */
340 public static final DocPath MODULE_OVERVIEW_FRAME = DocPath.create("module-overview-frame.html");
341
342 /** The name of the sub-package from which resources are read. */
343 public static final DocPath RESOURCES = DocPath.create("resources");
344
345 /** The name of the search javascript file. */
346 public static final DocPath SEARCH_JS = DocPath.create("search.js");
347
348 /** The name of the file for the serialized form info. */
349 public static final DocPath SERIALIZED_FORM = DocPath.create("serialized-form.html");
350
351 /** The name of the directory in which HTML versions of the source code
352 * are generated.
353 */
354 public static final DocPath SOURCE_OUTPUT = DocPath.create("src-html");
355
356 /** The name of the default stylesheet. */
357 public static final DocPath STYLESHEET = DocPath.create("stylesheet.css");
358
359 /** The name of the tag search index file. */
360 public static final DocPath TAG_SEARCH_INDEX_JSON = DocPath.create("tag-search-index.json");
361
362 /** The name of the tag search index zip file. */
363 public static final DocPath TAG_SEARCH_INDEX_ZIP = DocPath.create("tag-search-index.zip");
364
365 /** The name of the tag search index js file. */
366 public static final DocPath TAG_SEARCH_INDEX_JS = DocPath.create("tag-search-index.js");
367
368 /** The name of the type search index file. */
369 public static final DocPath TYPE_SEARCH_INDEX_JSON = DocPath.create("type-search-index.json");
370
371 /** The name of the type search index zip file. */
372 public static final DocPath TYPE_SEARCH_INDEX_ZIP = DocPath.create("type-search-index.zip");
373
374 /** The name of the type search index js file. */
375 public static final DocPath TYPE_SEARCH_INDEX_JS = DocPath.create("type-search-index.js");
376
377 /** The name of the image file for undo button on the search box. */
378 public static final DocPath X_IMG = DocPath.create("x.png");
379
380 }