| A pluggable logger that can listen to
AntEvent s during
one or more
AntSession s.
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. 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
AntLogger.buildFinished .
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
AntLogger.buildStarted ,
AntLogger.buildFinished , or
AntLogger.buildInitializationFailed at all, and loggers not additionally interested
in all scripts will not receive
AntLogger.buildInitializationFailed .
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 and
AntSession.putCustomData 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 (^).
author:
Jesse Glick
See Also: Issue #42525
since:
org.apache.tools.ant.module/3 3.12 | 