diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/taskdefs/Javadoc.java')
-rw-r--r-- | framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/taskdefs/Javadoc.java | 2624 |
1 files changed, 0 insertions, 2624 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/taskdefs/Javadoc.java b/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/taskdefs/Javadoc.java deleted file mode 100644 index 7637be74..00000000 --- a/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/taskdefs/Javadoc.java +++ /dev/null @@ -1,2624 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - */ -package org.apache.tools.ant.taskdefs; - -import java.io.BufferedReader; -import java.io.BufferedWriter; -import java.io.File; -import java.io.FileInputStream; -import java.io.FileNotFoundException; -import java.io.FileOutputStream; -import java.io.FileReader; -import java.io.FileWriter; -import java.io.FilenameFilter; -import java.io.IOException; -import java.io.InputStream; -import java.io.InputStreamReader; -import java.io.OutputStreamWriter; -import java.net.MalformedURLException; -import java.net.URL; -import java.util.ArrayList; -import java.util.Enumeration; -import java.util.HashSet; -import java.util.Iterator; -import java.util.Locale; -import java.util.StringTokenizer; -import java.util.Vector; - -import org.apache.tools.ant.BuildException; -import org.apache.tools.ant.DirectoryScanner; -import org.apache.tools.ant.MagicNames; -import org.apache.tools.ant.Project; -import org.apache.tools.ant.ProjectComponent; -import org.apache.tools.ant.Task; -import org.apache.tools.ant.types.Commandline; -import org.apache.tools.ant.types.DirSet; -import org.apache.tools.ant.types.EnumeratedAttribute; -import org.apache.tools.ant.types.FileSet; -import org.apache.tools.ant.types.Path; -import org.apache.tools.ant.types.PatternSet; -import org.apache.tools.ant.types.Reference; -import org.apache.tools.ant.types.Resource; -import org.apache.tools.ant.types.ResourceCollection; -import org.apache.tools.ant.types.resources.FileProvider; -import org.apache.tools.ant.util.FileUtils; -import org.apache.tools.ant.util.JavaEnvUtils; -import org.apache.tools.ant.util.StringUtils; - -/** - * Generates Javadoc documentation for a collection - * of source code. - * - * <p>Current known limitations are: - * - * <p><ul> - * <li>patterns must be of the form "xxx.*", every other pattern doesn't - * work. - * <li>there is no control on arguments sanity since they are left - * to the Javadoc implementation. - * </ul> - * - * <p>If no <code>doclet</code> is set, then the <code>version</code> and - * <code>author</code> are by default <code>"yes"</code>. - * - * <p>Note: This task is run on another VM because the Javadoc code calls - * <code>System.exit()</code> which would break Ant functionality. - * - * @since Ant 1.1 - * - * @ant.task category="java" - */ -public class Javadoc extends Task { - // Whether *this VM* is 1.4+ (but also check executable != null). - - private static final boolean JAVADOC_5 = - !JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_4); - - private static final String LOAD_FRAME = "function loadFrames() {"; - private static final int LOAD_FRAME_LEN = LOAD_FRAME.length(); - - /** - * Inner class used to manage doclet parameters. - */ - public class DocletParam { - /** The parameter name */ - private String name; - - /** The parameter value */ - private String value; - - /** - * Set the name of the parameter. - * - * @param name the name of the doclet parameter - */ - public void setName(final String name) { - this.name = name; - } - - /** - * Get the parameter name. - * - * @return the parameter's name. - */ - public String getName() { - return name; - } - - /** - * Set the parameter value. - * - * Note that only string values are supported. No resolution of file - * paths is performed. - * - * @param value the parameter value. - */ - public void setValue(final String value) { - this.value = value; - } - - /** - * Get the parameter value. - * - * @return the parameter value. - */ - public String getValue() { - return value; - } - } - - /** - * A project aware class used for Javadoc extensions which take a name - * and a path such as doclet and taglet arguments. - * - */ - public static class ExtensionInfo extends ProjectComponent { - /** The name of the extension */ - private String name; - - /** The optional path to use to load the extension */ - private Path path; - - /** - * Set the name of the extension - * - * @param name the extension's name. - */ - public void setName(final String name) { - this.name = name; - } - - /** - * Get the name of the extension. - * - * @return the extension's name. - */ - public String getName() { - return name; - } - - /** - * Set the path to use when loading the component. - * - * @param path a Path instance containing the classpath to use. - */ - public void setPath(final Path path) { - if (this.path == null) { - this.path = path; - } else { - this.path.append(path); - } - } - - /** - * Get the extension's path. - * - * @return the path to be used to load the extension. - * May be <code>null</code> - */ - public Path getPath() { - return path; - } - - /** - * Create an empty nested path to be configured by Ant with the - * classpath for the extension. - * - * @return a new Path instance to be configured. - */ - public Path createPath() { - if (path == null) { - path = new Path(getProject()); - } - return path.createPath(); - } - - /** - * Adds a reference to a CLASSPATH defined elsewhere. - * - * @param r the reference containing the path. - */ - public void setPathRef(final Reference r) { - createPath().setRefid(r); - } - } - - /** - * This class stores info about doclets. - * - */ - public class DocletInfo extends ExtensionInfo { - - /** Collection of doclet parameters. */ - private final Vector<DocletParam> params = new Vector<DocletParam>(); - - /** - * Create a doclet parameter to be configured by Ant. - * - * @return a new DocletParam instance to be configured. - */ - public DocletParam createParam() { - final DocletParam param = new DocletParam(); - params.addElement(param); - - return param; - } - - /** - * Get the doclet's parameters. - * - * @return an Enumeration of DocletParam instances. - */ - public Enumeration<DocletParam> getParams() { - return params.elements(); - } - } - - /** - * Used to track info about the packages to be javadoc'd - */ - public static class PackageName { - /** The package name */ - private String name; - - /** - * Set the name of the package - * - * @param name the package name. - */ - public void setName(final String name) { - this.name = name.trim(); - } - - /** - * Get the package name. - * - * @return the package's name. - */ - public String getName() { - return name; - } - - /** - * Return a string rep for this object. - * @return the package name. - */ - @Override - public String toString() { - return getName(); - } - } - - /** - * This class is used to manage the source files to be processed. - */ - public static class SourceFile { - /** The source file */ - private File file; - - /** - * Default constructor - */ - public SourceFile() { - //empty - } - - /** - * Constructor specifying the source file directly - * - * @param file the source file - */ - public SourceFile(final File file) { - this.file = file; - } - - /** - * Set the source file. - * - * @param file the source file. - */ - public void setFile(final File file) { - this.file = file; - } - - /** - * Get the source file. - * - * @return the source file. - */ - public File getFile() { - return file; - } - } - - /** - * An HTML element in the Javadoc. - * - * This class is used for those Javadoc elements which contain HTML such as - * footers, headers, etc. - */ - public static class Html { - /** The text for the element */ - private final StringBuffer text = new StringBuffer(); - - /** - * Add text to the element. - * - * @param t the text to be added. - */ - public void addText(final String t) { - text.append(t); - } - - /** - * Get the current text for the element. - * - * @return the current text. - */ - public String getText() { - return text.substring(0); - } - } - - /** - * EnumeratedAttribute implementation supporting the Javadoc scoping - * values. - */ - public static class AccessType extends EnumeratedAttribute { - /** - * @return the allowed values for the access type. - */ - @Override - public String[] getValues() { - // Protected first so if any GUI tool offers a default - // based on enum #0, it will be right. - return new String[] {"protected", "public", "package", "private"}; - } - } - - /** - * Holds a collection of ResourceCollections. - * - * <p>A separate kind of container is needed since this task - * contains special handling for FileSets that has to occur at - * task runtime.</p> - */ - public class ResourceCollectionContainer { - private final ArrayList<ResourceCollection> rcs = new ArrayList<ResourceCollection>(); - /** - * Add a resource collection to the container. - * @param rc the collection to add. - */ - public void add(final ResourceCollection rc) { - rcs.add(rc); - } - - /** - * Get an iterator on the collection. - * @return an iterator. - */ - private Iterator<ResourceCollection> iterator() { - return rcs.iterator(); - } - } - - private static final FileUtils FILE_UTILS = FileUtils.getFileUtils(); - - /** The command line built to execute Javadoc. */ - private final Commandline cmd = new Commandline(); - - /** - * Utility method to add an argument to the command line conditionally - * based on the given flag. - * - * @param b the flag which controls if the argument is added. - * @param arg the argument value. - */ - private void addArgIf(final boolean b, final String arg) { - if (b) { - cmd.createArgument().setValue(arg); - } - } - - /** - * Utility method to add a Javadoc argument. - * - * @param key the argument name. - * @param value the argument value. - */ - private void addArgIfNotEmpty(final String key, final String value) { - if (value != null && value.length() != 0) { - cmd.createArgument().setValue(key); - cmd.createArgument().setValue(value); - } else { - log("Warning: Leaving out empty argument '" + key + "'", - Project.MSG_WARN); - } - } - - /** - * Flag which indicates if the task should fail if there is a - * Javadoc error. - */ - private boolean failOnError = false; - /** - * Flag which indicates if the task should fail if there is a - * Javadoc warning. - */ - private boolean failOnWarning = false; - private Path sourcePath = null; - private File destDir = null; - private final Vector<SourceFile> sourceFiles = new Vector<SourceFile>(); - private final Vector<PackageName> packageNames = new Vector<PackageName>(); - private final Vector<PackageName> excludePackageNames = new Vector<PackageName>(1); - private boolean author = true; - private boolean version = true; - private DocletInfo doclet = null; - private Path classpath = null; - private Path bootclasspath = null; - private String group = null; - private String packageList = null; - private final Vector<LinkArgument> links = new Vector<LinkArgument>(); - private final Vector<GroupArgument> groups = new Vector<GroupArgument>(); - private final Vector<Object> tags = new Vector<Object>(); - private boolean useDefaultExcludes = true; - private Html doctitle = null; - private Html header = null; - private Html footer = null; - private Html bottom = null; - private boolean useExternalFile = false; - private String source = null; - private boolean linksource = false; - private boolean breakiterator = false; - private String noqualifier; - private boolean includeNoSourcePackages = false; - private String executable = null; - private boolean docFilesSubDirs = false; - private String excludeDocFilesSubDir = null; - private String docEncoding = null; - private boolean postProcessGeneratedJavadocs = true; - - private final ResourceCollectionContainer nestedSourceFiles - = new ResourceCollectionContainer(); - private final Vector<DirSet> packageSets = new Vector<DirSet>(); - - /** - * Work around command line length limit by using an external file - * for the sourcefiles. - * - * @param b true if an external file is to be used. - */ - public void setUseExternalFile(final boolean b) { - useExternalFile = b; - } - - /** - * Sets whether default exclusions should be used or not. - * - * @param useDefaultExcludes "true"|"on"|"yes" when default exclusions - * should be used, "false"|"off"|"no" when they - * shouldn't be used. - */ - public void setDefaultexcludes(final boolean useDefaultExcludes) { - this.useDefaultExcludes = useDefaultExcludes; - } - - /** - * Set the maximum memory to be used by the javadoc process - * - * @param max a string indicating the maximum memory according to the - * JVM conventions (e.g. 128m is 128 Megabytes) - */ - public void setMaxmemory(final String max) { - cmd.createArgument().setValue("-J-Xmx" + max); - } - - /** - * Set an additional parameter on the command line - * - * @param add the additional command line parameter for the javadoc task. - */ - public void setAdditionalparam(final String add) { - cmd.createArgument().setLine(add); - } - - /** - * Adds a command-line argument. - * @return a command-line argument to configure - * @since Ant 1.6 - */ - public Commandline.Argument createArg() { - return cmd.createArgument(); - } - - /** - * Specify where to find source file - * - * @param src a Path instance containing the various source directories. - */ - public void setSourcepath(final Path src) { - if (sourcePath == null) { - sourcePath = src; - } else { - sourcePath.append(src); - } - } - - /** - * Create a path to be configured with the locations of the source - * files. - * - * @return a new Path instance to be configured by the Ant core. - */ - public Path createSourcepath() { - if (sourcePath == null) { - sourcePath = new Path(getProject()); - } - return sourcePath.createPath(); - } - - /** - * Adds a reference to a CLASSPATH defined elsewhere. - * - * @param r the reference containing the source path definition. - */ - public void setSourcepathRef(final Reference r) { - createSourcepath().setRefid(r); - } - - /** - * Set the directory where the Javadoc output will be generated. - * - * @param dir the destination directory. - */ - public void setDestdir(final File dir) { - destDir = dir; - cmd.createArgument().setValue("-d"); - cmd.createArgument().setFile(destDir); - } - - /** - * Set the list of source files to process. - * - * @param src a comma separated list of source files. - */ - public void setSourcefiles(final String src) { - final StringTokenizer tok = new StringTokenizer(src, ","); - while (tok.hasMoreTokens()) { - final String f = tok.nextToken(); - final SourceFile sf = new SourceFile(); - sf.setFile(getProject().resolveFile(f.trim())); - addSource(sf); - } - } - - /** - * Add a single source file. - * - * @param sf the source file to be processed. - */ - public void addSource(final SourceFile sf) { - sourceFiles.addElement(sf); - } - - /** - * Set the package names to be processed. - * - * @param packages a comma separated list of packages specs - * (may be wildcarded). - * - * @see #addPackage for wildcard information. - */ - public void setPackagenames(final String packages) { - final StringTokenizer tok = new StringTokenizer(packages, ","); - while (tok.hasMoreTokens()) { - final String p = tok.nextToken(); - final PackageName pn = new PackageName(); - pn.setName(p); - addPackage(pn); - } - } - - /** - * Add a single package to be processed. - * - * If the package name ends with ".*" the Javadoc task - * will find and process all subpackages. - * - * @param pn the package name, possibly wildcarded. - */ - public void addPackage(final PackageName pn) { - packageNames.addElement(pn); - } - - /** - * Set the list of packages to be excluded. - * - * @param packages a comma separated list of packages to be excluded. - * This may not include wildcards. - */ - public void setExcludePackageNames(final String packages) { - final StringTokenizer tok = new StringTokenizer(packages, ","); - while (tok.hasMoreTokens()) { - final String p = tok.nextToken(); - final PackageName pn = new PackageName(); - pn.setName(p); - addExcludePackage(pn); - } - } - - /** - * Add a package to be excluded from the Javadoc run. - * - * @param pn the name of the package (wildcards are not permitted). - */ - public void addExcludePackage(final PackageName pn) { - excludePackageNames.addElement(pn); - } - - /** - * Specify the file containing the overview to be included in the generated - * documentation. - * - * @param f the file containing the overview. - */ - public void setOverview(final File f) { - cmd.createArgument().setValue("-overview"); - cmd.createArgument().setFile(f); - } - - /** - * Indicate whether only public classes and members are to be included in - * the scope processed - * - * @param b true if scope is to be public. - */ - public void setPublic(final boolean b) { - addArgIf(b, "-public"); - } - - /** - * Indicate whether only protected and public classes and members are to - * be included in the scope processed - * - * @param b true if scope is to be protected. - */ - public void setProtected(final boolean b) { - addArgIf(b, "-protected"); - } - - /** - * Indicate whether only package, protected and public classes and - * members are to be included in the scope processed - * - * @param b true if scope is to be package level. - */ - public void setPackage(final boolean b) { - addArgIf(b, "-package"); - } - - /** - * Indicate whether all classes and - * members are to be included in the scope processed - * - * @param b true if scope is to be private level. - */ - public void setPrivate(final boolean b) { - addArgIf(b, "-private"); - } - - /** - * Set the scope to be processed. This is an alternative to the - * use of the setPublic, setPrivate, etc methods. It gives better build - * file control over what scope is processed. - * - * @param at the scope to be processed. - */ - public void setAccess(final AccessType at) { - cmd.createArgument().setValue("-" + at.getValue()); - } - - /** - * Set the class that starts the doclet used in generating the - * documentation. - * - * @param docletName the name of the doclet class. - */ - public void setDoclet(final String docletName) { - if (doclet == null) { - doclet = new DocletInfo(); - doclet.setProject(getProject()); - } - doclet.setName(docletName); - } - - /** - * Set the classpath used to find the doclet class. - * - * @param docletPath the doclet classpath. - */ - public void setDocletPath(final Path docletPath) { - if (doclet == null) { - doclet = new DocletInfo(); - doclet.setProject(getProject()); - } - doclet.setPath(docletPath); - } - - /** - * Set the classpath used to find the doclet class by reference. - * - * @param r the reference to the Path instance to use as the doclet - * classpath. - */ - public void setDocletPathRef(final Reference r) { - if (doclet == null) { - doclet = new DocletInfo(); - doclet.setProject(getProject()); - } - doclet.createPath().setRefid(r); - } - - /** - * Create a doclet to be used in the documentation generation. - * - * @return a new DocletInfo instance to be configured. - */ - public DocletInfo createDoclet() { - if (doclet == null) { - doclet = new DocletInfo(); - } - return doclet; - } - - /** - * Add a taglet - * - * @param tagletInfo information about the taglet. - */ - public void addTaglet(final ExtensionInfo tagletInfo) { - tags.addElement(tagletInfo); - } - - /** - * Indicate whether Javadoc should produce old style (JDK 1.1) - * documentation. - * - * This is not supported by JDK 1.1 and has been phased out in JDK 1.4 - * - * @param b if true attempt to generate old style documentation. - */ - public void setOld(final boolean b) { - log("Javadoc 1.4 doesn't support the -1.1 switch anymore", - Project.MSG_WARN); - } - - /** - * Set the classpath to be used for this Javadoc run. - * - * @param path an Ant Path object containing the compilation - * classpath. - */ - public void setClasspath(final Path path) { - if (classpath == null) { - classpath = path; - } else { - classpath.append(path); - } - } - - /** - * Create a Path to be configured with the classpath to use - * - * @return a new Path instance to be configured with the classpath. - */ - public Path createClasspath() { - if (classpath == null) { - classpath = new Path(getProject()); - } - return classpath.createPath(); - } - - /** - * Adds a reference to a CLASSPATH defined elsewhere. - * - * @param r the reference to an instance defining the classpath. - */ - public void setClasspathRef(final Reference r) { - createClasspath().setRefid(r); - } - - /** - * Set the boot classpath to use. - * - * @param path the boot classpath. - */ - public void setBootclasspath(final Path path) { - if (bootclasspath == null) { - bootclasspath = path; - } else { - bootclasspath.append(path); - } - } - - /** - * Create a Path to be configured with the boot classpath - * - * @return a new Path instance to be configured with the boot classpath. - */ - public Path createBootclasspath() { - if (bootclasspath == null) { - bootclasspath = new Path(getProject()); - } - return bootclasspath.createPath(); - } - - /** - * Adds a reference to a CLASSPATH defined elsewhere. - * - * @param r the reference to an instance defining the bootclasspath. - */ - public void setBootClasspathRef(final Reference r) { - createBootclasspath().setRefid(r); - } - - /** - * Set the location of the extensions directories. - * - * @param path the string version of the path. - * @deprecated since 1.5.x. - * Use the {@link #setExtdirs(Path)} version. - */ - @Deprecated - public void setExtdirs(final String path) { - cmd.createArgument().setValue("-extdirs"); - cmd.createArgument().setValue(path); - } - - /** - * Set the location of the extensions directories. - * - * @param path a path containing the extension directories. - */ - public void setExtdirs(final Path path) { - cmd.createArgument().setValue("-extdirs"); - cmd.createArgument().setPath(path); - } - - /** - * Run javadoc in verbose mode - * - * @param b true if operation is to be verbose. - */ - public void setVerbose(final boolean b) { - addArgIf(b, "-verbose"); - } - - /** - * Set the local to use in documentation generation. - * - * @param locale the locale to use. - */ - public void setLocale(final String locale) { - // createArgument(true) is necessary to make sure -locale - // is the first argument (required in 1.3+). - cmd.createArgument(true).setValue(locale); - cmd.createArgument(true).setValue("-locale"); - } - - /** - * Set the encoding name of the source files, - * - * @param enc the name of the encoding for the source files. - */ - public void setEncoding(final String enc) { - cmd.createArgument().setValue("-encoding"); - cmd.createArgument().setValue(enc); - } - - /** - * Include the version tag in the generated documentation. - * - * @param b true if the version tag should be included. - */ - public void setVersion(final boolean b) { - this.version = b; - } - - /** - * Generate the "use" page for each package. - * - * @param b true if the use page should be generated. - */ - public void setUse(final boolean b) { - addArgIf(b, "-use"); - } - - - /** - * Include the author tag in the generated documentation. - * - * @param b true if the author tag should be included. - */ - public void setAuthor(final boolean b) { - author = b; - } - - /** - * Generate a split index - * - * @param b true if the index should be split into a file per letter. - */ - public void setSplitindex(final boolean b) { - addArgIf(b, "-splitindex"); - } - - /** - * Set the title to be placed in the HTML <title> tag of the - * generated documentation. - * - * @param title the window title to use. - */ - public void setWindowtitle(final String title) { - addArgIfNotEmpty("-windowtitle", title); - } - - /** - * Set the title of the generated overview page. - * - * @param doctitle the Document title. - */ - public void setDoctitle(final String doctitle) { - final Html h = new Html(); - h.addText(doctitle); - addDoctitle(h); - } - - /** - * Add a document title to use for the overview page. - * - * @param text the HTML element containing the document title. - */ - public void addDoctitle(final Html text) { - doctitle = text; - } - - /** - * Set the header text to be placed at the top of each output file. - * - * @param header the header text - */ - public void setHeader(final String header) { - final Html h = new Html(); - h.addText(header); - addHeader(h); - } - - /** - * Set the header text to be placed at the top of each output file. - * - * @param text the header text - */ - public void addHeader(final Html text) { - header = text; - } - - /** - * Set the footer text to be placed at the bottom of each output file. - * - * @param footer the footer text. - */ - public void setFooter(final String footer) { - final Html h = new Html(); - h.addText(footer); - addFooter(h); - } - - /** - * Set the footer text to be placed at the bottom of each output file. - * - * @param text the footer text. - */ - public void addFooter(final Html text) { - footer = text; - } - - /** - * Set the text to be placed at the bottom of each output file. - * - * @param bottom the bottom text. - */ - public void setBottom(final String bottom) { - final Html h = new Html(); - h.addText(bottom); - addBottom(h); - } - - /** - * Set the text to be placed at the bottom of each output file. - * - * @param text the bottom text. - */ - public void addBottom(final Html text) { - bottom = text; - } - - /** - * Link to docs at "url" using package list at "url2" - * - separate the URLs by using a space character. - * - * @param src the offline link specification (url and package list) - */ - public void setLinkoffline(final String src) { - final LinkArgument le = createLink(); - le.setOffline(true); - final String linkOfflineError = "The linkoffline attribute must include" - + " a URL and a package-list file location separated by a" - + " space"; - if (src.trim().length() == 0) { - throw new BuildException(linkOfflineError); - } - final StringTokenizer tok = new StringTokenizer(src, " ", false); - le.setHref(tok.nextToken()); - - if (!tok.hasMoreTokens()) { - throw new BuildException(linkOfflineError); - } - le.setPackagelistLoc(getProject().resolveFile(tok.nextToken())); - } - - /** - * Group specified packages together in overview page. - * - * @param src the group packages - a command separated list of group specs, - * each one being a group name and package specification separated - * by a space. - */ - public void setGroup(final String src) { - group = src; - } - - /** - * Create links to Javadoc output at the given URL. - * @param src the URL to link to - */ - public void setLink(final String src) { - createLink().setHref(src); - } - - /** - * Control deprecation information - * - * @param b If true, do not include deprecated information. - */ - public void setNodeprecated(final boolean b) { - addArgIf(b, "-nodeprecated"); - } - - /** - * Control deprecated list generation - * - * @param b if true, do not generate deprecated list. - */ - public void setNodeprecatedlist(final boolean b) { - addArgIf(b, "-nodeprecatedlist"); - } - - /** - * Control class tree generation. - * - * @param b if true, do not generate class hierarchy. - */ - public void setNotree(final boolean b) { - addArgIf(b, "-notree"); - } - - /** - * Control generation of index. - * - * @param b if true, do not generate index. - */ - public void setNoindex(final boolean b) { - addArgIf(b, "-noindex"); - } - - /** - * Control generation of help link. - * - * @param b if true, do not generate help link - */ - public void setNohelp(final boolean b) { - addArgIf(b, "-nohelp"); - } - - /** - * Control generation of the navigation bar. - * - * @param b if true, do not generate navigation bar. - */ - public void setNonavbar(final boolean b) { - addArgIf(b, "-nonavbar"); - } - - /** - * Control warnings about serial tag. - * - * @param b if true, generate warning about the serial tag. - */ - public void setSerialwarn(final boolean b) { - addArgIf(b, "-serialwarn"); - } - - /** - * Specifies the CSS stylesheet file to use. - * - * @param f the file with the CSS to use. - */ - public void setStylesheetfile(final File f) { - cmd.createArgument().setValue("-stylesheetfile"); - cmd.createArgument().setFile(f); - } - - /** - * Specifies the HTML help file to use. - * - * @param f the file containing help content. - */ - public void setHelpfile(final File f) { - cmd.createArgument().setValue("-helpfile"); - cmd.createArgument().setFile(f); - } - - /** - * Output file encoding name. - * - * @param enc name of the encoding to use. - */ - public void setDocencoding(final String enc) { - cmd.createArgument().setValue("-docencoding"); - cmd.createArgument().setValue(enc); - docEncoding = enc; - } - - /** - * The name of a file containing the packages to process. - * - * @param src the file containing the package list. - */ - public void setPackageList(final String src) { - packageList = src; - } - - /** - * Create link to Javadoc output at the given URL. - * - * @return link argument to configure - */ - public LinkArgument createLink() { - final LinkArgument la = new LinkArgument(); - links.addElement(la); - return la; - } - - /** - * Represents a link triplet (href, whether link is offline, - * location of the package list if off line) - */ - public class LinkArgument { - private String href; - private boolean offline = false; - private File packagelistLoc; - private URL packagelistURL; - private boolean resolveLink = false; - - /** Constructor for LinkArgument */ - public LinkArgument() { - //empty - } - - /** - * Set the href attribute. - * @param hr a <code>String</code> value - */ - public void setHref(final String hr) { - href = hr; - } - - /** - * Get the href attribute. - * @return the href attribute. - */ - public String getHref() { - return href; - } - - /** - * Set the packetlist location attribute. - * @param src a <code>File</code> value - */ - public void setPackagelistLoc(final File src) { - packagelistLoc = src; - } - - /** - * Get the packetList location attribute. - * @return the packetList location attribute. - */ - public File getPackagelistLoc() { - return packagelistLoc; - } - - /** - * Set the packetlist location attribute. - * @param src an <code>URL</code> value - */ - public void setPackagelistURL(final URL src) { - packagelistURL = src; - } - - /** - * Get the packetList location attribute. - * @return the packetList location attribute. - */ - public URL getPackagelistURL() { - return packagelistURL; - } - - /** - * Set the offline attribute. - * @param offline a <code>boolean</code> value - */ - public void setOffline(final boolean offline) { - this.offline = offline; - } - - /** - * Get the linkOffline attribute. - * @return the linkOffline attribute. - */ - public boolean isLinkOffline() { - return offline; - } - - /** - * Sets whether Ant should resolve the link attribute relative - * to the current basedir. - * @param resolve a <code>boolean</code> value - */ - public void setResolveLink(final boolean resolve) { - this.resolveLink = resolve; - } - - /** - * should Ant resolve the link attribute relative to the - * current basedir? - * @return the resolveLink attribute. - */ - public boolean shouldResolveLink() { - return resolveLink; - } - - } - - /** - * Creates and adds a -tag argument. This is used to specify - * custom tags. This argument is only available for Javadoc 1.4, - * and will generate a verbose message (and then be ignored) - * when run on Java versions below 1.4. - * @return tag argument to be configured - */ - public TagArgument createTag() { - final TagArgument ta = new TagArgument(); - tags.addElement (ta); - return ta; - } - - /** - * Scope element verbose names. (Defined here as fields - * cannot be static in inner classes.) The first letter - * from each element is used to build up the scope string. - */ - static final String[] SCOPE_ELEMENTS = { - "overview", "packages", "types", "constructors", - "methods", "fields" - }; - - /** - * Class representing a -tag argument. - */ - public class TagArgument extends FileSet { - /** Name of the tag. */ - private String name = null; - /** Whether or not the tag is enabled. */ - private boolean enabled = true; - /** - * Scope string of the tag. This will form the middle - * argument of the -tag parameter when the tag is enabled - * (with an X prepended for and is parsed from human-readable form. - */ - private String scope = "a"; - - /** Sole constructor. */ - public TagArgument () { - //empty - } - - /** - * Sets the name of the tag. - * - * @param name The name of the tag. - * Must not be <code>null</code> or empty. - */ - public void setName (final String name) { - this.name = name; - } - - /** - * Sets the scope of the tag. This is in comma-separated - * form, with each element being one of "all" (the default), - * "overview", "packages", "types", "constructors", "methods", - * "fields". The elements are treated in a case-insensitive - * manner. - * - * @param verboseScope The scope of the tag. - * Must not be <code>null</code>, - * should not be empty. - * - * @exception BuildException if all is specified along with - * other elements, if any elements are repeated, if no - * elements are specified, or if any unrecognised elements are - * specified. - */ - public void setScope (String verboseScope) throws BuildException { - verboseScope = verboseScope.toLowerCase(Locale.ENGLISH); - - final boolean[] elements = new boolean[SCOPE_ELEMENTS.length]; - - boolean gotAll = false; - boolean gotNotAll = false; - - // Go through the tokens one at a time, updating the - // elements array and issuing warnings where appropriate. - final StringTokenizer tok = new StringTokenizer (verboseScope, ","); - while (tok.hasMoreTokens()) { - final String next = tok.nextToken().trim(); - if (next.equals("all")) { - if (gotAll) { - getProject().log ("Repeated tag scope element: all", - Project.MSG_VERBOSE); - } - gotAll = true; - } else { - int i; - for (i = 0; i < SCOPE_ELEMENTS.length; i++) { - if (next.equals (SCOPE_ELEMENTS[i])) { - break; - } - } - if (i == SCOPE_ELEMENTS.length) { - throw new BuildException ("Unrecognised scope element: " - + next); - } else { - if (elements[i]) { - getProject().log ("Repeated tag scope element: " - + next, Project.MSG_VERBOSE); - } - elements[i] = true; - gotNotAll = true; - } - } - } - - if (gotNotAll && gotAll) { - throw new BuildException ("Mixture of \"all\" and other scope " - + "elements in tag parameter."); - } - if (!gotNotAll && !gotAll) { - throw new BuildException ("No scope elements specified in tag " - + "parameter."); - } - if (gotAll) { - this.scope = "a"; - } else { - final StringBuffer buff = new StringBuffer (elements.length); - for (int i = 0; i < elements.length; i++) { - if (elements[i]) { - buff.append (SCOPE_ELEMENTS[i].charAt(0)); - } - } - this.scope = buff.toString(); - } - } - - /** - * Sets whether or not the tag is enabled. - * - * @param enabled Whether or not this tag is enabled. - */ - public void setEnabled (final boolean enabled) { - this.enabled = enabled; - } - - /** - * Returns the -tag parameter this argument represented. - * @return the -tag parameter as a string - * @exception BuildException if either the name or description - * is <code>null</code> or empty. - */ - public String getParameter() throws BuildException { - if (name == null || name.equals("")) { - throw new BuildException ("No name specified for custom tag."); - } - if (getDescription() != null) { - return name + ":" + (enabled ? "" : "X") - + scope + ":" + getDescription(); - } else if (!enabled || !"a".equals(scope)) { - return name + ":" + (enabled ? "" : "X") + scope; - } else { - return name; - } - } - } - - /** - * Separates packages on the overview page into whatever - * groups you specify, one group per table. - * @return a group argument to be configured - */ - public GroupArgument createGroup() { - final GroupArgument ga = new GroupArgument(); - groups.addElement(ga); - return ga; - } - - - /** - * A class corresponding to the group nested element. - */ - public class GroupArgument { - private Html title; - private final Vector<PackageName> packages = new Vector<PackageName>(); - - /** Constructor for GroupArgument */ - public GroupArgument() { - //empty - } - - /** - * Set the title attribute using a string. - * @param src a <code>String</code> value - */ - public void setTitle(final String src) { - final Html h = new Html(); - h.addText(src); - addTitle(h); - } - /** - * Set the title attribute using a nested Html value. - * @param text a <code>Html</code> value - */ - public void addTitle(final Html text) { - title = text; - } - - /** - * Get the title. - * @return the title - */ - public String getTitle() { - return title != null ? title.getText() : null; - } - - /** - * Set the packages to Javadoc on. - * @param src a comma separated list of packages - */ - public void setPackages(final String src) { - final StringTokenizer tok = new StringTokenizer(src, ","); - while (tok.hasMoreTokens()) { - final String p = tok.nextToken(); - final PackageName pn = new PackageName(); - pn.setName(p); - addPackage(pn); - } - } - /** - * Add a package nested element. - * @param pn a nested element specifying the package. - */ - public void addPackage(final PackageName pn) { - packages.addElement(pn); - } - - /** - * Get the packages as a colon separated list. - * @return the packages as a string - */ - public String getPackages() { - final StringBuffer p = new StringBuffer(); - final int size = packages.size(); - for (int i = 0; i < size; i++) { - if (i > 0) { - p.append(":"); - } - p.append(packages.elementAt(i).toString()); - } - return p.toString(); - } - } - - /** - * Charset for cross-platform viewing of generated documentation. - * @param src the name of the charset - */ - public void setCharset(final String src) { - this.addArgIfNotEmpty("-charset", src); - } - - /** - * Should the build process fail if Javadoc fails (as indicated by - * a non zero return code)? - * - * <p>Default is false.</p> - * @param b a <code>boolean</code> value - */ - public void setFailonerror(final boolean b) { - failOnError = b; - } - - /** - * Should the build process fail if Javadoc warns (as indicated by - * the word "warning" on stdout)? - * - * <p>Default is false.</p> - * @param b a <code>boolean</code> value - * @since Ant 1.9.4 - */ - public void setFailonwarning(final boolean b) { - failOnWarning = b; - } - - /** - * Enables the -source switch, will be ignored if Javadoc is not - * the 1.4 version. - * @param source a <code>String</code> value - * @since Ant 1.5 - */ - public void setSource(final String source) { - this.source = source; - } - - /** - * Sets the actual executable command to invoke, instead of the binary - * <code>javadoc</code> found in Ant's JDK. - * @param executable the command to invoke. - * @since Ant 1.6.3 - */ - public void setExecutable(final String executable) { - this.executable = executable; - } - - /** - * Adds a packageset. - * - * <p>All included directories will be translated into package - * names be converting the directory separator into dots.</p> - * @param packageSet a directory set - * @since 1.5 - */ - public void addPackageset(final DirSet packageSet) { - packageSets.addElement(packageSet); - } - - /** - * Adds a fileset. - * - * <p>All included files will be added as sourcefiles. The task - * will automatically add - * <code>includes="**/*.java"</code> to the - * fileset.</p> - * @param fs a file set - * @since 1.5 - */ - public void addFileset(final FileSet fs) { - createSourceFiles().add(fs); - } - - /** - * Adds a container for resource collections. - * - * <p>All included files will be added as sourcefiles.</p> - * @return the source files to configure. - * @since 1.7 - */ - public ResourceCollectionContainer createSourceFiles() { - return nestedSourceFiles; - } - - /** - * Enables the -linksource switch, will be ignored if Javadoc is not - * the 1.4 version. Default is false - * @param b a <code>String</code> value - * @since Ant 1.6 - */ - public void setLinksource(final boolean b) { - this.linksource = b; - } - - /** - * Enables the -linksource switch, will be ignored if Javadoc is not - * the 1.4 version. Default is false - * @param b a <code>String</code> value - * @since Ant 1.6 - */ - public void setBreakiterator(final boolean b) { - this.breakiterator = b; - } - - /** - * Enables the -noqualifier switch, will be ignored if Javadoc is not - * the 1.4 version. - * @param noqualifier the parameter to the -noqualifier switch - * @since Ant 1.6 - */ - public void setNoqualifier(final String noqualifier) { - this.noqualifier = noqualifier; - } - - /** - * If set to true, Ant will also accept packages that only hold - * package.html files but no Java sources. - * @param b a <code>boolean</code> value. - * @since Ant 1.6.3 - */ - public void setIncludeNoSourcePackages(final boolean b) { - this.includeNoSourcePackages = b; - } - - /** - * Enables deep-copying of <code>doc-files</code> directories. - * - * @since Ant 1.8.0 - */ - public void setDocFilesSubDirs(final boolean b) { - docFilesSubDirs = b; - } - - /** - * Colon-separated list of <code>doc-files</code> subdirectories - * to skip if {@link #setDocFilesSubDirs docFilesSubDirs is true}. - * - * @since Ant 1.8.0 - */ - public void setExcludeDocFilesSubDir(final String s) { - excludeDocFilesSubDir = s; - } - - /** - * Whether to post-process the generated javadocs in order to mitigate CVE-2013-1571. - * @since Ant 1.9.2 - */ - public void setPostProcessGeneratedJavadocs(final boolean b) { - postProcessGeneratedJavadocs = b; - } - - /** - * Execute the task. - * @throws BuildException on error - */ - @Override - public void execute() throws BuildException { - checkTaskName(); - - final Vector<String> packagesToDoc = new Vector<String>(); - final Path sourceDirs = new Path(getProject()); - - checkPackageAndSourcePath(); - - if (sourcePath != null) { - sourceDirs.addExisting(sourcePath); - } - - parsePackages(packagesToDoc, sourceDirs); - checkPackages(packagesToDoc, sourceDirs); - - @SuppressWarnings("unchecked") - final Vector<SourceFile> sourceFilesToDoc = (Vector<SourceFile>) sourceFiles.clone(); - addSourceFiles(sourceFilesToDoc); - - checkPackagesToDoc(packagesToDoc, sourceFilesToDoc); - - log("Generating Javadoc", Project.MSG_INFO); - - final Commandline toExecute = (Commandline) cmd.clone(); - if (executable != null) { - toExecute.setExecutable(executable); - } else { - toExecute.setExecutable(JavaEnvUtils.getJdkExecutable("javadoc")); - } - - // Javadoc arguments - generalJavadocArguments(toExecute); // general Javadoc arguments - doSourcePath(toExecute, sourceDirs); // sourcepath - doDoclet(toExecute); // arguments for default doclet - doBootPath(toExecute); // bootpath - doLinks(toExecute); // links arguments - doGroup(toExecute); // group attribute - doGroups(toExecute); // groups attribute - doDocFilesSubDirs(toExecute); // docfilessubdir attribute - - doJava14(toExecute); - if (breakiterator && (doclet == null || JAVADOC_5)) { - toExecute.createArgument().setValue("-breakiterator"); - } - // If using an external file, write the command line options to it - if (useExternalFile) { - writeExternalArgs(toExecute); - } - - File tmpList = null; - FileWriter wr = null; - try { - /** - * Write sourcefiles and package names to a temporary file - * if requested. - */ - BufferedWriter srcListWriter = null; - if (useExternalFile) { - tmpList = FILE_UTILS.createTempFile("javadoc", "", null, true, true); - toExecute.createArgument() - .setValue("@" + tmpList.getAbsolutePath()); - wr = new FileWriter(tmpList.getAbsolutePath(), true); - srcListWriter = new BufferedWriter(wr); - } - - doSourceAndPackageNames( - toExecute, packagesToDoc, sourceFilesToDoc, - useExternalFile, tmpList, srcListWriter); - - if (useExternalFile) { - srcListWriter.flush(); - } - } catch (final IOException e) { - tmpList.delete(); - throw new BuildException("Error creating temporary file", - e, getLocation()); - } finally { - FileUtils.close(wr); - } - - if (packageList != null) { - toExecute.createArgument().setValue("@" + packageList); - } - log(toExecute.describeCommand(), Project.MSG_VERBOSE); - - log("Javadoc execution", Project.MSG_INFO); - - final JavadocOutputStream out = new JavadocOutputStream(Project.MSG_INFO); - final JavadocOutputStream err = new JavadocOutputStream(Project.MSG_WARN); - final Execute exe = new Execute(new PumpStreamHandler(out, err)); - exe.setAntRun(getProject()); - - /* - * No reason to change the working directory as all filenames and - * path components have been resolved already. - * - * Avoid problems with command line length in some environments. - */ - exe.setWorkingDirectory(null); - try { - exe.setCommandline(toExecute.getCommandline()); - final int ret = exe.execute(); - if (ret != 0 && failOnError) { - throw new BuildException("Javadoc returned " + ret, - getLocation()); - } - if (out.sawWarnings() && failOnWarning) { - throw new BuildException("Javadoc issued warnings.", - getLocation()); - } - postProcessGeneratedJavadocs(); - } catch (final IOException e) { - throw new BuildException("Javadoc failed: " + e, e, getLocation()); - } finally { - if (tmpList != null) { - tmpList.delete(); - tmpList = null; - } - - out.logFlush(); - err.logFlush(); - try { - out.close(); - err.close(); - } catch (final IOException e) { - // ignore - } - } - } - - private void checkTaskName() { - if ("javadoc2".equals(getTaskType())) { - log("Warning: the task name <javadoc2> is deprecated." - + " Use <javadoc> instead.", - Project.MSG_WARN); - } - } - - private void checkPackageAndSourcePath() { - if (packageList != null && sourcePath == null) { - final String msg = "sourcePath attribute must be set when " - + "specifying packagelist."; - throw new BuildException(msg); - } - } - - private void checkPackages(final Vector<String> packagesToDoc, final Path sourceDirs) { - if (packagesToDoc.size() != 0 && sourceDirs.size() == 0) { - final String msg = "sourcePath attribute must be set when " - + "specifying package names."; - throw new BuildException(msg); - } - } - - private void checkPackagesToDoc( - final Vector<String> packagesToDoc, final Vector<SourceFile> sourceFilesToDoc) { - if (packageList == null && packagesToDoc.size() == 0 - && sourceFilesToDoc.size() == 0) { - throw new BuildException("No source files and no packages have " - + "been specified."); - } - } - - private void doSourcePath(final Commandline toExecute, final Path sourceDirs) { - if (sourceDirs.size() > 0) { - toExecute.createArgument().setValue("-sourcepath"); - toExecute.createArgument().setPath(sourceDirs); - } - } - - private void generalJavadocArguments(final Commandline toExecute) { - if (doctitle != null) { - toExecute.createArgument().setValue("-doctitle"); - toExecute.createArgument().setValue(expand(doctitle.getText())); - } - if (header != null) { - toExecute.createArgument().setValue("-header"); - toExecute.createArgument().setValue(expand(header.getText())); - } - if (footer != null) { - toExecute.createArgument().setValue("-footer"); - toExecute.createArgument().setValue(expand(footer.getText())); - } - if (bottom != null) { - toExecute.createArgument().setValue("-bottom"); - toExecute.createArgument().setValue(expand(bottom.getText())); - } - - if (classpath == null) { - classpath = (new Path(getProject())).concatSystemClasspath("last"); - } else { - classpath = classpath.concatSystemClasspath("ignore"); - } - - if (classpath.size() > 0) { - toExecute.createArgument().setValue("-classpath"); - toExecute.createArgument().setPath(classpath); - } - - if (version && doclet == null) { - toExecute.createArgument().setValue("-version"); - } - if (author && doclet == null) { - toExecute.createArgument().setValue("-author"); - } - - if (doclet == null && destDir == null) { - throw new BuildException("destdir attribute must be set!"); - } - } - - private void doDoclet(final Commandline toExecute) { - if (doclet != null) { - if (doclet.getName() == null) { - throw new BuildException("The doclet name must be " - + "specified.", getLocation()); - } else { - toExecute.createArgument().setValue("-doclet"); - toExecute.createArgument().setValue(doclet.getName()); - if (doclet.getPath() != null) { - final Path docletPath - = doclet.getPath().concatSystemClasspath("ignore"); - if (docletPath.size() != 0) { - toExecute.createArgument().setValue("-docletpath"); - toExecute.createArgument().setPath(docletPath); - } - } - for (final Enumeration<DocletParam> e = doclet.getParams(); - e.hasMoreElements();) { - final DocletParam param = e.nextElement(); - if (param.getName() == null) { - throw new BuildException("Doclet parameters must " - + "have a name"); - } - - toExecute.createArgument().setValue(param.getName()); - if (param.getValue() != null) { - toExecute.createArgument() - .setValue(param.getValue()); - } - } - } - } - } - - private void writeExternalArgs(final Commandline toExecute) { - // If using an external file, write the command line options to it - File optionsTmpFile = null; - BufferedWriter optionsListWriter = null; - try { - optionsTmpFile = FILE_UTILS.createTempFile( - "javadocOptions", "", null, true, true); - final String[] listOpt = toExecute.getArguments(); - toExecute.clearArgs(); - toExecute.createArgument().setValue( - "@" + optionsTmpFile.getAbsolutePath()); - optionsListWriter = new BufferedWriter( - new FileWriter(optionsTmpFile.getAbsolutePath(), true)); - for (int i = 0; i < listOpt.length; i++) { - final String string = listOpt[i]; - if (string.startsWith("-J-")) { - toExecute.createArgument().setValue(string); - } else { - if (string.startsWith("-")) { - optionsListWriter.write(string); - optionsListWriter.write(" "); - } else { - optionsListWriter.write(quoteString(string)); - optionsListWriter.newLine(); - } - } - } - optionsListWriter.close(); - } catch (final IOException ex) { - if (optionsTmpFile != null) { - optionsTmpFile.delete(); - } - throw new BuildException( - "Error creating or writing temporary file for javadoc options", - ex, getLocation()); - } finally { - FileUtils.close(optionsListWriter); - } - } - - private void doBootPath(final Commandline toExecute) { - Path bcp = new Path(getProject()); - if (bootclasspath != null) { - bcp.append(bootclasspath); - } - bcp = bcp.concatSystemBootClasspath("ignore"); - if (bcp.size() > 0) { - toExecute.createArgument().setValue("-bootclasspath"); - toExecute.createArgument().setPath(bcp); - } - } - - private void doLinks(final Commandline toExecute) { - if (links.size() != 0) { - for (final Enumeration<LinkArgument> e = links.elements(); e.hasMoreElements();) { - final LinkArgument la = e.nextElement(); - - if (la.getHref() == null || la.getHref().length() == 0) { - log("No href was given for the link - skipping", - Project.MSG_VERBOSE); - continue; - } - String link = null; - if (la.shouldResolveLink()) { - final File hrefAsFile = - getProject().resolveFile(la.getHref()); - if (hrefAsFile.exists()) { - try { - link = FILE_UTILS.getFileURL(hrefAsFile) - .toExternalForm(); - } catch (final MalformedURLException ex) { - // should be impossible - log("Warning: link location was invalid " - + hrefAsFile, Project.MSG_WARN); - } - } - } - if (link == null) { - // is the href a valid URL - try { - final URL base = new URL("file://."); - new URL(base, la.getHref()); - link = la.getHref(); - } catch (final MalformedURLException mue) { - // ok - just skip - log("Link href \"" + la.getHref() - + "\" is not a valid url - skipping link", - Project.MSG_WARN); - continue; - } - } - - if (la.isLinkOffline()) { - final File packageListLocation = la.getPackagelistLoc(); - URL packageListURL = la.getPackagelistURL(); - if (packageListLocation == null - && packageListURL == null) { - throw new BuildException("The package list" - + " location for link " - + la.getHref() - + " must be provided " - + "because the link is " - + "offline"); - } - if (packageListLocation != null) { - final File packageListFile = - new File(packageListLocation, "package-list"); - if (packageListFile.exists()) { - try { - packageListURL = - FILE_UTILS.getFileURL(packageListLocation); - } catch (final MalformedURLException ex) { - log("Warning: Package list location was " - + "invalid " + packageListLocation, - Project.MSG_WARN); - } - } else { - log("Warning: No package list was found at " - + packageListLocation, Project.MSG_VERBOSE); - } - } - if (packageListURL != null) { - toExecute.createArgument().setValue("-linkoffline"); - toExecute.createArgument().setValue(link); - toExecute.createArgument() - .setValue(packageListURL.toExternalForm()); - } - } else { - toExecute.createArgument().setValue("-link"); - toExecute.createArgument().setValue(link); - } - } - } - } - - private void doGroup(final Commandline toExecute) { - // add the single group arguments - // Javadoc 1.2 rules: - // Multiple -group args allowed. - // Each arg includes 3 strings: -group [name] [packagelist]. - // Elements in [packagelist] are colon-delimited. - // An element in [packagelist] may end with the * wildcard. - - // Ant javadoc task rules for group attribute: - // Args are comma-delimited. - // Each arg is 2 space-delimited strings. - // E.g., group="XSLT_Packages org.apache.xalan.xslt*, - // XPath_Packages org.apache.xalan.xpath*" - if (group != null) { - final StringTokenizer tok = new StringTokenizer(group, ",", false); - while (tok.hasMoreTokens()) { - final String grp = tok.nextToken().trim(); - final int space = grp.indexOf(" "); - if (space > 0) { - final String name = grp.substring(0, space); - final String pkgList = grp.substring(space + 1); - toExecute.createArgument().setValue("-group"); - toExecute.createArgument().setValue(name); - toExecute.createArgument().setValue(pkgList); - } - } - } - } - - // add the group arguments - private void doGroups(final Commandline toExecute) { - if (groups.size() != 0) { - for (final Enumeration<GroupArgument> e = groups.elements(); e.hasMoreElements();) { - final GroupArgument ga = e.nextElement(); - final String title = ga.getTitle(); - final String packages = ga.getPackages(); - if (title == null || packages == null) { - throw new BuildException("The title and packages must " - + "be specified for group " - + "elements."); - } - toExecute.createArgument().setValue("-group"); - toExecute.createArgument().setValue(expand(title)); - toExecute.createArgument().setValue(packages); - } - } - } - - // Do java1.4 arguments - private void doJava14(final Commandline toExecute) { - for (final Enumeration<Object> e = tags.elements(); e.hasMoreElements();) { - final Object element = e.nextElement(); - if (element instanceof TagArgument) { - final TagArgument ta = (TagArgument) element; - final File tagDir = ta.getDir(getProject()); - if (tagDir == null) { - // The tag element is not used as a fileset, - // but specifies the tag directly. - toExecute.createArgument().setValue ("-tag"); - toExecute.createArgument() - .setValue (ta.getParameter()); - } else { - // The tag element is used as a - // fileset. Parse all the files and create - // -tag arguments. - final DirectoryScanner tagDefScanner = - ta.getDirectoryScanner(getProject()); - final String[] files = tagDefScanner.getIncludedFiles(); - for (int i = 0; i < files.length; i++) { - final File tagDefFile = new File(tagDir, files[i]); - try { - final BufferedReader in - = new BufferedReader( - new FileReader(tagDefFile) - ); - String line = null; - while ((line = in.readLine()) != null) { - toExecute.createArgument() - .setValue("-tag"); - toExecute.createArgument() - .setValue(line); - } - in.close(); - } catch (final IOException ioe) { - throw new BuildException( - "Couldn't read " - + " tag file from " - + tagDefFile.getAbsolutePath(), ioe); - } - } - } - } else { - final ExtensionInfo tagletInfo = (ExtensionInfo) element; - toExecute.createArgument().setValue("-taglet"); - toExecute.createArgument().setValue(tagletInfo - .getName()); - if (tagletInfo.getPath() != null) { - final Path tagletPath = tagletInfo.getPath() - .concatSystemClasspath("ignore"); - if (tagletPath.size() != 0) { - toExecute.createArgument() - .setValue("-tagletpath"); - toExecute.createArgument().setPath(tagletPath); - } - } - } - } - - final String sourceArg = source != null ? source - : getProject().getProperty(MagicNames.BUILD_JAVAC_SOURCE); - if (sourceArg != null) { - toExecute.createArgument().setValue("-source"); - toExecute.createArgument().setValue(sourceArg); - } - - if (linksource && doclet == null) { - toExecute.createArgument().setValue("-linksource"); - } - if (noqualifier != null && doclet == null) { - toExecute.createArgument().setValue("-noqualifier"); - toExecute.createArgument().setValue(noqualifier); - } - } - - private void doDocFilesSubDirs(final Commandline toExecute) { - if (docFilesSubDirs) { - toExecute.createArgument().setValue("-docfilessubdirs"); - if (excludeDocFilesSubDir != null - && excludeDocFilesSubDir.trim().length() > 0) { - toExecute.createArgument().setValue("-excludedocfilessubdir"); - toExecute.createArgument().setValue(excludeDocFilesSubDir); - } - } - } - - private void doSourceAndPackageNames( - final Commandline toExecute, - final Vector<String> packagesToDoc, - final Vector<SourceFile> sourceFilesToDoc, - final boolean useExternalFile, - final File tmpList, - final BufferedWriter srcListWriter) - throws IOException { - for (final String packageName : packagesToDoc) { - if (useExternalFile) { - srcListWriter.write(packageName); - srcListWriter.newLine(); - } else { - toExecute.createArgument().setValue(packageName); - } - } - - for (final SourceFile sf : sourceFilesToDoc) { - final String sourceFileName = sf.getFile().getAbsolutePath(); - if (useExternalFile) { - // TODO what is the following doing? - // should it run if !javadoc4 && executable != null? - if (sourceFileName.indexOf(" ") > -1) { - String name = sourceFileName; - if (File.separatorChar == '\\') { - name = sourceFileName.replace(File.separatorChar, '/'); - } - srcListWriter.write("\"" + name + "\""); - } else { - srcListWriter.write(sourceFileName); - } - srcListWriter.newLine(); - } else { - toExecute.createArgument().setValue(sourceFileName); - } - } - } - - /** - * Quote a string to place in a @ file. - * @param str the string to quote - * @return the quoted string, if there is no need to quote the string, - * return the original string. - */ - private String quoteString(final String str) { - if (!containsWhitespace(str) - && str.indexOf('\'') == -1 - && str.indexOf('"') == -1) { - return str; - } - if (str.indexOf('\'') == -1) { - return quoteString(str, '\''); - } else { - return quoteString(str, '"'); - } - } - - private boolean containsWhitespace(final String s) { - final int len = s.length(); - for (int i = 0; i < len; i++) { - if (Character.isWhitespace(s.charAt(i))) { - return true; - } - } - return false; - } - - private String quoteString(final String str, final char delim) { - final StringBuffer buf = new StringBuffer(str.length() * 2); - buf.append(delim); - final int len = str.length(); - boolean lastCharWasCR = false; - for (int i = 0; i < len; i++) { - final char c = str.charAt(i); - if (c == delim) { // can't put the non-constant delim into a case - buf.append('\\').append(c); - lastCharWasCR = false; - } else { - switch (c) { - case '\\': - buf.append("\\\\"); - lastCharWasCR = false; - break; - case '\r': - // insert a line continuation marker - buf.append("\\\r"); - lastCharWasCR = true; - break; - case '\n': - // insert a line continuation marker unless this - // is a \r\n sequence in which case \r already has - // created the marker - if (!lastCharWasCR) { - buf.append("\\\n"); - } else { - buf.append("\n"); - } - lastCharWasCR = false; - break; - default: - buf.append(c); - lastCharWasCR = false; - break; - } - } - } - buf.append(delim); - return buf.toString(); - } - - /** - * Add the files matched by the nested source files to the Vector - * as SourceFile instances. - * - * @since 1.7 - */ - private void addSourceFiles(final Vector<SourceFile> sf) { - final Iterator<ResourceCollection> e = nestedSourceFiles.iterator(); - while (e.hasNext()) { - ResourceCollection rc = e.next(); - if (!rc.isFilesystemOnly()) { - throw new BuildException("only file system based resources are" - + " supported by javadoc"); - } - if (rc instanceof FileSet) { - final FileSet fs = (FileSet) rc; - if (!fs.hasPatterns() && !fs.hasSelectors()) { - final FileSet fs2 = (FileSet) fs.clone(); - fs2.createInclude().setName("**/*.java"); - if (includeNoSourcePackages) { - fs2.createInclude().setName("**/package.html"); - } - rc = fs2; - } - } - for (final Resource r : rc) { - sf.addElement(new SourceFile(r.as(FileProvider.class).getFile())); - } - } - } - - /** - * Add the directories matched by the nested dirsets to the Vector - * and the base directories of the dirsets to the Path. It also - * handles the packages and excludepackages attributes and - * elements. - * - * @since 1.5 - */ - private void parsePackages(final Vector<String> pn, final Path sp) { - final HashSet<String> addedPackages = new HashSet<String>(); - @SuppressWarnings("unchecked") - final Vector<DirSet> dirSets = (Vector<DirSet>) packageSets.clone(); - - // for each sourcePath entry, add a directoryset with includes - // taken from packagenames attribute and nested package - // elements and excludes taken from excludepackages attribute - // and nested excludepackage elements - if (sourcePath != null) { - final PatternSet ps = new PatternSet(); - ps.setProject(getProject()); - if (packageNames.size() > 0) { - final Enumeration<PackageName> e = packageNames.elements(); - while (e.hasMoreElements()) { - final PackageName p = e.nextElement(); - String pkg = p.getName().replace('.', '/'); - if (pkg.endsWith("*")) { - pkg += "*"; - } - ps.createInclude().setName(pkg); - } - } else { - ps.createInclude().setName("**"); - } - - final Enumeration<PackageName> e = excludePackageNames.elements(); - while (e.hasMoreElements()) { - final PackageName p = e.nextElement(); - String pkg = p.getName().replace('.', '/'); - if (pkg.endsWith("*")) { - pkg += "*"; - } - ps.createExclude().setName(pkg); - } - - - final String[] pathElements = sourcePath.list(); - for (int i = 0; i < pathElements.length; i++) { - final File dir = new File(pathElements[i]); - if (dir.isDirectory()) { - final DirSet ds = new DirSet(); - ds.setProject(getProject()); - ds.setDefaultexcludes(useDefaultExcludes); - ds.setDir(dir); - ds.createPatternSet().addConfiguredPatternset(ps); - dirSets.addElement(ds); - } else { - log("Skipping " + pathElements[i] - + " since it is no directory.", Project.MSG_WARN); - } - } - } - - final Enumeration<DirSet> e = dirSets.elements(); - while (e.hasMoreElements()) { - final DirSet ds = e.nextElement(); - final File baseDir = ds.getDir(getProject()); - log("scanning " + baseDir + " for packages.", Project.MSG_DEBUG); - final DirectoryScanner dsc = ds.getDirectoryScanner(getProject()); - final String[] dirs = dsc.getIncludedDirectories(); - boolean containsPackages = false; - for (int i = 0; i < dirs.length; i++) { - // are there any java files in this directory? - final File pd = new File(baseDir, dirs[i]); - final String[] files = pd.list(new FilenameFilter () { - public boolean accept(final File dir1, final String name) { - return name.endsWith(".java") - || (includeNoSourcePackages - && name.equals("package.html")); - } - }); - - if (files.length > 0) { - if ("".equals(dirs[i])) { - log(baseDir - + " contains source files in the default package," - + " you must specify them as source files" - + " not packages.", - Project.MSG_WARN); - } else { - containsPackages = true; - final String packageName = - dirs[i].replace(File.separatorChar, '.'); - if (!addedPackages.contains(packageName)) { - addedPackages.add(packageName); - pn.addElement(packageName); - } - } - } - } - if (containsPackages) { - // We don't need to care for duplicates here, - // Path.list does it for us. - sp.createPathElement().setLocation(baseDir); - } else { - log(baseDir + " doesn\'t contain any packages, dropping it.", - Project.MSG_VERBOSE); - } - } - } - - private void postProcessGeneratedJavadocs() throws IOException { - if (!postProcessGeneratedJavadocs) { - return; - } - if (destDir != null && !destDir.isDirectory()) { - log("No javadoc created, no need to post-process anything", - Project.MSG_VERBOSE); - return; - } - final String fixData; - final InputStream in = Javadoc.class - .getResourceAsStream("javadoc-frame-injections-fix.txt"); - if (in == null) { - throw new FileNotFoundException("Missing resource " - + "'javadoc-frame-injections-fix.txt' in " - + "classpath."); - } - try { - fixData = - fixLineFeeds(FileUtils - .readFully(new InputStreamReader(in, "US-ASCII"))) - .trim(); - } finally { - FileUtils.close(in); - } - - final DirectoryScanner ds = new DirectoryScanner(); - ds.setBasedir(destDir); - ds.setCaseSensitive(false); - ds.setIncludes(new String[] { - "**/index.html", "**/index.htm", "**/toc.html", "**/toc.htm" - }); - ds.addDefaultExcludes(); - ds.scan(); - int patched = 0; - for (final String f : ds.getIncludedFiles()) { - patched += postProcess(new File(destDir, f), fixData); - } - if (patched > 0) { - log("Patched " + patched + " link injection vulnerable javadocs", - Project.MSG_INFO); - } - } - - private int postProcess(final File file, final String fixData) throws IOException { - final String enc = docEncoding != null ? docEncoding - : FILE_UTILS.getDefaultEncoding(); - // we load the whole file as one String (toc/index files are - // generally small, because they only contain frameset declaration): - final InputStream fin = new FileInputStream(file); - String fileContents; - try { - fileContents = - fixLineFeeds(FileUtils - .safeReadFully(new InputStreamReader(fin, enc))); - } finally { - FileUtils.close(fin); - } - - // check if file may be vulnerable because it was not - // patched with "validURL(url)": - if (fileContents.indexOf("function validURL(url) {") < 0) { - // we need to patch the file! - final String patchedFileContents = patchContent(fileContents, fixData); - if (!patchedFileContents.equals(fileContents)) { - final FileOutputStream fos = new FileOutputStream(file); - try { - final OutputStreamWriter w = new OutputStreamWriter(fos, enc); - w.write(patchedFileContents); - w.close(); - return 1; - } finally { - FileUtils.close(fos); - } - } - } - return 0; - } - - private String fixLineFeeds(final String orig) { - return orig.replace("\r\n", "\n") - .replace("\n", StringUtils.LINE_SEP); - } - - private String patchContent(final String fileContents, final String fixData) { - // using regexes here looks like overkill - final int start = fileContents.indexOf(LOAD_FRAME); - if (start >= 0) { - return fileContents.substring(0, start) + fixData - + fileContents.substring(start + LOAD_FRAME_LEN); - } - return fileContents; - } - - private class JavadocOutputStream extends LogOutputStream { - JavadocOutputStream(final int level) { - super(Javadoc.this, level); - } - - // - // Override the logging of output in order to filter out Generating - // messages. Generating messages are set to a priority of VERBOSE - // unless they appear after what could be an informational message. - // - private String queuedLine = null; - private boolean sawWarnings = false; - - @Override - protected void processLine(final String line, final int messageLevel) { - if (line.contains("warning")) { - sawWarnings = true; - } - if (messageLevel == Project.MSG_INFO - && line.startsWith("Generating ")) { - if (queuedLine != null) { - super.processLine(queuedLine, Project.MSG_VERBOSE); - } - queuedLine = line; - } else { - if (queuedLine != null) { - if (line.startsWith("Building ")) { - super.processLine(queuedLine, Project.MSG_VERBOSE); - } else { - super.processLine(queuedLine, Project.MSG_INFO); - } - queuedLine = null; - } - super.processLine(line, messageLevel); - } - } - - - protected void logFlush() { - if (queuedLine != null) { - super.processLine(queuedLine, Project.MSG_VERBOSE); - queuedLine = null; - } - } - - public boolean sawWarnings() { - return sawWarnings; - } - } - - /** - * Convenience method to expand properties. - * @param content the string to expand - * @return the converted string - */ - protected String expand(final String content) { - return getProject().replaceProperties(content); - } - -} |