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