Class RelativizingFileManager

  • All Implemented Interfaces:
    Closeable, Flushable, AutoCloseable, JavaFileManager, OptionChecker, StandardJavaFileManager

    public class RelativizingFileManager
    extends ForwardingJavaFileManager<StandardJavaFileManager>
    implements StandardJavaFileManager
    A ForwardingJavaFileManager that interposes when asked for an output file of type HTML, and rewrites href URLs that contain RELDOTS as a component.

    Purpose

    This file manager is intended for use with the DocumentationTool when -linkoffline is used to generate links between subprojects (for example, pljava-examples to pljava-api). Maven's site:stage will copy the generated per-subproject documentation trees into a single staging directory, which can be relocated, deployed to web servers, etc. Therefore, it is both reasonable and desirable for the subproject API docs to refer to each other by relative links. However, the documentation for -linkoffline states that the relative links should be given as if from the output destination (-d) directory. That implies that the tool will add the right number of ../ components, when generating links in a file some levels below the -d directory, so that the resulting relative URL will be correct. And it doesn't. The tool simply doesn't.

    As a workaround, the -linkoffline option can be told to produce URLs that contain RELDOTS, for example, ../../RELDOTS/pljava-api/apidocs, and this file manager can be used when running the tool. As the HTML files are written, any href URL that begins with zero or more ../ followed by RELDOTS will have the RELDOTS replaced with the right number of ../ to ascend from that file's containing directory to the output destination directory, resulting in relative URLs that are correct in files at any depth in the API docs tree.

    An alert reader will notice that RELDOTS is expanded to exactly what {@docRoot} is supposed to expand to. But experiment showed that {@docRoot} does not get expanded in a -linkoffline URL.

    Limitations

    The postprocessing is done blindly to any rules of HTML syntax. It will simply replace RELDOTS in any substring of the content resembling href="../RELDOTS/ (with any number, zero or more, of ../ before the RELDOTS). The example in the preceding sentence was written carefully to avoid being rewritten in this comment.

    Only the form with a double quote is recognized, as the javadoc tool does not appear to generate the single-quoted form.