org.sandev.sandbuild
Class SandJavadoc

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          org.sandev.sandbuild.SandTask
              org.sandev.sandbuild.SandJavadoc

public class SandJavadoc
extends SandTask

Ant task to run Javadoc in the same VM as Ant. This task relies on the programmatic interface to Javadoc introduced in Javadoc 1.4. Not all doclet parameters are explicitly supported; use the additionalparams parameter to pass through anything that is not explicitely covered.

This task uses the Ant Javadoc task, but just to hold values for setup. The actual call to javadoc is done here. The description of how to do this can be found under "Tool Documentation" -> javadoc -> "Standard Doclet" -> "running programmatically. This description shifts around a bit with each J2SE release, but that's where it was as of this writing.

Field Summary

protected java.lang.String	additionalparam Additional javadoc params can be passed via the additionalParam element.
protected org.apache.tools.ant.types.Path	classpath Classpath
protected java.lang.String	csvsourcefiles Takes a list of source file names, separated by commas, to use as the doclet source.
protected java.io.File	destdir Destination dir
protected org.apache.tools.ant.taskdefs.Javadoc.DocletInfo	doclet Doclet code
protected boolean	failonerror True if the task should fail when an error occurs.
protected org.apache.tools.ant.types.Path	sourcepath Source path
protected java.lang.String	subpackages Package names to run Javadoc on.

Fields inherited from class org.apache.tools.ant.Task

description, location, target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Constructor Summary

SandJavadoc()

Method Summary

protected java.lang.String	array2Path(java.lang.String[] path) Return an array of path elements as a single path string
org.apache.tools.ant.types.Path	createClasspath()
org.apache.tools.ant.taskdefs.Javadoc.DocletInfo	createDoclet()
protected void	diagnoseMethodAccess(java.lang.Class dc, java.lang.String methodName, java.lang.Class[] paramTypes) Try and figure out what access we have to the defined method.
protected void	dumpCallSummary(java.lang.String docletName, java.lang.String docletPath) Dump out a summary of the environment and such for the call
protected void	dumpClassLoaderInfo(java.lang.String leadText, java.lang.ClassLoader cl, boolean dumpSearchPath) Dump out some descriptive info about the specified ClassLoader.
void	dumpSearchPath(java.net.URLClassLoader ucl) Utility method to dump the current search path elements.
void	execute() Do our thing.
protected void	fixEnvironment() To avoid issues with duplicate class loadings, we trim down the additional environment that the doclet invocation references.
java.lang.String	getToolsJarName() Return the name of the tools jar file.
java.net.URL	getToolsURL() Return the tools URL.
protected void	pln(java.lang.String text) Just in case we want to hook this output for debugging, or make everything quiet.
protected void	prepareForExec(java.lang.String docletName, java.lang.String docletPath) Do what is necessary to make the exec call work.
void	setAdditionalparam(java.lang.String str)
void	setClasspath(org.apache.tools.ant.types.Path cp)
void	setClasspathRef(org.apache.tools.ant.types.Reference r)
void	setCsvsourcefiles(java.lang.String files)
void	setDestdir(java.io.File dir)
void	setDoclet(java.lang.String src)
void	setDocletPath(org.apache.tools.ant.types.Path src)
void	setDocletPathRef(org.apache.tools.ant.types.Reference r)
void	setFailonerror(boolean foe)
void	setSourcepath(org.apache.tools.ant.types.Path src)
void	setSubpackages(java.lang.String str)
protected void	testInvoke(java.lang.String docletClassName, java.lang.String docletPath) A test invocation mirroring how our doclet actually gets called.
void	testLoadClass(java.lang.String docletName, java.lang.String[] pathElems) Attempt to load our doclet and make sure it has a start method that can be found.
java.lang.ClassLoader	verifyClassLoaderPath(java.net.URLClassLoader ucl, java.lang.String[] pathElems) Verify all the pathElems are loaded so the calls work.
void	verifyClassLoading(java.lang.String docletName, org.apache.tools.ant.types.Path classpath) Loading the class is no prob.

Methods inherited from class org.apache.tools.ant.Task

getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, setProject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

sourcepath

protected org.apache.tools.ant.types.Path sourcepath

Source path

csvsourcefiles

protected java.lang.String csvsourcefiles

Takes a list of source file names, separated by commas, to use as the doclet source. In Ant, the javadoc task will take a sourcefiles parameter which works provided each full filename is separated by a comma character and nothing else (no whitespace). The javadoc tool itself specifies a sourcefilenames parameter, which states that each filename must be separated by spaces.

Since Ant uses CSV, we specify the same format here: full filename specifications separated by commas and no whitespace. The comma characters are converted to space characters and the resulting text is passed to com.sun.tools.javadoc.Main

classpath

protected org.apache.tools.ant.types.Path classpath

Classpath

destdir

protected java.io.File destdir

Destination dir

failonerror

protected boolean failonerror

True if the task should fail when an error occurs.

subpackages

protected java.lang.String subpackages

Package names to run Javadoc on. Currently only a single root package is supported.

additionalparam

protected java.lang.String additionalparam

Additional javadoc params can be passed via the additionalParam element.

doclet

protected org.apache.tools.ant.taskdefs.Javadoc.DocletInfo doclet

Doclet code

Constructor Detail

SandJavadoc

public SandJavadoc()

Method Detail

setSourcepath

public void setSourcepath(org.apache.tools.ant.types.Path src)

setCsvsourcefiles

public void setCsvsourcefiles(java.lang.String files)

setClasspath

public void setClasspath(org.apache.tools.ant.types.Path cp)

createClasspath

public org.apache.tools.ant.types.Path createClasspath()

setClasspathRef

public void setClasspathRef(org.apache.tools.ant.types.Reference r)

setDestdir

public void setDestdir(java.io.File dir)

setFailonerror

public void setFailonerror(boolean foe)

setSubpackages

public void setSubpackages(java.lang.String str)

setAdditionalparam

public void setAdditionalparam(java.lang.String str)

setDoclet

public void setDoclet(java.lang.String src)

setDocletPath

public void setDocletPath(org.apache.tools.ant.types.Path src)

setDocletPathRef

public void setDocletPathRef(org.apache.tools.ant.types.Reference r)

createDoclet

public org.apache.tools.ant.taskdefs.Javadoc.DocletInfo createDoclet()

prepareForExec

protected void prepareForExec(java.lang.String docletName,
                              java.lang.String docletPath)
                       throws org.apache.tools.ant.BuildException

Do what is necessary to make the exec call work. This has been prone to problems. In Ant 1.5.4 things worked, in Ant 1.6.0 they didn't. We ran into something similar back in May 2003 and were able to fix things up by moving GenDriverDoclet into apps/basics and specifying a docletpath. Now (Jan 2004) things are broken again, and after three days of diagnosis, I'm codifying the changes and checks.

You can't modify the ClassLoader for a Class, but you may be allowed to modify the ClassLoader for a Thread depending on security.

Throws:

org.apache.tools.ant.BuildException

pln

protected void pln(java.lang.String text)

Just in case we want to hook this output for debugging, or make everything quiet.

fixEnvironment

protected void fixEnvironment()

To avoid issues with duplicate class loadings, we trim down the additional environment that the doclet invocation references. The CLASSPATH in particular may bear little resemblance to how it started out.

dumpCallSummary

protected void dumpCallSummary(java.lang.String docletName,
                               java.lang.String docletPath)
                        throws org.apache.tools.ant.BuildException

Dump out a summary of the environment and such for the call

Throws:

org.apache.tools.ant.BuildException

dumpClassLoaderInfo

protected void dumpClassLoaderInfo(java.lang.String leadText,
                                   java.lang.ClassLoader cl,
                                   boolean dumpSearchPath)

Dump out some descriptive info about the specified ClassLoader.

dumpSearchPath

public void dumpSearchPath(java.net.URLClassLoader ucl)

Utility method to dump the current search path elements. Useful for debugging.

array2Path

protected java.lang.String array2Path(java.lang.String[] path)

Return an array of path elements as a single path string

testInvoke

protected void testInvoke(java.lang.String docletClassName,
                          java.lang.String docletPath)

A test invocation mirroring how our doclet actually gets called. This is meant to reproduce the call structure and is useful for tracking down bugs. Some of this code may look unnecessary, but might be necessary to accurately reflect what will happen.

This method generally shouldn't be called, but when something stops working it might give an idea as to why.

diagnoseMethodAccess

protected void diagnoseMethodAccess(java.lang.Class dc,
                                    java.lang.String methodName,
                                    java.lang.Class[] paramTypes)

Try and figure out what access we have to the defined method.

verifyClassLoading

public void verifyClassLoading(java.lang.String docletName,
                               org.apache.tools.ant.types.Path classpath)
                        throws org.apache.tools.ant.BuildException

Loading the class is no prob. This shows how to get to it and find the right method using the right ClassLoader. Unfortunately this is not how Javadoc Main does it. Hence the conflict when there are two different instances of com.sun.javadoc.RootDoc floating around and Main can't find the start method.

Throws:

org.apache.tools.ant.BuildException

testLoadClass

public void testLoadClass(java.lang.String docletName,
                          java.lang.String[] pathElems)
                   throws org.apache.tools.ant.BuildException

Attempt to load our doclet and make sure it has a start method that can be found.

Throws:

org.apache.tools.ant.BuildException

verifyClassLoaderPath

public java.lang.ClassLoader verifyClassLoaderPath(java.net.URLClassLoader ucl,
                                                   java.lang.String[] pathElems)
                                            throws org.apache.tools.ant.BuildException

Verify all the pathElems are loaded so the calls work. This method returns the ClassLoader in use, which may be different than what was passed in.

Throws:

org.apache.tools.ant.BuildException

getToolsJarName

public java.lang.String getToolsJarName()

Return the name of the tools jar file. This is where things like RootDoc and Doclet are defined.

getToolsURL

public java.net.URL getToolsURL()

Return the tools URL. This is the URL of tools.jar which has the doclet stuff in it. Necessary for generator processing.

execute

public void execute()
             throws org.apache.tools.ant.BuildException

Do our thing.

Overrides:

execute in class org.apache.tools.ant.Task

Throws:

org.apache.tools.ant.BuildException