aboutsummaryrefslogtreecommitdiffstats
path: root/framework/src/ant/apache-ant-1.9.6/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
diff options
context:
space:
mode:
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.java2624
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 &quot;.*&quot; 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 &quot;use&quot; 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 &lt;title&gt; 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=&quot;**&#47;*.java&quot;</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);
- }
-
-}