Class RelativizingFileManager
- java.lang.Object
-
- javax.tools.ForwardingJavaFileManager<StandardJavaFileManager>
-
- org.postgresql.pljava.pgxs.RelativizingFileManager
-
- All Implemented Interfaces:
Closeable
,Flushable
,AutoCloseable
,JavaFileManager
,OptionChecker
,StandardJavaFileManager
public class RelativizingFileManager extends ForwardingJavaFileManager<StandardJavaFileManager> implements StandardJavaFileManager
AForwardingJavaFileManager
that interposes when asked for an output file of typeHTML
, and rewriteshref
URLs that containRELDOTS
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
topljava-api
). Maven'ssite:stage
will copy the generated per-subproject documentation trees into a singlestaging
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 containRELDOTS
, for example,../../RELDOTS/pljava-api/apidocs
, and this file manager can be used when running the tool. As the HTML files are written, anyhref
URL that begins with zero or more../
followed byRELDOTS
will have theRELDOTS
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 replaceRELDOTS
in any substring of the content resemblinghref="../RELDOTS/
(with any number, zero or more, of../
before theRELDOTS
). 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.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface javax.tools.JavaFileManager
JavaFileManager.Location
-
Nested classes/interfaces inherited from interface javax.tools.StandardJavaFileManager
StandardJavaFileManager.PathFactory
-
-
Field Summary
-
Fields inherited from class javax.tools.ForwardingJavaFileManager
fileManager
-
-
Constructor Summary
Constructors Constructor Description RelativizingFileManager(StandardJavaFileManager fileManager, Charset outputEncoding)
Construct aRelativizingFileManager
, given the underlying file manager fromDocumentationTool.getStandardFileManager(javax.tools.DiagnosticListener<? super javax.tools.JavaFileObject>, java.util.Locale, java.nio.charset.Charset)
, and the output encoding to be used.
-
Method Summary
-
Methods inherited from class javax.tools.ForwardingJavaFileManager
close, contains, flush, getClassLoader, getFileForInput, getJavaFileForInput, getJavaFileForOutput, getLocationForModule, getLocationForModule, getServiceLoader, handleOption, hasLocation, inferBinaryName, inferModuleName, isSameFile, isSupportedOption, list, listLocationsForModules
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface javax.tools.JavaFileManager
close, contains, flush, getClassLoader, getFileForInput, getJavaFileForInput, getJavaFileForOutput, getLocationForModule, getLocationForModule, getServiceLoader, handleOption, hasLocation, inferBinaryName, inferModuleName, list, listLocationsForModules
-
Methods inherited from interface javax.tools.OptionChecker
isSupportedOption
-
Methods inherited from interface javax.tools.StandardJavaFileManager
isSameFile
-
-
-
-
Constructor Detail
-
RelativizingFileManager
public RelativizingFileManager(StandardJavaFileManager fileManager, Charset outputEncoding)
Construct aRelativizingFileManager
, given the underlying file manager fromDocumentationTool.getStandardFileManager(javax.tools.DiagnosticListener<? super javax.tools.JavaFileObject>, java.util.Locale, java.nio.charset.Charset)
, and the output encoding to be used.The javadoc tool requests
OutputStream
s for its output files, and supplies content already encoded, so the encoding is needed in order to decode them here for simple processing (asjava.util.regex
does not offer byte-domain flavors of patterns and matchers), then re-encode the result.The file manager constructed here must still be configured by passing the necessary subset of the desired javadoc options to
handleFirstOptions
.- Parameters:
fileManager
- the original file manager to be wrapped by this oneoutputEncoding
- the encoding that the caller will be using when writing bytes to an output file from this manager
-
-
Method Detail
-
getFileForOutput
public FileObject getFileForOutput(JavaFileManager.Location location, String packageName, String relativePath, FileObject sibling) throws IOException
Overridden to return the superclass result unchanged unless the requested file is of kindHTML
, and in that case to return a file object that will interpose on theOutputStream
and apply the rewriting.- Specified by:
getFileForOutput
in interfaceJavaFileManager
- Overrides:
getFileForOutput
in classForwardingJavaFileManager<StandardJavaFileManager>
- Throws:
IOException
-
handleFirstOptions
public void handleFirstOptions(Iterable<String> firstOptions)
CallhandleOption
on as many of the first supplied options as the file manager recognizes.Returns when
handleOption
first returns false, indicating an option the file manager does not recognize.As the options recognized by the standard file manager are generally those among the "Standard Options" that javadoc inherits from javac (including the various location-setting options such as
-classpath
, as well as-encoding
), with a little care to place those first in the argument list to be passed to the tool itself, the same list can be passed to this method to configure the file manager, without any more complicated option recognition needed here.- Parameters:
firstOptions
- an Iterable of options, where those recognized by a file manager must be first
-
getJavaFileObjectsFromFiles
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files)
- Specified by:
getJavaFileObjectsFromFiles
in interfaceStandardJavaFileManager
-
getJavaFileObjectsFromPaths
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Collection<? extends Path> paths)
-
getJavaFileObjectsFromPaths
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Iterable<? extends Path> paths)
- Specified by:
getJavaFileObjectsFromPaths
in interfaceStandardJavaFileManager
-
getJavaFileObjects
public Iterable<? extends JavaFileObject> getJavaFileObjects(File... files)
- Specified by:
getJavaFileObjects
in interfaceStandardJavaFileManager
-
getJavaFileObjects
public Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths)
- Specified by:
getJavaFileObjects
in interfaceStandardJavaFileManager
-
getJavaFileObjectsFromStrings
public Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(Iterable<String> names)
- Specified by:
getJavaFileObjectsFromStrings
in interfaceStandardJavaFileManager
-
getJavaFileObjects
public Iterable<? extends JavaFileObject> getJavaFileObjects(String... names)
- Specified by:
getJavaFileObjects
in interfaceStandardJavaFileManager
-
setLocation
public void setLocation(JavaFileManager.Location location, Iterable<? extends File> files) throws IOException
- Specified by:
setLocation
in interfaceStandardJavaFileManager
- Throws:
IOException
-
setLocationFromPaths
public void setLocationFromPaths(JavaFileManager.Location location, Collection<? extends Path> paths) throws IOException
- Specified by:
setLocationFromPaths
in interfaceStandardJavaFileManager
- Throws:
IOException
-
setLocationForModule
public void setLocationForModule(JavaFileManager.Location location, String moduleName, Collection<? extends Path> paths) throws IOException
- Specified by:
setLocationForModule
in interfaceStandardJavaFileManager
- Throws:
IOException
-
getLocation
public Iterable<? extends File> getLocation(JavaFileManager.Location location)
- Specified by:
getLocation
in interfaceStandardJavaFileManager
-
getLocationAsPaths
public Iterable<? extends Path> getLocationAsPaths(JavaFileManager.Location location)
- Specified by:
getLocationAsPaths
in interfaceStandardJavaFileManager
-
asPath
public Path asPath(FileObject file)
- Specified by:
asPath
in interfaceStandardJavaFileManager
-
setPathFactory
public void setPathFactory(StandardJavaFileManager.PathFactory f)
- Specified by:
setPathFactory
in interfaceStandardJavaFileManager
-
-