org.apache.tools.ant.module.spi

{@link org.apache.tools.ant.module.spi.AutomaticExtraClasspathProvider} will be useful to modules which bundle libraries that may be needed for some optional tasks shipped with Ant.

{@link org.apache.tools.ant.module.spi.AntLogger}, together with the auxiliary interfaces {@link org.apache.tools.ant.module.spi.AntSession}, {@link org.apache.tools.ant.module.spi.AntEvent}, and {@link org.apache.tools.ant.module.spi.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.

1. 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.

2. 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:

1. The JRE and JDK libraries.
2. The installed copy of Ant, including any user-configured Ant classpath.
3. 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

Note that one event is shared across all listeners.

The information available from the event represents a best effort to gather information from the Ant run.

There can be several loggers active on a given session, so AntEvent.consume may be used to cooperate. Implementations may be registered to default org.openide.util.Lookup . Loggers are notified of events in the order of their registration in lookup.

A logger will always first be asked if it is interested in a given session; if it declines, it will receive no further events for that session. Otherwise it will normally receive AntLogger.buildStarted ; then some combination of target, task, and message logged events; then AntLogger.buildFinished . (Or it may receive just AntLogger.buildInitializationFailed .) A logger may not assume that target and task events are properly nested in any way, due to Ant's <parallel> task and other complexities such as <import> handling.