AntLogger (Ant) - NetBeans API Javadoc (Current Development Version)

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

java.lang.Object
  org.apache.tools.ant.module.spi.AntLogger

public abstract class AntLogger
extends Object

A pluggable logger that can listen to AntEvents during one or more AntSessions.

There can be several loggers active on a given session, so AntEvent.consume() may be used to cooperate. Implementations may be registered to default 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 buildStarted(org.apache.tools.ant.module.spi.AntEvent); then some combination of target, task, and message logged events; then buildFinished(org.apache.tools.ant.module.spi.AntEvent). (Or it may receive just buildInitializationFailed(org.apache.tools.ant.module.spi.AntEvent).) 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. Events may also be delivered from the originating script or any subscripts, again with no guaranteed nesting behavior. A logger may not assume that it will not receive any events after buildFinished(org.apache.tools.ant.module.spi.AntEvent).

Various mask methods permit loggers to declare themselves uninterested in some kinds of events. Such events will not be delivered to them. Loggers should declare themselves interested only in events they will actually use in some way, to permit the Ant engine to minimize the number of events delivered. Note that loggers which do not declare themselves interested in the given session will not receive buildStarted(org.apache.tools.ant.module.spi.AntEvent), buildFinished(org.apache.tools.ant.module.spi.AntEvent), or buildInitializationFailed(org.apache.tools.ant.module.spi.AntEvent) at all, and loggers not additionally interested in all scripts will not receive buildInitializationFailed(org.apache.tools.ant.module.spi.AntEvent).

A logger should not keep any state as a rule; this would be a memory leak, and also a logger may be called from multiple threads with different sessions. Use AntSession.getCustomData(org.apache.tools.ant.module.spi.AntLogger) and AntSession.putCustomData(org.apache.tools.ant.module.spi.AntLogger, java.lang.Object) instead. Loggers may not make calls to the session, event, or task structure objects outside the dynamic scope of an event callback.

This is an abstract class so that new event types or masks may be added in the future. To prevent possible conflicts, implementors are forbidden to define other methods which take a single parameter of type AntEvent or which have a name beginning with the string interested.

 /path/to/File.java:34: you cannot throw a bogus exception here
          throw new Exception("bogus!");
                              ^

Since:

org.apache.tools.ant.module/3 3.12

See Also:

Issue #42525

Field Summary
static String[]	ALL_TARGETS           Special constant indicating the logger is interested in receiving all target events.
static String[]	ALL_TASKS           Special constant indicating the logger is interested in receiving all task events.
static String[]	NO_TARGETS           Special constant indicating the logger is not interested in receiving any target events.
static String[]	NO_TASKS           Special constant indicating the logger is not interested in receiving any task events.

 

Constructor Summary
protected	AntLogger()           No-op constructor for implementors.

 

Method Summary
void	buildFinished(AntEvent event)           Fired once when a build is finished.
void	buildInitializationFailed(AntEvent event)           Fired only if the build could not even be started.
void	buildStarted(AntEvent event)           Fired once when a build is started.
boolean	interestedInAllScripts(AntSession session)           Mark whether this logger is interested in any Ant script.
int[]	interestedInLogLevels(AntSession session)           Mark which kinds of message log events this logger is interested in.
boolean	interestedInScript(File script, AntSession session)           Mark whether this logger is interested in a given Ant script.
boolean	interestedInSession(AntSession session)           Mark whether this logger is interested in a given Ant session.
String[]	interestedInTargets(AntSession session)           Mark which kinds of targets this logger is interested in.
String[]	interestedInTasks(AntSession session)           Mark which kinds of tasks this logger is interested in.
void	messageLogged(AntEvent event)           Fired when a message is logged.
void	targetFinished(AntEvent event)           Fired when a target is finished.
void	targetStarted(AntEvent event)           Fired when a target is started.
void	taskFinished(AntEvent event)           Fired when a task is finished.
void	taskStarted(AntEvent event)           Fired when a task is started.

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

NO_TARGETS

public static final String[] NO_TARGETS

Special constant indicating the logger is not interested in receiving any target events.

See Also:

interestedInTargets(org.apache.tools.ant.module.spi.AntSession)

ALL_TARGETS

public static final String[] ALL_TARGETS

Special constant indicating the logger is interested in receiving all target events.

See Also:

interestedInTargets(org.apache.tools.ant.module.spi.AntSession)

NO_TASKS

public static final String[] NO_TASKS

Special constant indicating the logger is not interested in receiving any task events.

See Also:

interestedInTasks(org.apache.tools.ant.module.spi.AntSession)

ALL_TASKS

public static final String[] ALL_TASKS

Special constant indicating the logger is interested in receiving all task events.

See Also:

interestedInTasks(org.apache.tools.ant.module.spi.AntSession)

AntLogger

protected AntLogger()

No-op constructor for implementors.

buildInitializationFailed

public void buildInitializationFailed(AntEvent event)

Fired only if the build could not even be started. AntEvent.getException() will be non-null. The default implementation does nothing.

Parameters:

event - the associated event object

buildStarted

public void buildStarted(AntEvent event)

Fired once when a build is started. The default implementation does nothing.

Parameters:

event - the associated event object

buildFinished

public void buildFinished(AntEvent event)

Fired once when a build is finished. The default implementation does nothing.

Parameters:

event - the associated event object

See Also:

AntEvent.getException()

targetStarted

public void targetStarted(AntEvent event)

Fired when a target is started. It is not guaranteed that AntEvent.getTargetName() will be non-null (as can happen in some circumstances with <import>, for example). The default implementation does nothing.

Parameters:

event - the associated event object

targetFinished

public void targetFinished(AntEvent event)

Fired when a target is finished. It is not guaranteed that AntEvent.getTargetName() will be non-null. The default implementation does nothing.

Parameters:

event - the associated event object

taskStarted

public void taskStarted(AntEvent event)

Fired when a task is started. It is not guaranteed that AntEvent.getTaskName() or AntEvent.getTaskStructure() will be non-null, though they will usually be defined. AntEvent.getTargetName() might also be null. The default implementation does nothing.

Parameters:

event - the associated event object

taskFinished

public void taskFinished(AntEvent event)

Fired when a task is finished. It is not guaranteed that AntEvent.getTaskName() or AntEvent.getTaskStructure() will be non-null. AntEvent.getTargetName() might also be null. The default implementation does nothing.

Parameters:

event - the associated event object

messageLogged

public void messageLogged(AntEvent event)

Fired when a message is logged. The task and target fields may or may not be defined. The default implementation does nothing.

Parameters:

event - the associated event object

interestedInSession

public boolean interestedInSession(AntSession session)

Mark whether this logger is interested in a given Ant session.

Parameters:

session - a session which is about to be start

Returns:

true to receive events about it; by default, false

interestedInAllScripts

public boolean interestedInAllScripts(AntSession session)

Mark whether this logger is interested in any Ant script. If true, no events will be masked due to the script location. Note that a few events have no defined script and so will only be delivered to loggers interested in all scripts; typically this applies to debugging messages when a project is just being configured.

Parameters:

session - the relevant session

Returns:

true to receive events for all scripts; by default, false

interestedInScript

public boolean interestedInScript(File script,
                                  AntSession session)

Mark whether this logger is interested in a given Ant script. Called only if interestedInAllScripts(org.apache.tools.ant.module.spi.AntSession) is false. Only events with a defined script according to AntEvent.getScriptLocation() which this logger is interested in will be delivered. Note that a few events have no defined script and so will only be delivered to loggers interested in all scripts; typically this applies to debugging messages when a project is just being configured. Note also that a single session can involve many different scripts.

Parameters:

script - a particular build script

session - the relevant session

Returns:

true to receive events sent from this script; by default, false

interestedInTargets

public String[] interestedInTargets(AntSession session)

Mark which kinds of targets this logger is interested in. This applies to both target start and finish events, as well as any other events for which AntEvent.getTargetName() is not null, such as task start and finish events, and message log events. If NO_TARGETS, no events with specific targets will be sent to it. If a specific list, only events with defined target names included in the list will be sent to it. If ALL_TARGETS, all events not otherwise excluded will be sent to it.

Parameters:

session - the relevant session

Returns:

a nonempty (and non-null) list of target names; by default, NO_TARGETS

interestedInTasks

public String[] interestedInTasks(AntSession session)

Mark which kinds of tasks this logger is interested in. This applies to both task start and finish events, as well as any other events for which AntEvent.getTaskName() is not null, such as message log events. If NO_TASKS, no events with specific tasks will be sent to it. If a specific list, only events with defined task names included in the list will be sent to it. If ALL_TASKS, all events not otherwise excluded will be sent to it.

Parameters:

session - the relevant session

Returns:

a nonempty (and non-null) list of task names; by default, NO_TASKS

interestedInLogLevels

public int[] interestedInLogLevels(AntSession session)

Mark which kinds of message log events this logger is interested in. This applies only to message log events and no others. Only events with log levels included in the returned list will be delivered.

Parameters:

session - the relevant session

Returns:

a list of levels such as AntEvent.LOG_INFO; by default, an empty list

See Also:

AntSession.getVerbosity()