1 /*

     2  * Copyright (c) 1998, 2014, 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 com.sun.tools.doclets.internal.toolkit.util;

    27 

    28 import java.io.*;

    29 import java.net.*;

    30 import java.util.HashMap;

    31 import java.util.Map;

    32 

    33 import javax.tools.DocumentationTool;

    34 

    35 import com.sun.javadoc.*;

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

    37 

    38 /**

    39  * Process and manage "-link" and "-linkoffline" to external packages. The

    40  * options "-link" and "-linkoffline" both depend on the fact that Javadoc now

    41  * generates "package-list"(lists all the packages which are getting

    42  * documented) file in the current or the destination directory, while

    43  * generating the documentation.

    44  *

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

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

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

    48  *  deletion without notice.</b>

    49  *

    50  * @author Atul M Dambalkar

    51  * @author Robert Field

    52  */

    53 public class Extern {

    54 

    55     /**

    56      * Map package names onto Extern Item objects.

    57      * Lazily initialized.

    58      */

    59     private Map<String,Item> packageToItemMap;

    60 

    61     /**

    62      * The global configuration information for this run.

    63      */

    64     private final Configuration configuration;

    65 

    66     /**

    67      * True if we are using -linkoffline and false if -link is used instead.

    68      */

    69     private boolean linkoffline = false;

    70 

    71     /**

    72      * Stores the info for one external doc set

    73      */

    74     private class Item {

    75 

    76         /**

    77          * Package name, found in the "package-list" file in the {@link path}.

    78          */

    79         final String packageName;

    80 

    81         /**

    82          * The URL or the directory path at which the package documentation will be

    83          * avaliable.

    84          */

    85         final String path;

    86 

    87         /**

    88          * If given path is directory path then true else if it is a URL then false.

    89          */

    90         final boolean relative;

    91 

    92         /**

    93          * Constructor to build a Extern Item object and map it with the package name.

    94          * If the same package name is found in the map, then the first mapped

    95          * Item object or offline location will be retained.

    96          *

    97          * @param packageName Package name found in the "package-list" file.

    98          * @param path        URL or Directory path from where the "package-list"

    99          * file is picked.

   100          * @param relative    True if path is URL, false if directory path.

   101          */

   102         Item(String packageName, String path, boolean relative) {

   103             this.packageName = packageName;

   104             this.path = path;

   105             this.relative = relative;

   106             if (packageToItemMap == null) {

   107                 packageToItemMap = new HashMap<>();

   108             }

   109             if (!packageToItemMap.containsKey(packageName)) { // save the previous

   110                 packageToItemMap.put(packageName, this);        // mapped location

   111             }

   112         }

   113 

   114         /**

   115          * String representation of "this" with packagename and the path.

   116          */

   117         public String toString() {

   118             return packageName + (relative? " -> " : " => ") + path;

   119         }

   120     }

   121 

   122     public Extern(Configuration configuration) {

   123         this.configuration = configuration;

   124     }

   125 

   126     /**

   127      * Determine if a doc item is externally documented.

   128      *

   129      * @param doc A ProgramElementDoc.

   130      */

   131     public boolean isExternal(ProgramElementDoc doc) {

   132         if (packageToItemMap == null) {

   133             return false;

   134         }

   135         return packageToItemMap.get(doc.containingPackage().name()) != null;

   136     }

   137 

   138     /**

   139      * Convert a link to be an external link if appropriate.

   140      *

   141      * @param pkgName The package name.

   142      * @param relativepath    The relative path.

   143      * @param filename    The link to convert.

   144      * @return if external return converted link else return null

   145      */

   146     public DocLink getExternalLink(String pkgName,

   147                                   DocPath relativepath, String filename) {

   148         return getExternalLink(pkgName, relativepath, filename, null);

   149     }

   150 

   151     public DocLink getExternalLink(String pkgName,

   152                                   DocPath relativepath, String filename, String memberName) {

   153         Item fnd = findPackageItem(pkgName);

   154         if (fnd == null)

   155             return null;

   156 

   157         DocPath p = fnd.relative ?

   158                 relativepath.resolve(fnd.path).resolve(filename) :

   159                 DocPath.create(fnd.path).resolve(filename);

   160 

   161         return new DocLink(p, "is-external=true", memberName);

   162     }

   163 

   164     /**

   165      * Build the extern package list from given URL or the directory path.

   166      * Flag error if the "-link" or "-linkoffline" option is already used.

   167      *

   168      * @param url        URL or Directory path.

   169      * @param pkglisturl This can be another URL for "package-list" or ordinary

   170      *                   file.

   171      * @param reporter   The <code>DocErrorReporter</code> used to report errors.

   172      * @param linkoffline True if -linkoffline is used and false if -link is used.

   173      */

   174     public boolean link(String url, String pkglisturl,

   175                               DocErrorReporter reporter, boolean linkoffline) {

   176         this.linkoffline = linkoffline;

   177         try {

   178             url = adjustEndFileSeparator(url);

   179             if (isUrl(pkglisturl)) {

   180                 readPackageListFromURL(url, toURL(adjustEndFileSeparator(pkglisturl)));

   181             } else {

   182                 readPackageListFromFile(url, DocFile.createFileForInput(configuration, pkglisturl));

   183             }

   184             return true;

   185         } catch (Fault f) {

   186             reporter.printWarning(f.getMessage());

   187             return false;

   188         }

   189     }

   190 

   191     private URL toURL(String url) throws Fault {

   192         try {

   193             return new URL(url);

   194         } catch (MalformedURLException e) {

   195             throw new Fault(configuration.getText("doclet.MalformedURL", url), e);

   196         }

   197     }

   198 

   199     private class Fault extends Exception {

   200         private static final long serialVersionUID = 0;

   201 

   202         Fault(String msg, Exception cause) {

   203             super(msg, cause);

   204         }

   205     }

   206 

   207     /**

   208      * Get the Extern Item object associated with this package name.

   209      *

   210      * @param pkgName Package name.

   211      */

   212     private Item findPackageItem(String pkgName) {

   213         if (packageToItemMap == null) {

   214             return null;

   215         }

   216         return packageToItemMap.get(pkgName);

   217     }

   218 

   219     /**

   220      * If the URL or Directory path is missing end file separator, add that.

   221      */

   222     private String adjustEndFileSeparator(String url) {

   223         return url.endsWith("/") ? url : url + '/';

   224     }

   225 

   226     /**

   227      * Fetch the URL and read the "package-list" file.

   228      *

   229      * @param urlpath        Path to the packages.

   230      * @param pkglisturlpath URL or the path to the "package-list" file.

   231      */

   232     private void readPackageListFromURL(String urlpath, URL pkglisturlpath)

   233             throws Fault {

   234         try {

   235             URL link = pkglisturlpath.toURI().resolve(DocPaths.PACKAGE_LIST.getPath()).toURL();

   236             readPackageList(link.openStream(), urlpath, false);

   237         } catch (URISyntaxException | MalformedURLException exc) {

   238             throw new Fault(configuration.getText("doclet.MalformedURL", pkglisturlpath.toString()), exc);

   239         }

   240         catch (IOException exc) {

   241             throw new Fault(configuration.getText("doclet.URL_error", pkglisturlpath.toString()), exc);

   242         }

   243     }

   244 

   245     /**

   246      * Read the "package-list" file which is available locally.

   247      *

   248      * @param path URL or directory path to the packages.

   249      * @param pkgListPath Path to the local "package-list" file.

   250      */

   251     private void readPackageListFromFile(String path, DocFile pkgListPath)

   252             throws Fault {

   253         DocFile file = pkgListPath.resolve(DocPaths.PACKAGE_LIST);

   254         if (! (file.isAbsolute() || linkoffline)){

   255             file = file.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT);

   256         }

   257         try {

   258             if (file.exists() && file.canRead()) {

   259                 boolean pathIsRelative =

   260                         !DocFile.createFileForInput(configuration, path).isAbsolute()

   261                         && !isUrl(path);

   262                 readPackageList(file.openInputStream(), path, pathIsRelative);

   263             } else {

   264                 throw new Fault(configuration.getText("doclet.File_error", file.getPath()), null);

   265             }

   266         } catch (IOException exc) {

   267            throw new Fault(configuration.getText("doclet.File_error", file.getPath()), exc);

   268         }

   269     }

   270 

   271     /**

   272      * Read the file "package-list" and for each package name found, create

   273      * Extern object and associate it with the package name in the map.

   274      *

   275      * @param input    InputStream from the "package-list" file.

   276      * @param path     URL or the directory path to the packages.

   277      * @param relative Is path relative?

   278      */

   279     private void readPackageList(InputStream input, String path,

   280                                 boolean relative)

   281                          throws IOException {

   282         BufferedReader in = new BufferedReader(new InputStreamReader(input));

   283         StringBuilder strbuf = new StringBuilder();

   284         try {

   285             int c;

   286             while ((c = in.read()) >= 0) {

   287                 char ch = (char)c;

   288                 if (ch == '\n' || ch == '\r') {

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

   290                         String packname = strbuf.toString();

   291                         String packpath = path +

   292                                       packname.replace('.', '/') + '/';

   293                         new Item(packname, packpath, relative);

   294                         strbuf.setLength(0);

   295                     }

   296                 } else {

   297                     strbuf.append(ch);

   298                 }

   299             }

   300         } finally {

   301             input.close();

   302         }

   303     }

   304 

   305     public boolean isUrl (String urlCandidate) {

   306         try {

   307             new URL(urlCandidate);

   308             //No exception was thrown, so this must really be a URL.

   309             return true;

   310         } catch (MalformedURLException e) {

   311             //Since exception is thrown, this must be a directory path.

   312             return false;

   313         }

   314     }

   315 }