null.
*/
public BuildEvent(Project project) {
super(project);
@@ -76,9 +100,12 @@ public class BuildEvent extends EventObject {
}
/**
- * Construct a BuildEvent for a target level event
+ * Construct a BuildEvent for a target level event.
+ * The project associated with the event is derived
+ * from the given target.
*
* @param target the target that emitted the event.
+ * Must not be null.
*/
public BuildEvent(Target target) {
super(target);
@@ -88,9 +115,12 @@ public class BuildEvent extends EventObject {
}
/**
- * Construct a BuildEvent for a task level event
+ * Construct a BuildEvent for a task level event.
+ * The project and target associated with the event
+ * are derived from the given task.
*
* @param task the task that emitted the event.
+ * Must not be null.
*/
public BuildEvent(Task task) {
super(task);
@@ -99,24 +129,52 @@ public class BuildEvent extends EventObject {
this.task = task;
}
+ /**
+ * Sets the message and priority associated with this event.
+ * This is used for "messageLogged" events.
+ *
+ * @param message the message to be associated with this event.
+ * Should not be null.
+ * @param priority the priority to be associated with this event,
+ * as defined in the {@link Project Project} class.
+ *
+ * @see BuildListener#messageLogged(BuildEvent)
+ */
public void setMessage(String message, int priority) {
this.message = message;
this.priority = priority;
}
+ /**
+ * Sets the exception associated with this event. This is used
+ * for "taskFinished", "targetFinished", and "buildFinished"
+ * events.
+ *
+ * @param exception The exception to be associated with this event.
+ * May be null.
+ *
+ * @see BuildListener#taskFinished(BuildEvent)
+ * @see BuildListener#targetFinished(BuildEvent)
+ * @see BuildListener#buildFinished(BuildEvent)
+ */
public void setException(Throwable exception) {
this.exception = exception;
}
/**
- * Returns the project that fired this event.
+ * Returns the project that fired this event.
+ *
+ * @return the project that fired this event
*/
public Project getProject() {
return project;
}
/**
- * Returns the target that fired this event.
+ * Returns the target that fired this event.
+ *
+ * @return the project that fired this event, or null
+ * if this event is a project level event.
*/
public Target getTarget() {
@@ -124,39 +182,52 @@ public class BuildEvent extends EventObject {
}
/**
- * Returns the task that fired this event.
+ * Returns the task that fired this event.
+ *
+ * @return the task that fired this event, or null
+ * if this event is a project or target level event.
*/
public Task getTask() {
return task;
}
/**
- * Returns the logging message. This field will only be set
- * for "messageLogged" events.
+ * Returns the logging message. This field will only be set
+ * for "messageLogged" events.
*
- * @see BuildListener#messageLogged(BuildEvent)
+ * @return the message associated with this event, or null
+ * if no message has been set.
+ *
+ * @see BuildListener#messageLogged(BuildEvent)
*/
public String getMessage() {
return message;
}
/**
- * Returns the priority of the logging message. This field will only
- * be set for "messageLogged" events.
+ * Returns the priority of the logging message. This field will only
+ * be set for "messageLogged" events. The meaning of this priority
+ * is as specified by the constants in the {@link Project Project} class.
+ *
+ * @return the priority associated with this event.
*
- * @see BuildListener#messageLogged(BuildEvent)
+ * @see BuildListener#messageLogged(BuildEvent)
*/
public int getPriority(){
return priority;
}
/**
- * Returns the exception that was thrown, if any. This field will only
- * be set for "taskFinished", "targetFinished", and "buildFinished" events.
+ * Returns the exception that was thrown, if any. This field will only
+ * be set for "taskFinished", "targetFinished", and "buildFinished"
+ * events.
+ *
+ * @return the exception associated with this exception, or
+ * null if no exception has been set.
*
- * @see BuildListener#taskFinished(BuildEvent)
- * @see BuildListener#targetFinished(BuildEvent)
- * @see BuildListener#buildFinished(BuildEvent)
+ * @see BuildListener#taskFinished(BuildEvent)
+ * @see BuildListener#targetFinished(BuildEvent)
+ * @see BuildListener#buildFinished(BuildEvent)
*/
public Throwable getException() {
return exception;
diff --git a/src/main/org/apache/tools/ant/BuildException.java b/src/main/org/apache/tools/ant/BuildException.java
index 8fbc3519d..ef24feebf 100644
--- a/src/main/org/apache/tools/ant/BuildException.java
+++ b/src/main/org/apache/tools/ant/BuildException.java
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -53,12 +53,11 @@
*/
package org.apache.tools.ant;
-
import java.io.PrintWriter;
import java.io.PrintStream;
/**
- * Signals an error condition during a build.
+ * Signals an error condition during a build
*
* @author James Duncan Davidson
*/
@@ -79,7 +78,9 @@ public class BuildException extends RuntimeException {
/**
* Constructs an exception with the given descriptive message.
- * @param msg Description of or information about the exception.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be null.
*/
public BuildException(String msg) {
super(msg);
@@ -88,8 +89,11 @@ public class BuildException extends RuntimeException {
/**
* Constructs an exception with the given message and exception as
* a root cause.
- * @param msg Description of or information about the exception.
- * @param cause Throwable that might have cause this one.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be null unless a cause is specified.
+ * @param cause The exception that might have caused this one.
+ * May be null.
*/
public BuildException(String msg, Throwable cause) {
super(msg);
@@ -99,9 +103,13 @@ public class BuildException extends RuntimeException {
/**
* Constructs an exception with the given message and exception as
* a root cause and a location in a file.
- * @param msg Description of or information about the exception.
- * @param cause Exception that might have cause this one.
- * @param location Location in the project file where the error occured.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be null unless a cause is specified.
+ * @param cause The exception that might have caused this one.
+ * May be null.
+ * @param location The location in the project file where the error
+ * occurred. Must not be null.
*/
public BuildException(String msg, Throwable cause, Location location) {
this(msg, cause);
@@ -110,7 +118,9 @@ public class BuildException extends RuntimeException {
/**
* Constructs an exception with the given exception as a root cause.
- * @param cause Exception that might have caused this one.
+ *
+ * @param cause The exception that might have caused this one.
+ * Should not be null.
*/
public BuildException(Throwable cause) {
super(cause.toString());
@@ -118,10 +128,13 @@ public class BuildException extends RuntimeException {
}
/**
- * Constructs an exception with the given descriptive message and a location
- * in a file.
- * @param msg Description of or information about the exception.
- * @param location Location in the project file where the error occured.
+ * Constructs an exception with the given descriptive message and a
+ * location in a file.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be null.
+ * @param location The location in the project file where the error
+ * occurred. Must not be null.
*/
public BuildException(String msg, Location location) {
super(msg);
@@ -131,8 +144,11 @@ public class BuildException extends RuntimeException {
/**
* Constructs an exception with the given exception as
* a root cause and a location in a file.
- * @param cause Exception that might have cause this one.
- * @param location Location in the project file where the error occured.
+ *
+ * @param cause The exception that might have caused this one.
+ * Should not be null.
+ * @param location The location in the project file where the error
+ * occurred. Must not be null.
*/
public BuildException(Throwable cause, Location location) {
this(cause);
@@ -140,7 +156,10 @@ public class BuildException extends RuntimeException {
}
/**
- * Returns the nested exception.
+ * Returns the nested exception, if any.
+ *
+ * @return the nested exception, or null if no
+ * exception is associated with this one
*/
public Throwable getException() {
return cause;
@@ -148,30 +167,47 @@ public class BuildException extends RuntimeException {
/**
* Returns the location of the error and the error message.
+ *
+ * @return the location of the error and the error message
*/
public String toString() {
return location.toString() + getMessage();
}
/**
- * Sets the file location where the error occured.
+ * Sets the file location where the error occurred.
+ *
+ * @param location The file location where the error occurred.
+ * Must not be null.
*/
public void setLocation(Location location) {
this.location = location;
}
/**
- * Returns the file location where the error occured.
+ * Returns the file location where the error occurred.
+ *
+ * @return the file location where the error occurred.
*/
public Location getLocation() {
return location;
}
- // Override stack trace methods to show original cause:
+ /**
+ * Prints the stack trace for this exception and any
+ * nested exception to System.err.
+ */
public void printStackTrace() {
printStackTrace(System.err);
}
+ /**
+ * Prints the stack trace of this exception and any nested
+ * exception to the specified PrintStream.
+ *
+ * @param ps The PrintStream to print the stack trace to.
+ * Must not be null.
+ */
public void printStackTrace(PrintStream ps) {
synchronized (ps) {
super.printStackTrace(ps);
@@ -182,6 +218,13 @@ public class BuildException extends RuntimeException {
}
}
+ /**
+ * Prints the stack trace of this exception and any nested
+ * exception to the specified PrintWriter.
+ *
+ * @param pw The PrintWriter to print the stack trace to.
+ * Must not be null.
+ */
public void printStackTrace(PrintWriter pw) {
synchronized (pw) {
super.printStackTrace(pw);
diff --git a/src/main/org/apache/tools/ant/BuildListener.java b/src/main/org/apache/tools/ant/BuildListener.java
index 3ac1a24e0..2d2d6cb8b 100644
--- a/src/main/org/apache/tools/ant/BuildListener.java
+++ b/src/main/org/apache/tools/ant/BuildListener.java
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2000 The Apache Software Foundation. All rights
+ * Copyright (c) 2000,2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -57,62 +57,84 @@ package org.apache.tools.ant;
import java.util.EventListener;
/**
- * Classes that implement this interface will be notified when
- * things happend during a build.
+ * Instances of classes that implement this interface can register
+ * to be notified when things happened during a build.
*
- * @see BuildEvent
- * @see Project#addBuildListener(BuildListener)
+ * @see BuildEvent
+ * @see Project#addBuildListener(BuildListener)
*/
public interface BuildListener extends EventListener {
/**
- * Fired before any targets are started.
+ * Signals that a build has started. This event
+ * is fired before any targets have started.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be null.
*/
void buildStarted(BuildEvent event);
/**
- * Fired after the last target has finished. This event
- * will still be thrown if an error occured during the build.
+ * Signals that the last target has finished. This event
+ * will still be fired if an error occurred during the build.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be null.
*
- * @see BuildEvent#getException()
+ * @see BuildEvent#getException()
*/
void buildFinished(BuildEvent event);
/**
- * Fired when a target is started.
+ * Signals that a target is starting.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be null.
*
- * @see BuildEvent#getTarget()
+ * @see BuildEvent#getTarget()
*/
void targetStarted(BuildEvent event);
/**
- * Fired when a target has finished. This event will
- * still be thrown if an error occured during the build.
+ * Signals that a target has finished. This event will
+ * still be fired if an error occurred during the build.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be null.
*
- * @see BuildEvent#getException()
+ * @see BuildEvent#getException()
*/
void targetFinished(BuildEvent event);
/**
- * Fired when a task is started.
+ * Signals that a task is starting.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be null.
*
- * @see BuildEvent#getTask()
+ * @see BuildEvent#getTask()
*/
void taskStarted(BuildEvent event);
/**
- * Fired when a task has finished. This event will still
- * be throw if an error occured during the build.
+ * Signals that a task has finished. This event will still
+ * be fired if an error occurred during the build.
*
- * @see BuildEvent#getException()
+ * @param event An event with any relevant extra information.
+ * Must not be null.
+ *
+ * @see BuildEvent#getException()
*/
void taskFinished(BuildEvent event);
/**
- * Fired whenever a message is logged.
+ * Signals a message logging event.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be null.
*
- * @see BuildEvent#getMessage()
- * @see BuildEvent#getPriority()
+ * @see BuildEvent#getMessage()
+ * @see BuildEvent#getPriority()
*/
void messageLogged(BuildEvent event);
}
diff --git a/src/main/org/apache/tools/ant/BuildLogger.java b/src/main/org/apache/tools/ant/BuildLogger.java
index f02a51d6f..22590377e 100644
--- a/src/main/org/apache/tools/ant/BuildLogger.java
+++ b/src/main/org/apache/tools/ant/BuildLogger.java
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -59,45 +59,51 @@ import java.io.PrintStream;
/**
* Interface used by Ant to log the build output.
*
- * A build logger is a build listener which has the 'right' to send output to the
- * ant log, which is usually System.out unles redirected by the -logfile option.
+ * A build logger is a build listener which has the 'right' to send output to
+ * the ant log, which is usually System.out unless redirected by
+ * the -logfile option.
*
* @author Conor MacNeill
*/
public interface BuildLogger extends BuildListener {
+
/**
- * Set the msgOutputLevel this logger is to respond to.
+ * Sets the msgOutputLevel this logger is to respond to.
*
- * Only messages with a message level lower than or equal to the given level are
- * output to the log.
+ * Only messages with a message level lower than or equal to the given
+ * level are output to the log.
*
- * Constants for the message levels are in Project.java. The order of
- * the levels, from least to most verbose, is MSG_ERR, MSG_WARN,
- * MSG_INFO, MSG_VERBOSE, MSG_DEBUG.
+ * Constants for the message levels are in the
+ * {@link Project Project} class. The order of the levels, from least
+ * to most verbose, is MSG_ERR, MSG_WARN,
+ * MSG_INFO, MSG_VERBOSE,
+ * MSG_DEBUG.
*
* @param level the logging level for the logger.
*/
void setMessageOutputLevel(int level);
/**
- * Set the output stream to which this logger is to send its output.
+ * Sets the output stream to which this logger is to send its output.
*
- * @param output the output stream for the logger.
+ * @param output The output stream for the logger.
+ * Must not be null.
*/
void setOutputPrintStream(PrintStream output);
/**
- * Set this logger to produce emacs (and other editor) friendly output.
+ * Sets this logger to produce emacs (and other editor) friendly output.
*
- * @param emacsMode true if output is to be unadorned so that emacs and other
- * editors can parse files names, etc.
+ * @param emacsMode true if output is to be unadorned so that
+ * emacs and other editors can parse files names, etc.
*/
void setEmacsMode(boolean emacsMode);
/**
- * Set the output stream to which this logger is to send error messages.
+ * Sets the output stream to which this logger is to send error messages.
*
- * @param err the error stream for the logger.
+ * @param err The error stream for the logger.
+ * Must not be null.
*/
void setErrorPrintStream(PrintStream err);
}