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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

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

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

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

public final class AntSession
extends Object
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

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.

File getOriginatingScript()
          Get the Ant script originally invoked.

String[] getOriginatingTargets()
          Get the Ant targets originally run.

int getVerbosity()
          Get the (user-requested) verbosity level for this session.

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 Summary
`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.
`File`	`getOriginatingScript()` Get the Ant script originally invoked.
`String[]`	`getOriginatingTargets()` Get the Ant targets originally run.
`int`	`getVerbosity()` Get the (user-requested) verbosity level for this session.
`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

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)

toString

public String toString()

Overrides:: toString in class Object