FileDocCategorySizeDatePackage
Javadoc.javaAPI DocApache Ant 1.7076777Wed Dec 13 06:16:24 GMT 2006org.apache.tools.ant.taskdefs

Javadoc

public class Javadoc extends org.apache.tools.ant.Task
Generates Javadoc documentation for a collection of source code.

Current known limitations are:

  • patterns must be of the form "xxx.*", every other pattern doesn't work.
  • there is no control on arguments sanity since they are left to the Javadoc implementation.

If no doclet is set, then the version and author are by default "yes".

Note: This task is run on another VM because the Javadoc code calls System.exit() which would break Ant functionality.

since
Ant 1.1
ant.task
category="java"

Fields Summary
private static final org.apache.tools.ant.util.FileUtils
FILE_UTILS
private org.apache.tools.ant.types.Commandline
cmd
The command line built to execute Javadoc.
private boolean
failOnError
Flag which indicates if the task should fail if there is a Javadoc error.
private org.apache.tools.ant.types.Path
sourcePath
private File
destDir
private Vector
sourceFiles
private Vector
packageNames
private Vector
excludePackageNames
private boolean
author
private boolean
version
private DocletInfo
doclet
private org.apache.tools.ant.types.Path
classpath
private org.apache.tools.ant.types.Path
bootclasspath
private String
group
private String
packageList
private Vector
links
private Vector
groups
private Vector
tags
private boolean
useDefaultExcludes
private Html
doctitle
private Html
header
private Html
footer
private Html
bottom
private boolean
useExternalFile
private String
source
private boolean
linksource
private boolean
breakiterator
private String
noqualifier
private boolean
includeNoSourcePackages
private boolean
old
private String
executable
private ResourceCollectionContainer
nestedSourceFiles
private Vector
packageSets
static final String[]
SCOPE_ELEMENTS
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.
Constructors Summary
Methods Summary
private voidaddArgIf(boolean b, java.lang.String arg)
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.


                                         
          
        if (b) {
            cmd.createArgument().setValue(arg);
        }
    
private voidaddArgIfNotEmpty(java.lang.String key, java.lang.String value)
Utility method to add a Javadoc argument.

param
key the argument name.
param
value the argument 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);
        }
    
public voidaddBottom(org.apache.tools.ant.taskdefs.Javadoc$Html text)
Set the text to be placed at the bottom of each output file.

param
text the bottom text.

        bottom = text;
    
public voidaddDoctitle(org.apache.tools.ant.taskdefs.Javadoc$Html text)
Add a document title to use for the overview page.

param
text the HTML element containing the document title.

        doctitle = text;
    
public voidaddExcludePackage(org.apache.tools.ant.taskdefs.Javadoc$PackageName pn)
Add a package to be excluded from the Javadoc run.

param
pn the name of the package (wildcards are not permitted).

        excludePackageNames.addElement(pn);
    
public voidaddFileset(org.apache.tools.ant.types.FileSet fs)
Adds a fileset.

All included files will be added as sourcefiles. The task will automatically add includes="**/*.java" to the fileset.

param
fs a file set
since
1.5

        createSourceFiles().add(fs);
    
public voidaddFooter(org.apache.tools.ant.taskdefs.Javadoc$Html text)
Set the footer text to be placed at the bottom of each output file.

param
text the footer text.

        footer = text;
    
public voidaddHeader(org.apache.tools.ant.taskdefs.Javadoc$Html text)
Set the header text to be placed at the top of each output file.

param
text the header text

        header = text;
    
public voidaddPackage(org.apache.tools.ant.taskdefs.Javadoc$PackageName 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.

        packageNames.addElement(pn);
    
public voidaddPackageset(org.apache.tools.ant.types.DirSet packageSet)
Adds a packageset.

All included directories will be translated into package names be converting the directory separator into dots.

param
packageSet a directory set
since
1.5

        packageSets.addElement(packageSet);
    
public voidaddSource(org.apache.tools.ant.taskdefs.Javadoc$SourceFile sf)
Add a single source file.

param
sf the source file to be processed.

        sourceFiles.addElement(sf);
    
private voidaddSourceFiles(java.util.Vector sf)
Add the files matched by the nested source files to the Vector as SourceFile instances.

since
1.7

        Iterator e = nestedSourceFiles.iterator();
        while (e.hasNext()) {
            ResourceCollection rc = (ResourceCollection) e.next();
            if (!rc.isFilesystemOnly()) {
                throw new BuildException("only file system based resources are"
                                         + " supported by javadoc");
            }
            if (rc instanceof FileSet) {
                FileSet fs = (FileSet) rc;
                if (!fs.hasPatterns() && !fs.hasSelectors()) {
                    fs = (FileSet) fs.clone();
                    fs.createInclude().setName("**/*.java");
                    if (includeNoSourcePackages) {
                        fs.createInclude().setName("**/package.html");
                    }
                }
            }
            Iterator iter = rc.iterator();
            while (iter.hasNext()) {
                sf.addElement(new SourceFile(((FileResource) iter.next())
                                             .getFile()));
            }
        }
    
public voidaddTaglet(org.apache.tools.ant.taskdefs.Javadoc$ExtensionInfo tagletInfo)
Add a taglet

param
tagletInfo information about the taglet.

        tags.addElement(tagletInfo);
    
public Commandline.ArgumentcreateArg()
Adds a command-line argument.

return
a command-line argument to configure
since
Ant 1.6

        return cmd.createArgument();
    
public org.apache.tools.ant.types.PathcreateBootclasspath()
Create a Path to be configured with the boot classpath

return
a new Path instance to be configured with the boot classpath.

        if (bootclasspath == null) {
            bootclasspath = new Path(getProject());
        }
        return bootclasspath.createPath();
    
public org.apache.tools.ant.types.PathcreateClasspath()
Create a Path to be configured with the classpath to use

return
a new Path instance to be configured with the classpath.

        if (classpath == null) {
            classpath = new Path(getProject());
        }
        return classpath.createPath();
    
public org.apache.tools.ant.taskdefs.Javadoc$DocletInfocreateDoclet()
Create a doclet to be used in the documentation generation.

return
a new DocletInfo instance to be configured.

        if (doclet == null) {
            doclet = new DocletInfo();
        }
        return doclet;
    
public org.apache.tools.ant.taskdefs.Javadoc$GroupArgumentcreateGroup()
Separates packages on the overview page into whatever groups you specify, one group per table.

return
a group argument to be configured

        GroupArgument ga = new GroupArgument();
        groups.addElement(ga);
        return ga;
    
public org.apache.tools.ant.taskdefs.Javadoc$LinkArgumentcreateLink()
Create link to Javadoc output at the given URL.

return
link argument to configure

        LinkArgument la = new LinkArgument();
        links.addElement(la);
        return la;
    
public org.apache.tools.ant.taskdefs.Javadoc$ResourceCollectionContainercreateSourceFiles()
Adds a container for resource collections.

All included files will be added as sourcefiles.

return
the source files to configure.
since
1.7

        return nestedSourceFiles;
    
public org.apache.tools.ant.types.PathcreateSourcepath()
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.

        if (sourcePath == null) {
            sourcePath = new Path(getProject());
        }
        return sourcePath.createPath();
    
public org.apache.tools.ant.taskdefs.Javadoc$TagArgumentcreateTag()
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

        TagArgument ta = new TagArgument();
        tags.addElement (ta);
        return ta;
    
public voidexecute()
Execute the task.

throws
BuildException on error

        if ("javadoc2".equals(getTaskType())) {
            log("Warning: the task name <javadoc2> is deprecated. Use <javadoc> instead.",
                Project.MSG_WARN);
        }

        // Whether *this VM* is 1.4+ (but also check executable != null).
        boolean javadoc4 =
            !JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_2)
            && !JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_3);
        boolean javadoc5 = javadoc4
            && !JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_4);

        Vector packagesToDoc = new Vector();
        Path sourceDirs = new Path(getProject());

        if (packageList != null && sourcePath == null) {
            String msg = "sourcePath attribute must be set when "
                + "specifying packagelist.";
            throw new BuildException(msg);
        }

        if (sourcePath != null) {
            sourceDirs.addExisting(sourcePath);
        }

        parsePackages(packagesToDoc, sourceDirs);

        if (packagesToDoc.size() != 0 && sourceDirs.size() == 0) {
            String msg = "sourcePath attribute must be set when "
                + "specifying package names.";
            throw new BuildException(msg);
        }

        Vector sourceFilesToDoc = (Vector) sourceFiles.clone();
        addSourceFiles(sourceFilesToDoc);

        if (packageList == null && packagesToDoc.size() == 0
            && sourceFilesToDoc.size() == 0) {
            throw new BuildException("No source files and no packages have "
                                     + "been specified.");
        }

        log("Generating Javadoc", Project.MSG_INFO);

        Commandline toExecute = (Commandline) cmd.clone();
        if (executable != null) {
            toExecute.setExecutable(executable);
        } else {
            toExecute.setExecutable(JavaEnvUtils.getJdkExecutable("javadoc"));
        }

        // ------------------------------------------ general Javadoc arguments
        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 (sourceDirs.size() > 0) {
            toExecute.createArgument().setValue("-sourcepath");
            toExecute.createArgument().setPath(sourceDirs);
        }

        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!");
        }

        // ---------------------------- javadoc2 arguments for default doclet

        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) {
                    Path docletPath
                        = doclet.getPath().concatSystemClasspath("ignore");
                    if (docletPath.size() != 0) {
                        toExecute.createArgument().setValue("-docletpath");
                        toExecute.createArgument().setPath(docletPath);
                    }
                }
                for (Enumeration e = doclet.getParams();
                     e.hasMoreElements();) {
                    DocletParam param = (DocletParam) 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());
                    }
                }
            }
        }
        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);
        }

        // add the links arguments
        if (links.size() != 0) {
            for (Enumeration e = links.elements(); e.hasMoreElements();) {
                LinkArgument la = (LinkArgument) 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()) {
                    File hrefAsFile =
                        getProject().resolveFile(la.getHref());
                    if (hrefAsFile.exists()) {
                        try {
                            link = FILE_UTILS.getFileURL(hrefAsFile)
                                .toExternalForm();
                        } catch (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 {
                        URL base = new URL("file://.");
                        new URL(base, la.getHref());
                        link = la.getHref();
                    } catch (MalformedURLException mue) {
                        // ok - just skip
                        log("Link href \"" + la.getHref()
                            + "\" is not a valid url - skipping link",
                            Project.MSG_WARN);
                        continue;
                    }
                }

                if (la.isLinkOffline()) {
                    File packageListLocation = la.getPackagelistLoc();
                    if (packageListLocation == null) {
                        throw new BuildException("The package list"
                                                 + " location for link "
                                                 + la.getHref()
                                                 + " must be provided "
                                                 + "because the link is "
                                                 + "offline");
                    }
                    File packageListFile =
                        new File(packageListLocation, "package-list");
                    if (packageListFile.exists()) {
                        try {
                            String packageListURL =
                                FILE_UTILS.getFileURL(packageListLocation)
                                .toExternalForm();
                            toExecute.createArgument()
                                .setValue("-linkoffline");
                            toExecute.createArgument()
                                .setValue(link);
                            toExecute.createArgument()
                                .setValue(packageListURL);
                        } catch (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);
                    }
                } else {
                    toExecute.createArgument().setValue("-link");
                    toExecute.createArgument().setValue(link);
                }
            }
        }

        // 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) {
            StringTokenizer tok = new StringTokenizer(group, ",", false);
            while (tok.hasMoreTokens()) {
                String grp = tok.nextToken().trim();
                int space = grp.indexOf(" ");
                if (space > 0) {
                    String name = grp.substring(0, space);
                    String pkgList = grp.substring(space + 1);
                    toExecute.createArgument().setValue("-group");
                    toExecute.createArgument().setValue(name);
                    toExecute.createArgument().setValue(pkgList);
                }
            }
        }

        // add the group arguments
        if (groups.size() != 0) {
            for (Enumeration e = groups.elements(); e.hasMoreElements();) {
                GroupArgument ga = (GroupArgument) e.nextElement();
                String title = ga.getTitle();
                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);
            }
        }

        // Javadoc 1.4 parameters
        if (javadoc4 || executable != null) {
            for (Enumeration e = tags.elements(); e.hasMoreElements();) {
                Object element = e.nextElement();
                if (element instanceof TagArgument) {
                    TagArgument ta = (TagArgument) element;
                    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.
                        DirectoryScanner tagDefScanner =
                            ta.getDirectoryScanner(getProject());
                        String[] files = tagDefScanner.getIncludedFiles();
                        for (int i = 0; i < files.length; i++) {
                            File tagDefFile = new File(tagDir, files[i]);
                            try {
                                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 (IOException ioe) {
                                throw new BuildException("Couldn't read "
                                    + " tag file from "
                                    + tagDefFile.getAbsolutePath(), ioe);
                            }
                        }
                    }
                } else {
                    ExtensionInfo tagletInfo = (ExtensionInfo) element;
                    toExecute.createArgument().setValue("-taglet");
                    toExecute.createArgument().setValue(tagletInfo
                                                        .getName());
                    if (tagletInfo.getPath() != null) {
                        Path tagletPath = tagletInfo.getPath()
                            .concatSystemClasspath("ignore");
                        if (tagletPath.size() != 0) {
                            toExecute.createArgument()
                                .setValue("-tagletpath");
                            toExecute.createArgument().setPath(tagletPath);
                        }
                    }
                }
            }

            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 (breakiterator && (doclet == null || javadoc5)) {
                toExecute.createArgument().setValue("-breakiterator");
            }
            if (noqualifier != null && doclet == null) {
                toExecute.createArgument().setValue("-noqualifier");
                toExecute.createArgument().setValue(noqualifier);
            }
        } else {
            // Not 1.4+.
            if (!tags.isEmpty()) {
                log("-tag and -taglet options not supported on Javadoc < 1.4",
                     Project.MSG_VERBOSE);
            }
            if (source != null) {
                log("-source option not supported on Javadoc < 1.4",
                     Project.MSG_VERBOSE);
            }
            if (linksource) {
                log("-linksource option not supported on Javadoc < 1.4",
                     Project.MSG_VERBOSE);
            }
            if (breakiterator) {
                log("-breakiterator option not supported on Javadoc < 1.4",
                     Project.MSG_VERBOSE);
            }
            if (noqualifier != null) {
                log("-noqualifier option not supported on Javadoc < 1.4",
                     Project.MSG_VERBOSE);
            }
        }
        // Javadoc 1.2/1.3 parameters:
        if (!javadoc4 || executable != null) {
            if (old) {
                toExecute.createArgument().setValue("-1.1");
            }
        } else {
            if (old) {
                log("Javadoc 1.4 doesn't support the -1.1 switch anymore",
                    Project.MSG_WARN);
            }
        }
        // If using an external file, write the command line options to it
        if (useExternalFile && javadoc4) {
            writeExternalArgs(toExecute);
        }

        File tmpList = null;
        PrintWriter srcListWriter = null;

        try {

            /**
             * Write sourcefiles and package names to a temporary file
             * if requested.
             */
            if (useExternalFile) {
                if (tmpList == null) {
                    tmpList = FILE_UTILS.createTempFile("javadoc", "", null);
                    tmpList.deleteOnExit();
                    toExecute.createArgument()
                        .setValue("@" + tmpList.getAbsolutePath());
                }
                srcListWriter = new PrintWriter(
                                    new FileWriter(tmpList.getAbsolutePath(),
                                                   true));
            }

            Enumeration e = packagesToDoc.elements();
            while (e.hasMoreElements()) {
                String packageName = (String) e.nextElement();
                if (useExternalFile) {
                    srcListWriter.println(packageName);
                } else {
                    toExecute.createArgument().setValue(packageName);
                }
            }

            e = sourceFilesToDoc.elements();
            while (e.hasMoreElements()) {
                SourceFile sf = (SourceFile) e.nextElement();
                String sourceFileName = sf.getFile().getAbsolutePath();
                if (useExternalFile) {
                    // XXX what is the following doing?
                    //     should it run if !javadoc4 && executable != null?
                    if (javadoc4 && sourceFileName.indexOf(" ") > -1) {
                        String name = sourceFileName;
                        if (File.separatorChar == '\\") {
                            name = sourceFileName.replace(File.separatorChar, '/");
                        }
                        srcListWriter.println("\"" + name + "\"");
                    } else {
                        srcListWriter.println(sourceFileName);
                    }
                } else {
                    toExecute.createArgument().setValue(sourceFileName);
                }
            }

        } catch (IOException e) {
            tmpList.delete();
            throw new BuildException("Error creating temporary file",
                                     e, getLocation());
        } finally {
            if (srcListWriter != null) {
                srcListWriter.close();
            }
        }

        if (packageList != null) {
            toExecute.createArgument().setValue("@" + packageList);
        }
        log(toExecute.describeCommand(), Project.MSG_VERBOSE);

        log("Javadoc execution", Project.MSG_INFO);

        JavadocOutputStream out = new JavadocOutputStream(Project.MSG_INFO);
        JavadocOutputStream err = new JavadocOutputStream(Project.MSG_WARN);
        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());
            int ret = exe.execute();
            if (ret != 0 && failOnError) {
                throw new BuildException("Javadoc returned " + ret,
                                         getLocation());
            }
        } catch (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 (IOException e) {
                // ignore
            }
        }
    
protected java.lang.Stringexpand(java.lang.String content)
Convenience method to expand properties.

param
content the string to expand
return
the converted string

        return getProject().replaceProperties(content);
    
private voidparsePackages(java.util.Vector pn, org.apache.tools.ant.types.Path sp)
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

        Vector addedPackages = new Vector();
        Vector dirSets = (Vector) 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) {
            PatternSet ps = new PatternSet();
            if (packageNames.size() > 0) {
                Enumeration e = packageNames.elements();
                while (e.hasMoreElements()) {
                    PackageName p = (PackageName) e.nextElement();
                    String pkg = p.getName().replace('.", '/");
                    if (pkg.endsWith("*")) {
                        pkg += "*";
                    }
                    ps.createInclude().setName(pkg);
                }
            } else {
                ps.createInclude().setName("**");
            }

            Enumeration e = excludePackageNames.elements();
            while (e.hasMoreElements()) {
                PackageName p = (PackageName) e.nextElement();
                String pkg = p.getName().replace('.", '/");
                if (pkg.endsWith("*")) {
                    pkg += "*";
                }
                ps.createExclude().setName(pkg);
            }


            String[] pathElements = sourcePath.list();
            for (int i = 0; i < pathElements.length; i++) {
                File dir = new File(pathElements[i]);
                if (dir.isDirectory()) {
                    DirSet ds = new DirSet();
                    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);
                }
            }
        }

        Enumeration e = dirSets.elements();
        while (e.hasMoreElements()) {
            DirSet ds = (DirSet) e.nextElement();
            File baseDir = ds.getDir(getProject());
            log("scanning " + baseDir + " for packages.", Project.MSG_DEBUG);
            DirectoryScanner dsc = ds.getDirectoryScanner(getProject());
            String[] dirs = dsc.getIncludedDirectories();
            boolean containsPackages = false;
            for (int i = 0; i < dirs.length; i++) {
                // are there any java files in this directory?
                File pd = new File(baseDir, dirs[i]);
                String[] files = pd.list(new FilenameFilter () {
                        public boolean accept(File dir1, 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;
                        String packageName =
                            dirs[i].replace(File.separatorChar, '.");
                        if (!addedPackages.contains(packageName)) {
                            addedPackages.addElement(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 java.lang.StringquoteString(java.lang.String str)
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.

        if (str.indexOf(' ") == -1
            && str.indexOf('\'") == -1
            && str.indexOf('"") == -1) {
            return str;
        }
        if (str.indexOf('\'") == -1) {
            return quoteString(str, '\'");
        } else {
            return quoteString(str, '"");
        }
    
private java.lang.StringquoteString(java.lang.String str, char delim)

        StringBuffer buf = new StringBuffer(str.length() * 2);
        buf.append(delim);
        if (str.indexOf('\\") != -1) {
            str = replace(str, '\\", "\\\\");
        }
        if (str.indexOf(delim) != -1) {
            str = replace(str, delim, "\\" + delim);
        }
        buf.append(str);
        buf.append(delim);
        return buf.toString();
    
private java.lang.Stringreplace(java.lang.String str, char fromChar, java.lang.String toString)

        StringBuffer buf = new StringBuffer(str.length() * 2);
        for (int i = 0; i < str.length(); ++i) {
            char ch = str.charAt(i);
            if (ch == fromChar) {
                buf.append(toString);
            } else {
                buf.append(ch);
            }
        }
        return buf.toString();
    
public voidsetAccess(org.apache.tools.ant.taskdefs.Javadoc$AccessType at)
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.

        cmd.createArgument().setValue("-" + at.getValue());
    
public voidsetAdditionalparam(java.lang.String add)
Set an additional parameter on the command line

param
add the additional command line parameter for the javadoc task.

        cmd.createArgument().setLine(add);
    
public voidsetAuthor(boolean b)
Include the author tag in the generated documentation.

param
b true if the author tag should be included.

        author = b;
    
public voidsetBootClasspathRef(org.apache.tools.ant.types.Reference r)
Adds a reference to a CLASSPATH defined elsewhere.

param
r the reference to an instance defining the bootclasspath.

        createBootclasspath().setRefid(r);
    
public voidsetBootclasspath(org.apache.tools.ant.types.Path path)
Set the boot classpath to use.

param
path the boot classpath.

        if (bootclasspath == null) {
            bootclasspath = path;
        } else {
            bootclasspath.append(path);
        }
    
public voidsetBottom(java.lang.String bottom)
Set the text to be placed at the bottom of each output file.

param
bottom the bottom text.

        Html h = new Html();
        h.addText(bottom);
        addBottom(h);
    
public voidsetBreakiterator(boolean b)
Enables the -linksource switch, will be ignored if Javadoc is not the 1.4 version. Default is false

param
b a String value
since
Ant 1.6

        this.breakiterator = b;
    
public voidsetCharset(java.lang.String src)
Charset for cross-platform viewing of generated documentation.

param
src the name of the charset

        this.addArgIfNotEmpty("-charset", src);
    
public voidsetClasspath(org.apache.tools.ant.types.Path path)
Set the classpath to be used for this Javadoc run.

param
path an Ant Path object containing the compilation classpath.

        if (classpath == null) {
            classpath = path;
        } else {
            classpath.append(path);
        }
    
public voidsetClasspathRef(org.apache.tools.ant.types.Reference r)
Adds a reference to a CLASSPATH defined elsewhere.

param
r the reference to an instance defining the classpath.

        createClasspath().setRefid(r);
    
public voidsetDefaultexcludes(boolean useDefaultExcludes)
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.

        this.useDefaultExcludes = useDefaultExcludes;
    
public voidsetDestdir(java.io.File dir)
Set the directory where the Javadoc output will be generated.

param
dir the destination directory.

        destDir = dir;
        cmd.createArgument().setValue("-d");
        cmd.createArgument().setFile(destDir);
    
public voidsetDocencoding(java.lang.String enc)
Output file encoding name.

param
enc name of the encoding to use.

        cmd.createArgument().setValue("-docencoding");
        cmd.createArgument().setValue(enc);
    
public voidsetDoclet(java.lang.String docletName)
Set the class that starts the doclet used in generating the documentation.

param
docletName the name of the doclet class.

        if (doclet == null) {
            doclet = new DocletInfo();
            doclet.setProject(getProject());
        }
        doclet.setName(docletName);
    
public voidsetDocletPath(org.apache.tools.ant.types.Path docletPath)
Set the classpath used to find the doclet class.

param
docletPath the doclet classpath.

        if (doclet == null) {
            doclet = new DocletInfo();
            doclet.setProject(getProject());
        }
        doclet.setPath(docletPath);
    
public voidsetDocletPathRef(org.apache.tools.ant.types.Reference r)
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.

        if (doclet == null) {
            doclet = new DocletInfo();
            doclet.setProject(getProject());
        }
        doclet.createPath().setRefid(r);
    
public voidsetDoctitle(java.lang.String doctitle)
Set the title of the generated overview page.

param
doctitle the Document title.

        Html h = new Html();
        h.addText(doctitle);
        addDoctitle(h);
    
public voidsetEncoding(java.lang.String enc)
Set the encoding name of the source files,

param
enc the name of the encoding for the source files.

        cmd.createArgument().setValue("-encoding");
        cmd.createArgument().setValue(enc);
    
public voidsetExcludePackageNames(java.lang.String packages)
Set the list of packages to be excluded.

param
packages a comma separated list of packages to be excluded. This may not include wildcards.

        StringTokenizer tok = new StringTokenizer(packages, ",");
        while (tok.hasMoreTokens()) {
            String p = tok.nextToken();
            PackageName pn = new PackageName();
            pn.setName(p);
            addExcludePackage(pn);
        }
    
public voidsetExecutable(java.lang.String executable)
Sets the actual executable command to invoke, instead of the binary javadoc found in Ant's JDK.

param
executable the command to invoke.
since
Ant 1.6.3

        this.executable = executable;
    
public voidsetExtdirs(java.lang.String path)
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.

        cmd.createArgument().setValue("-extdirs");
        cmd.createArgument().setValue(path);
    
public voidsetExtdirs(org.apache.tools.ant.types.Path path)
Set the location of the extensions directories.

param
path a path containing the extension directories.

        cmd.createArgument().setValue("-extdirs");
        cmd.createArgument().setPath(path);
    
public voidsetFailonerror(boolean b)
Should the build process fail if Javadoc fails (as indicated by a non zero return code)?

Default is false.

param
b a boolean value

        failOnError = b;
    
public voidsetFooter(java.lang.String footer)
Set the footer text to be placed at the bottom of each output file.

param
footer the footer text.

        Html h = new Html();
        h.addText(footer);
        addFooter(h);
    
public voidsetGroup(java.lang.String src)
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.

        group = src;
    
public voidsetHeader(java.lang.String header)
Set the header text to be placed at the top of each output file.

param
header the header text

        Html h = new Html();
        h.addText(header);
        addHeader(h);
    
public voidsetHelpfile(java.io.File f)
Specifies the HTML help file to use.

param
f the file containing help content.

        cmd.createArgument().setValue("-helpfile");
        cmd.createArgument().setFile(f);
    
public voidsetIncludeNoSourcePackages(boolean b)
If set to true, Ant will also accept packages that only hold package.html files but no Java sources.

param
b a boolean value.
since
Ant 1.6.3

        this.includeNoSourcePackages = b;
    
public voidsetLink(java.lang.String src)
Create links to Javadoc output at the given URL.

param
src the URL to link to

        createLink().setHref(src);
    
public voidsetLinkoffline(java.lang.String src)
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)

        LinkArgument le = createLink();
        le.setOffline(true);
        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);
        }
        StringTokenizer tok = new StringTokenizer(src, " ", false);
        le.setHref(tok.nextToken());

        if (!tok.hasMoreTokens()) {
            throw new BuildException(linkOfflineError);
        }
        le.setPackagelistLoc(getProject().resolveFile(tok.nextToken()));
    
public voidsetLinksource(boolean b)
Enables the -linksource switch, will be ignored if Javadoc is not the 1.4 version. Default is false

param
b a String value
since
Ant 1.6

        this.linksource = b;
    
public voidsetLocale(java.lang.String locale)
Set the local to use in documentation generation.

param
locale the locale to use.

        // 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");
    
public voidsetMaxmemory(java.lang.String max)
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)

        cmd.createArgument().setValue("-J-Xmx" + max);
    
public voidsetNodeprecated(boolean b)
Control deprecation infromation

param
b If true, do not include deprecated information.

        addArgIf(b, "-nodeprecated");
    
public voidsetNodeprecatedlist(boolean b)
Control deprecated list generation

param
b if true, do not generate deprecated list.

        addArgIf(b, "-nodeprecatedlist");
    
public voidsetNohelp(boolean b)
Control generation of help link.

param
b if true, do not generate help link

        addArgIf(b, "-nohelp");
    
public voidsetNoindex(boolean b)
Control generation of index.

param
b if true, do not generate index.

        addArgIf(b, "-noindex");
    
public voidsetNonavbar(boolean b)
Control generation of the navigation bar.

param
b if true, do not generate navigation bar.

        addArgIf(b, "-nonavbar");
    
public voidsetNoqualifier(java.lang.String noqualifier)
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

        this.noqualifier = noqualifier;
    
public voidsetNotree(boolean b)
Control class tree generation.

param
b if true, do not generate class hierarchy.

        addArgIf(b, "-notree");
    
public voidsetOld(boolean b)
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.

        old = b;
    
public voidsetOverview(java.io.File f)
Specify the file containing the overview to be included in the generated documentation.

param
f the file containing the overview.

        cmd.createArgument().setValue("-overview");
        cmd.createArgument().setFile(f);
    
public voidsetPackage(boolean b)
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.

        addArgIf(b, "-package");
    
public voidsetPackageList(java.lang.String src)
The name of a file containing the packages to process.

param
src the file containing the package list.

        packageList = src;
    
public voidsetPackagenames(java.lang.String packages)
Set the package names to be processed.

param
packages a comma separated list of packages specs (may be wildcarded).
see
#addPackage for wildcard information.

        StringTokenizer tok = new StringTokenizer(packages, ",");
        while (tok.hasMoreTokens()) {
            String p = tok.nextToken();
            PackageName pn = new PackageName();
            pn.setName(p);
            addPackage(pn);
        }
    
public voidsetPrivate(boolean b)
Indicate whether all classes and members are to be included in the scope processed

param
b true if scope is to be private level.

        addArgIf(b, "-private");
    
public voidsetProtected(boolean b)
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.

        addArgIf(b, "-protected");
    
public voidsetPublic(boolean b)
Indicate whether only public classes and members are to be included in the scope processed

param
b true if scope is to be public.

        addArgIf(b, "-public");
    
public voidsetSerialwarn(boolean b)
Control warnings about serial tag.

param
b if true, generate warning about the serial tag.

        addArgIf(b, "-serialwarn");
    
public voidsetSource(java.lang.String source)
Enables the -source switch, will be ignored if Javadoc is not the 1.4 version.

param
source a String value
since
Ant 1.5

        this.source = source;
    
public voidsetSourcefiles(java.lang.String src)
Set the list of source files to process.

param
src a comma separated list of source files.

        StringTokenizer tok = new StringTokenizer(src, ",");
        while (tok.hasMoreTokens()) {
            String f = tok.nextToken();
            SourceFile sf = new SourceFile();
            sf.setFile(getProject().resolveFile(f.trim()));
            addSource(sf);
        }
    
public voidsetSourcepath(org.apache.tools.ant.types.Path src)
Specify where to find source file

param
src a Path instance containing the various source directories.

        if (sourcePath == null) {
            sourcePath = src;
        } else {
            sourcePath.append(src);
        }
    
public voidsetSourcepathRef(org.apache.tools.ant.types.Reference r)
Adds a reference to a CLASSPATH defined elsewhere.

param
r the reference containing the source path definition.

        createSourcepath().setRefid(r);
    
public voidsetSplitindex(boolean b)
Generate a split index

param
b true if the index should be split into a file per letter.

        addArgIf(b, "-splitindex");
    
public voidsetStylesheetfile(java.io.File f)
Specifies the CSS stylesheet file to use.

param
f the file with the CSS to use.

        cmd.createArgument().setValue("-stylesheetfile");
        cmd.createArgument().setFile(f);
    
public voidsetUse(boolean b)
Generate the "use" page for each package.

param
b true if the use page should be generated.

        addArgIf(b, "-use");
    
public voidsetUseExternalFile(boolean b)
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.


                                  
        
        useExternalFile = b;
    
public voidsetVerbose(boolean b)
Run javadoc in verbose mode

param
b true if operation is to be verbose.

        addArgIf(b, "-verbose");
    
public voidsetVersion(boolean b)
Include the version tag in the generated documentation.

param
b true if the version tag should be included.

        this.version = b;
    
public voidsetWindowtitle(java.lang.String title)
Set the title to be placed in the HTML <title> tag of the generated documentation.

param
title the window title to use.

        addArgIfNotEmpty("-windowtitle", title);
    
private voidwriteExternalArgs(org.apache.tools.ant.types.Commandline toExecute)

        // If using an external file, write the command line options to it
        File optionsTmpFile = null;
        PrintWriter optionsListWriter = null;
        try {
            optionsTmpFile = FILE_UTILS.createTempFile(
                "javadocOptions", "", null);
            optionsTmpFile.deleteOnExit();
            String[] listOpt = toExecute.getArguments();
            toExecute.clearArgs();
            toExecute.createArgument().setValue(
                "@" + optionsTmpFile.getAbsolutePath());
            optionsListWriter = new PrintWriter(
                new FileWriter(optionsTmpFile.getAbsolutePath(), true));
            for (int i = 0; i < listOpt.length; i++) {
                String string = listOpt[i];
                if (string.startsWith("-J-")) {
                    toExecute.createArgument().setValue(string);
                } else  {
                    if (string.startsWith("-")) {
                        optionsListWriter.print(string);
                        optionsListWriter.print(" ");
                    } else {
                        optionsListWriter.println(quoteString(string));
                    }
                }
            }
            optionsListWriter.close();
        } catch (IOException ex) {
            if (optionsTmpFile != null) {
                optionsTmpFile.delete();
            }
            throw new BuildException(
                "Error creating or writing temporary file for javadoc options",
                ex, getLocation());
        } finally {
            FILE_UTILS.close(optionsListWriter);
        }