org.apache.tools.ant.module.spi (Ant)

Interface Summary
Interface	Description
AutomaticExtraClasspathProvider	Permits a module to register special additional JARs (or directories) to be added to Ant's primary classpath by default.

Class Summary
Class	Description
AntEvent	One event delivered to an `AntLogger`.
AntLogger	A pluggable logger that can listen to `AntEvent`s during one or more `AntSession`s.
AntOutputStream	Deprecated This functionality is not recommended to be used and may result in loss of some Ant module features as of org.apache.tools.ant.module/3 3.12.
AntSession	Represents one Ant build session, possibly consisting of multiple targets, subprojects, and so on.
TaskStructure	Describes the structure of a task.

Package org.apache.tools.ant.module.spi Description

Ways of influencing how Ant is run inside NetBeans.

AutomaticExtraClasspathProvider will be useful to modules which bundle libraries that may be needed for some optional tasks shipped with Ant.

AntLogger, together with the auxiliary interfaces AntSession, AntEvent, and TaskStructure, provides a powerful way of controlling the appearance of Ant process output.

Registering Tasks and Types

The Ant module provides a way for other modules to register custom Ant tasks and types that will automatically be available to any scripts running inside NetBeans.

Do consider this facility for tasks which would only make sense running inside the NetBeans VM, typically making direct Java method calls to internal NetBeans objects.
Do not consider this facility for tasks which would be useful in any context. You may bundle up such task JARs in ant/extra/*.jar in the NetBeans distribution and recommend users use them via <taskdef> with a <classpath>, as they would any other third-party task libraries.

Examples of likely tasks: opening the GUI-configured web browser on a URL, reloading a NetBeans test module, attaching the NetBeans debugger to a running application, etc. You could consider these things IDE scripting using Ant.

Registration is simple. (Assume for sake of illustration that the code name base of the host module is org.netbeans.modules.foo; in the following text, replace this package sequence with the actual code name base of your module, using whatever separator character is indicated.) Create a JAR file containing the task class(es), named org-netbeans-modules-foo.jar. Create an entry in that JAR org/netbeans/modules/foo/antlib.xml listing tasks (or types, macrodefs, etc.) you wish to define, in the standard Antlib format. For example:

<?xml version="1.0" encoding="UTF-8"?>
<antlib>
    <taskdef name="mytask1" classname="org.netbeans.modules.foo.MyTask1"/>
    <taskdef name="mytask2" classname="org.netbeans.modules.foo.MyTask2"/>
</antlib>

(Note that when using Ant 1.5, only <taskdef> and <typedef> elements are supported, and only using the name and classname attributes.)

Place the JAR file in the ant/nblib/ directory of the NetBeans distribution, i.e. bundle it in your NBM as netbeans/ant/nblib/org-netbeans-modules-foo.jar. NetBeans will automatically load your task/type definitions and make them available to build scripts.

The task classes will be loaded in a special class loader, not the one usually used for your module's classes. This loader will have access to:

The JRE and JDK libraries.
The installed copy of Ant, including any user-configured Ant classpath.
Your module, including any extension JARs and anything your module can directly refer to, such as other modules it depends on.

Do not include copies of your task or type definitions in the module JAR. They must reside only in ant/nblib/*.jar.

Now whenever your module is enabled, Ant projects run inside NetBeans will have access to the definitions you provided. When running Ant 1.5, the definitions will be available with no namespace qualification, e.g.:

<project default="all">
    <target name="all">
        <mytask1 arg="val"/>
    </target>
</project>

When running Ant 1.6, the definitions will still be available with no namespace qualification. However it is recommended in 1.6 to namespace-qualify everything; so the antlib is loaded in the namespace you would expect, ensuring that there is no possibility of name clashes with unrelated tasks:

<project default="all"
         xmlns="antlib:org.apache.tools.ant"
         xmlns:foo="antlib:org.netbeans.modules.foo">
    <target name="all">
        <foo:mytask1 arg="val"/>
    </target>
</project>

Complete working example of task registration: ant/browsetask module