org.apache.tools.ant.module/3 3.27.1 2

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

java.lang.Object
  extended by 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.

The Ant module registers one logger at position 100 in META-INF/services lookup which may or may not handle any events which have not already been consumed (marking them consumed itself) and will typically process message logged events by printing them to the output somehow, using hyperlinks for common file error patterns such as /path/to/File.java:34: some message. It may also handle sequences of messages logged within a task in the format

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

by linking to the column number indicated by the caret (^).

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)
Constructor Detail

AntLogger

protected AntLogger()
No-op constructor for implementors.

Method Detail

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()

org.apache.tools.ant.module/3 3.27.1 2

Built on January 29 2008.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.