AntLogger (Ant)

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

Please Note: Using System.out or System.err in your subclass will add the messages to the build's output, not IDE log file. The behaviour is not part of the API contract though and can be changed in the future.
Since:

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

See Also:

Issue #42525

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Modifier Constructor and Description

protected AntLogger()
No-op constructor for implementors.

Constructors
Modifier	Constructor and Description
`protected`	`AntLogger()` No-op constructor for implementors.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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()

Class AntLogger

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NO_TARGETS

ALL_TARGETS

NO_TASKS

ALL_TASKS

Constructor Detail

AntLogger

Method Detail

buildInitializationFailed

buildStarted

buildFinished

targetStarted

targetFinished

taskStarted

taskFinished

messageLogged

interestedInSession

interestedInAllScripts

interestedInScript

interestedInTargets

interestedInTasks

interestedInLogLevels