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.