org.apache.tools.ant.module.spi

Class AntSession

java.lang.Object

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

public final class AntSession
extends Object

Represents one Ant build session, possibly consisting of multiple targets, subprojects, and so on. A session may be shared by several AntLoggers.

Since:

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

Method Summary

Modifier and Type	Method and Description
void	consumeException(Throwable t) Marks an exception as having been processed by a logger.
OutputListener	createStandardHyperlink(URL file, String message, int line1, int column1, int line2, int column2) Convenience method to create a standard hyperlink implementation.
void	deliverMessageLogged(AntEvent originalEvent, String message, int level) Deliver a message logged event to all matching loggers.
Object	getCustomData(AntLogger logger) Get optional data stored by the logger in this session.
String	getDisplayName() Get a display name used for the session as a whole.
InputOutput	getIO() Obtains the I/O handle for advanced operations such as IOColors.
File	getOriginatingScript() Get the Ant script originally invoked.
String[]	getOriginatingTargets() Get the Ant targets originally run.
Map<String,String>	getProperties() Gets a set of user properties defined for this session.
int	getVerbosity() Get the (user-requested) verbosity level for this session.
boolean	isConcealed(String propertyName) Checks if the property is concealed.
boolean	isExceptionConsumed(Throwable t) Tests whether a given exception has already been consumed by some logger.
void	println(String message, boolean err, OutputListener listener) Print a line of text to the Ant output.
void	putCustomData(AntLogger logger, Object data) Store custom data associated with this session.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getOriginatingScript

public File getOriginatingScript()

Get the Ant script originally invoked. Note that due to subproject support some events may come from other scripts.

Returns:

the Ant script which was run to start with

getOriginatingTargets

public String[] getOriginatingTargets()

Get the Ant targets originally run.

Returns:

a list of one or more targets (but may be empty during AntLogger.buildInitializationFailed(org.apache.tools.ant.module.spi.AntEvent))

getCustomData

public Object getCustomData(AntLogger logger)

Get optional data stored by the logger in this session.

Parameters:

logger - the logger which wishes to retrieve data

Returns:

any optional data, or null initially

putCustomData

public void putCustomData(AntLogger logger,
                          Object data)

Store custom data associated with this session. May be used by the logger to keep some information that will persist for the lifetime of the session.

Parameters:

logger - the logger which wishes to store data

data - some custom data to retain

println

public void println(String message,
                    boolean err,
                    OutputListener listener)

Print a line of text to the Ant output.

Parameters:

message - a message to print (newline will be appended automatically)

err - true to send to the error stream, false for regular output

listener - an output listener suitable for hyperlinks, or null for a plain print

See Also:

createStandardHyperlink(java.net.URL, java.lang.String, int, int, int, int)

deliverMessageLogged

public void deliverMessageLogged(AntEvent originalEvent,
                                 String message,
                                 int level)

Deliver a message logged event to all matching loggers.

Loggers will receive AntLogger.messageLogged(org.apache.tools.ant.module.spi.AntEvent) with an event similar to the original event except for the message and log level; also the exception will always be null and the event will initially be unconsumed.

This call blocks until all loggers have processed the nested event. Note that this logger may also receive the event so it must be reentrant.

Loggers are discouraged from using this facility merely to create hyperlinks for which the target is known. Use println(java.lang.String, boolean, org.openide.windows.OutputListener) instead. This method is primarily intended for use from the standard logger to deliver stack trace lines to other loggers which may be able to hyperlink them.

Parameters:

originalEvent - the original event received by the calling logger

message - a message to log (see AntEvent.getMessage())

level - the level to log it at (see AntEvent.getLogLevel())

consumeException

public void consumeException(Throwable t)
                      throws IllegalStateException

Marks an exception as having been processed by a logger.

A single build-halting exception can traverse any number of Ant events as it progresses outwards, typically from the failing task to the failing target (possibly several times due to subprojects) and finally to the build failure.

Consuming the exception permits a logger to indicate to other loggers that it has already handled the problem in an appropriate manner. Since the standard logger may print an exception (possibly with stack trace) that is part of a AntLogger.buildFinished(org.apache.tools.ant.module.spi.AntEvent) event, loggers which deal with the exception in some other way should consume it before returning from the callback.

Parameters:

t - an exception to mark as consumed

Throws:

IllegalStateException - if it was already consumed

isExceptionConsumed

public boolean isExceptionConsumed(Throwable t)

Tests whether a given exception has already been consumed by some logger.

Note that if an exception is consumed, any exception with that exception as its Throwable.getCause() (possibly recursively) is also considered consumed. This is useful because Ant's ProjectHelper.addLocationToBuildException will annotate BuildExceptions with location information by constructing wrapper exceptions.

Parameters:

t - an exception

Returns:

true if it (or a nested exception) has already been consumed by consumeException(java.lang.Throwable)

getVerbosity

public int getVerbosity()

Get the (user-requested) verbosity level for this session. Generally only messages logged at this or lesser level (higher priority) should be displayed.

Returns:

the verbosity, e.g. AntEvent.LOG_INFO

getProperties

public Map<String,String> getProperties()

Gets a set of user properties defined for this session. These might be a mixture of global default definitions and per-session properties.

Returns:

an immutable property map

Since:

3.52

isConcealed

public boolean isConcealed(String propertyName)

Checks if the property is concealed. The value of the concealed property is not visible to the user.

Parameters:

propertyName - the property name to check

Returns:

true if property should not be visible to user

Since:

3.71

getDisplayName

public String getDisplayName()

Get a display name used for the session as a whole.

Returns:

a user-presentable display name appropriate for session-scope messaging

createStandardHyperlink

public OutputListener createStandardHyperlink(URL file,
                                              String message,
                                              int line1,
                                              int column1,
                                              int line2,
                                              int column2)

Convenience method to create a standard hyperlink implementation. The GUI of the hyperlink will be oriented toward error messages and may involve editor annotations. Line and column numbers start at 1.

Parameters:

file - a file to link to (may or may not exist, but hyperlink will not work if it does not)

message - a message to use e.g. for the status bar when clicking on the hyperlink, or for annotation tool tips

line1 - the starting line number, or -1 if there is no associated line number

column1 - the starting column number, or -1 if there is no associated column number (must be -1 if line1 is -1)

line2 - the ending line number, or -1 for a single-line link (must be -1 if line1 is -1)

column2 - the ending column number, or -1 if not applicable (must be -1 if either line2 or column1 is -1)

Returns:

a standard hyperlink suitable for println(java.lang.String, boolean, org.openide.windows.OutputListener)

getIO

public InputOutput getIO()

Obtains the I/O handle for advanced operations such as IOColors.

Returns:

an I/O handle

Since:

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

toString

public String toString()

Overrides:

toString in class Object