Introduction

This document lists changes made to the NetBeans Ant module APIs. Please ask on the nbdev@netbeans.org mailing list if you have any questions.


Index of APIs

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

All changes by date

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.apache.tools.ant.module/3 > 1.20

Changes by affected class

org.apache.tools.ant.module.api.support.ActionUtils

org.apache.tools.ant.module.spi.AntEvent

org.apache.tools.ant.module.spi.AntLogger

org.apache.tools.ant.module.spi.AntOutputStream

org.apache.tools.ant.module.api.AntProjectCookie

org.apache.tools.ant.module.api.support.AntScriptUtils

org.apache.tools.ant.module.spi.AntSession

org.apache.tools.ant.module.api.AntTargetCookie

org.apache.tools.ant.module.api.AntTargetExecutor

org.apache.tools.ant.module.spi.AutomaticExtraClasspathProvider

org.apache.tools.ant.module.api.DefinitionRegistry

org.apache.tools.ant.module.api.IntrospectedInfo

org.apache.tools.ant.module.api.support.TargetLister

org.apache.tools.ant.module.spi.TaskStructure


Details of all changes by API and date


Ant module APIs

Added a method to mark an execution as user / non-user into the AntTargetExecutor.Env

May 2 '17; API spec. version: 3.85; affected top-level classes: AntTargetExecutor; made by: tzezula

Added a method AntTargetExecutor.Env.setUserActionto mark an execution as user / non-user. The executions marked as user actions are registered in the UI support org.netbeans.spi.project.ui.support.BuildExecutionSupport. By default the execution is an user action.

Added methods to override the default tab replacement policy into the AntTargetExecutor.Env

Apr 27 '17; API spec. version: 3.84; affected top-level classes: AntTargetExecutor; made by: tzezula

When the IDE is set to the automatic close tabs mode the tabs created by the previous run of the AntTargetExecutor are closed by successive run. Added a support to override this behavior.

Added AntTargetExecutor.Env.setConcealedProperties

Oct 2 '13; API spec. version: 3.73; affected top-level classes: ActionUtils AntTargetExecutor AntSession; made by: tzezula

Added ability to hide property values. Such properties can be used to pass passwords from the IDE keyring to ant scripts.

TargetLister.Script is now returning information about parse exception

Sep 26 '13; API spec. version: 3.72; affected top-level classes: TargetLister; made by: mkozeny; issues: #57677

TargetLister.Script constructor is now returning information about parse exception, when parsing of document fails.

Added TargetLister.Target.getOriginatingScript

Jan 18 '12; API spec. version: 3.53; affected top-level classes: TargetLister; made by: jglick; issues: #207192

Added ability to get originating script for a Target.

Added AntSession.getProperties

Dec 15 '11; API spec. version: 3.52; affected top-level classes: AntSession; made by: jglick; issues: #206161

Added ability to get user properties defined for a build.

Added AntSession.getIO

Mar 16 '09; API spec. version: 3.35; affected top-level classes: AntSession; made by: jglick; issues: #124366

Added ability to get the underlying InputOutput object for advanced formatting.

Added AntScriptUtils

Jun 12 '08; API spec. version: 3.31; affected top-level classes: AntScriptUtils; made by: jglick; issues: #136597

Added a new convenience class for getting some common information from Ant scripts.

Ant loggers can now inspect Ant reference objects

Mar 6 '08; API spec. version: 3.29; affected top-level classes: AntEvent; made by: jglick; issues: #128778

The AntEvent methods getProperty and getPropertyNames can now work with Ant references as well as plain properties. This is critical for loggers which wish to inspect e.g. the runtime value of a classpath given as:

<classpath refid="my.cp"/>

which otherwise would be inaccessible.


Compatibility:

Properties of the same name take precedence over references, so only code which relied on a property name not being set would see different behavior.

IntrospectedInfo no longer serializable

Oct 14 '06; API spec. version: 3.26; affected top-level classes: IntrospectedInfo; made by: jglick; issues: #87114

As part of a switch to the Preferences API, this class no longer needs to be serialized.


Compatibility:

Any clients which were attempting to serialize IntrospectedInfo objects will no longer be able to. No one should have been doing this to begin with; the class was offered to API clients for inspection in a given Ant session, but serialization was handled by the Ant module implementation.

Factory method to create AutomaticExtraClasspathProvider

Jun 20 '06; API spec. version: 3.26; affected top-level classes: AutomaticExtraClasspathProvider; made by: jtulach; issues: #77489

AutomaticExtraClasspathProvider can now be created in a declarative way. So libraries that wish to provide such Ant extension may just do it in declarative way without depending on AutomaticExtraClasspathProvider class.

Can now declaratively extend Ant context menu items

Mar 23 '05; API spec. version: 3.17; made by: jglick

You may now extend the Ant main node's context menu using the layer context Loaders/text/x-ant+xml/Actions.

Added antIncludesList (FileObject[] files, FileObject dir, boolean recursive) method

Mar 21 '05; API spec. version: 3.16; affected top-level classes: ActionUtils; made by: tzezula; issues: #51132

The current ActionUtils.antIncludeList (FileObject[] files, FileObject dir) generates a recursive include list for directories. The API change introduces new ActionUtils.antIncludeList (FileObject[] files, FileObject dir, boolean recursive) which generates either recursive or non recursive include depending on the value of the recursive parameter. The old method is bridged into the new one.

Added Ant logging SPI

Jun 11 '04; API spec. version: 3.12; affected top-level classes: AntLogger AntSession AntEvent TaskStructure AntOutputStream; made by: jglick; issues: #42525

Added a new SPI for influencing the logging behavior of Ant. See Javadoc for details.


Compatibility:

AntOutputStream was obsoleted by this change.

Added TargetLister

Jun 3 '04; API spec. version: 3.11; affected top-level classes: TargetLister; made by: jglick; issues: #21728 #36320 #42901

The TargetLister class was added to make it easier to implement target-related UI without needing to duplicate logic relating to <import>.

AntProjectCookie no longer guaranteed serializable

May 11 '04; API spec. version: 3.10; affected top-level classes: AntProjectCookie; made by: jglick

AntProjectCookie used to be serializable. This was used to persist build script information associated with service types. Now that these types are gone, the raison d'être for the serializability is also gone.


Compatibility:

Incompatible for anyone expecting to serialize them.

AntOutputStream should be passed URL not FileObject

Apr 30 '04; API spec. version: 3.10; affected top-level classes: AntOutputStream; made by: jglick; issues: #42666

Formerly AntOutputStream was passed a FileObject parameter in writeLine. However that was potentially inefficient as it required a FileObject to be created for each hyperlink, if it was never activated. The former writeLine method has been deprecated and subclasses should now override the new variant that takes URL (and should return true).


Compatibility:

Old subclasses of AntOutputStream should continue to work unmodified. But new subclasses which override the new method taking URL must return true so that the old method is not called. The old method is now non-final but cannot be called. The new method is non-final but should be treated as abstract.

Added ActionUtils

Mar 21 '04; API spec. version: 3.9; affected top-level classes: ActionUtils; made by: jglick

The utility class ActionUtils was added to help implement actions based on Ant targets. Previously it was in the Ant Project SPI.

Deprecated AntOutputStream.formatMessage

Mar 16 '04; API spec. version: 3.8; affected top-level classes: AntOutputStream; made by: jglick

This method is no longer called due to changes in how Ant output formatting is handled, so it is deprecated.

Added AutomaticExtraClasspathProvider

Mar 16 '04; API spec. version: 3.8; affected top-level classes: AutomaticExtraClasspathProvider; made by: jglick

A new SPI interface AutomaticExtraClasspathProvider was added in order to make it possible to include bundled libraries such as junit.jar in Ant's main classpath without user intervention.

Format of ant/nblib/*.jar changed to use antlib.xml

Jan 7 '04; API spec. version: 3.6; made by: jglick; issues: #38306
ant/nblib/*.jar taskdef (or typedef) JARs must now be named according to the code name base of the module, and must define their tasks (or types etc.) using the standard antlib.xml syntax rather than META-INF/taskdefs.properties and/or META-INF/typedefs.properties.
Compatibility: Existing modules installing taskdef JARs in this directory must change their format. The previous format was however introduced after NetBeans 3.5 in the trunk.

IntrospectedInfo.getTags(String) added

Nov 8 '03; API spec. version: 3.3; affected top-level classes: IntrospectedInfo; made by: jglick; issues: #37111
IntrospectedInfo now keeps information about the tag values represented by EnumeratedAttribute subclasses, so it is not necessary to load the runtime class just for this information.

Redesign to support pluggable Ant installation

Jul 7 '03; API spec. version: 3.1; affected top-level classes: IntrospectedInfo org.apache.tools.ant.module.api.DefinitionRegistry org.apache.tools.ant.module.api.AntTargetCookie; made by: jglick; issues: #20211

The Ant module was partially refactored to permit the actual Ant installation to be user-selectable and modifiable at runtime, plus to use an independent class loader with its own classpath for running Ant in. This necessitated some structural changes in the public APIs.

Modules which registered automatic task definitions will need to be changed to use the new API. Typically such tasks run only inside the NetBeans VM, do not need a <taskdef>, and make use of API calls into NetBeans modules. Other uses of the Ant module—for example, calls to AntTargetExecutor—are unlikely to be affected by the change.


Compatibility:

There are several incompatible changes here:

  1. All previously deprecated methods and classes were removed as a cleanup measure.

  2. Registration of VM-internal (NetBeans-specific) tasks changed. Rather than using DefinitionRegistry and Lookup, task JARs are placed in a well-known location.

  3. Modules depending on the Ant module can no longer refer to Ant classes directly, i.e. they are no longer exported from the Ant module class loader.

  4. IntrospectedInfo.scanProject changed its parameter from Project to Map.

  5. The major release version changed from 2 to 3. Modules which are unaffected by the above changes may elect to depend on either version: org.apache.tools.ant.module/2-3.

API for target execution was added

Jan 27 '03; API spec. version: 2.15; affected top-level classes: AntTargetExecutor; made by: dkonecny
AntTargetExecutor class for target execution was added. It has factory method createTargetExecutor() which for the the given instance of AntTargetExecutor.Env creates instance of AntTargetExecutor capable to execute list of targets from the Ant script represented by AntProjectCookie. The AntTargetExecutor.Env class describes environment which is used during the target execution.

SPI for parsing of output from Ant execution

Jan 27 '03; API spec. version: 2.15; affected top-level classes: AntOutputStream; made by: dkonecny
AntOutputStream abstract class was added which simplifies handling and parsing of output produced during the Ant script execution. It parses the output and if it contains information in the form of file_name : line_column : error_description it will parse the information and finds FileObject for the file_name.

IntrospectedInfo.getKnownInfo() added

Jan 7 '03; API spec. version: 2.14; affected top-level classes: IntrospectedInfo; made by: jglick
This new static convenience method gives you one info object containing all tasks and types, both those built into Ant, and custom definitions too.

ParseStatus cookie was added

Jun 27 '02; API spec. version: 2.10; affected top-level classes: AntProjectCookie; made by: dkonecny; issues: #24213
ParseStatus cookie which extends AntProjectCookie was added to API. It permits queries of parse status.