Contributing tasks and types
When your plug-in contributes Ant tasks and types, the tasks and types have access to all
of the classes inside the contributing plug-in. For example, the eclipse.refreshLocal task
contributed by org.eclipse.core.resources plug-in is
a wrapper for the
IResource.refreshLocal() method.
Tasks and types contributed by plug-ins must not be placed in any of the
plug-in libraries. They have to be in a separate JAR. This means that the
plug-in classes do not have access to the tasks and types provided by the
plug-in. (See
Why a separate JAR for tasks and types?
for more information.)
The
org.eclipse.ant.core.antTasks
extension point provides an example of how to specify
a new task
in the plugin.xml file.
Progress Monitors
The Eclipse Ant support provides access to an
IProgressMonitor if one is passed when invoking the AntRunner. One of the advantages of having access to a progress
monitor is that a long-running task can check to see if the user has requested its cancellation. The progress
monitor object is obtained from the Ant project's references. Note that a monitor is only made available if
the method
AntRunner.run(IProgressMonitor) was called with a valid progress monitor. The following code snippet
shows how to obtain a progress monitor from the task's project:
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;
import org.eclipse.ant.core.AntCorePlugin;
import org.eclipse.core.runtime.IProgressMonitor;
public class CoolTask extends Task {
public void execute() throws BuildException {
IProgressMonitor monitor =
(IProgressMonitor) getProject().getReferences().get(AntCorePlugin.ECLIPSE_PROGRESS_MONITOR);
if (monitor == null) {
...
} else {
...
}
}
}
Important rules when contributing tasks and types
The following should work as a checklist for plug-in developers:
- The JAR containing the tasks must not be a plug-in library (declared in
<library></library>).
- The task or type can reference any class available for the plug-in but
plug-in classes must not access the tasks or types.
- Native libraries should be loaded by the plug-in library classes and not tasks or types.
Why a separate JAR for tasks and types?
There are basically two requirements for running Ant in Eclipse that do not fit
the plug-in model very well:
- Change the Ant classpath at runtime
- Change the Ant version at runtime
During runtime plug-in classloaders cannot have their classpaths expanded and
plug-ins cannot change their dependencies. At the same time having separate
JARs for the tasks and types is a good isolation from the plug-in classloading
mechanism. Having these extra JARs declared by a plug-in permits adding the
contributing plug-in to the Ant classpath as well.
