ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject cvs commit: jakarta-ant/src/main/org/apache/tools/ant BuildEvent.java BuildException.java BuildListener.java BuildLogger.java
Date Fri, 15 Feb 2002 13:59:38 GMT
bodewig     02/02/15 05:59:38

  Modified:    src/main/org/apache/tools/ant BuildEvent.java
                        BuildException.java BuildListener.java
                        BuildLogger.java
  Log:
  More JavaDoc documentation fixups.
  
  Submitted by:	Jon Skeet <jon.skeet@peramon.com>
  
  Revision  Changes    Path
  1.7       +90 -19    jakarta-ant/src/main/org/apache/tools/ant/BuildEvent.java
  
  Index: BuildEvent.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/BuildEvent.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- BuildEvent.java	10 Jan 2002 11:21:18 -0000	1.6
  +++ BuildEvent.java	15 Feb 2002 13:59:38 -0000	1.7
  @@ -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
  @@ -55,18 +55,42 @@
   
   import java.util.EventObject;
   
  +/**
  + * Class representing an event occurring during a build. An
  + * event is built by specifying either a project, a task or a target.
  + * A project level event will only have a project reference;
  + * a target level event will have project and target references;
  + * a task level event will have project, target and task references.
  + */
   public class BuildEvent extends EventObject {
  +    
  +    /** Project which emitted the event. */
       private Project project;
  +    /** Target which emitted the event, if specified. */
       private Target target;
  +    /** Task which emitted the event, if specified. */
       private Task task;
  +    /** 
  +     * Message associated with the event. This is only used for
  +     * "messageLogged" events.
  +     */
       private String message;
  +    /**
  +     * The priority of the message, for "messageLogged" events.
  +     */
       private int priority = Project.MSG_VERBOSE;
  +    /**
  +     * The exception associated with this event, if any.
  +     * This is only used for "taskFinished", "targetFinished", 
  +     * and "buildFinished" events.
  +     */
       private Throwable exception;
   
       /**
  -     * Construct a BuildEvent for a project level event
  +     * Construct a BuildEvent for a project level event.
        *
        * @param project the project that emitted the event.
  +     *                Should not be <code>null</code>.
        */
       public BuildEvent(Project project) {
           super(project);
  @@ -76,9 +100,12 @@
       }
       
       /**
  -     * 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 <code>null</code>.
        */
       public BuildEvent(Target target) {
           super(target);
  @@ -88,9 +115,12 @@
       }
       
       /**
  -     * 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 <code>null</code>.
        */
       public BuildEvent(Task task) {
           super(task);
  @@ -99,24 +129,52 @@
           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 <code>null</code>.
  +     * @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 <code>null</code>.
  +     *
  +     * @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 <code>null</code>
  +     *          if this event is a project level event.
        */
       public Target getTarget() {
           
  @@ -124,39 +182,52 @@
       }
   
       /**
  -     *  Returns the task that fired this event.
  +     * Returns the task that fired this event.
  +     * 
  +     * @return the task that fired this event, or <code>null</code>
  +     *         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 <code>null</code>
  +     *         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.
  -     *
  -     *  @see BuildListener#taskFinished(BuildEvent)
  -     *  @see BuildListener#targetFinished(BuildEvent)
  -     *  @see BuildListener#buildFinished(BuildEvent)
  +     * 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 
  +     *         <code>null</code> if no exception has been set.
  +     *
  +     * @see BuildListener#taskFinished(BuildEvent)
  +     * @see BuildListener#targetFinished(BuildEvent)
  +     * @see BuildListener#buildFinished(BuildEvent)
        */
       public Throwable getException() {
           return exception;
  
  
  
  1.14      +63 -20    jakarta-ant/src/main/org/apache/tools/ant/BuildException.java
  
  Index: BuildException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/BuildException.java,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- BuildException.java	10 Jan 2002 11:21:18 -0000	1.13
  +++ BuildException.java	15 Feb 2002 13:59:38 -0000	1.14
  @@ -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 @@
   
       /**
        * 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 <code>null</code>.
        */
       public BuildException(String msg) {
           super(msg);
  @@ -88,8 +89,11 @@
       /**
        * 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 <code>null</code> unless a cause is specified.
  +     * @param cause The exception that might have caused this one.
  +     *              May be <code>null</code>.
        */
       public BuildException(String msg, Throwable cause) {
           super(msg);
  @@ -99,9 +103,13 @@
       /**
        * 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 <code>null</code> unless a cause is specified.
  +     * @param cause The exception that might have caused this one.
  +     *              May be <code>null</code>.
  +     * @param location The location in the project file where the error 
  +     *                 occurred. Must not be <code>null</code>.
        */
       public BuildException(String msg, Throwable cause, Location location) {
           this(msg, cause);
  @@ -110,7 +118,9 @@
   
       /**
        * 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 <code>null</code>.
        */
       public BuildException(Throwable cause) {
           super(cause.toString());
  @@ -118,10 +128,13 @@
       }
   
       /**
  -     * 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 <code>null</code>.
  +     * @param location The location in the project file where the error 
  +     *                 occurred. Must not be <code>null</code>.
        */
       public BuildException(String msg, Location location) {
           super(msg);
  @@ -131,8 +144,11 @@
       /**
        * 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 <code>null</code>.
  +     * @param location The location in the project file where the error 
  +     *                 occurred. Must not be <code>null</code>.
        */
       public BuildException(Throwable cause, Location location) {
           this(cause);
  @@ -140,7 +156,10 @@
       }
   
       /**
  -     * Returns the nested exception.
  +     * Returns the nested exception, if any.
  +     * 
  +     * @return the nested exception, or <code>null</code> if no
  +     *         exception is associated with this one
        */
       public Throwable getException() {
           return cause;
  @@ -148,30 +167,47 @@
   
       /**
        * 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 <code>null</code>.
        */
       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 <code>System.err</code>.
  +     */
       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 <code>null</code>.
  +     */
       public void printStackTrace(PrintStream ps) {
           synchronized (ps) {
               super.printStackTrace(ps);
  @@ -182,6 +218,13 @@
           }
       }
       
  +    /**
  +     * 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 <code>null</code>.
  +     */
       public void printStackTrace(PrintWriter pw) {
           synchronized (pw) {
               super.printStackTrace(pw);
  
  
  
  1.6       +44 -22    jakarta-ant/src/main/org/apache/tools/ant/BuildListener.java
  
  Index: BuildListener.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/BuildListener.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- BuildListener.java	10 Jan 2002 11:21:18 -0000	1.5
  +++ BuildListener.java	15 Feb 2002 13:59:38 -0000	1.6
  @@ -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 @@
   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 <code>null</code>.
        */
       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 <code>null</code>.
        *
  -     *  @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 <code>null</code>.
        *
  -     *  @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 <code>null</code>.
        *
  -     *  @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 <code>null</code>.
        *
  -     *  @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 <code>null</code>.
  +     *
  +     * @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 <code>null</code>.
        *
  -     *  @see BuildEvent#getMessage()
  -     *  @see BuildEvent#getPriority()
  +     * @see BuildEvent#getMessage()
  +     * @see BuildEvent#getPriority()
        */
       void messageLogged(BuildEvent event);
   }
  
  
  
  1.8       +22 -16    jakarta-ant/src/main/org/apache/tools/ant/BuildLogger.java
  
  Index: BuildLogger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/BuildLogger.java,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- BuildLogger.java	10 Jan 2002 11:21:19 -0000	1.7
  +++ BuildLogger.java	15 Feb 2002 13:59:38 -0000	1.8
  @@ -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 @@
   /**
    * 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 <code>System.out</code> unless redirected
by 
  + * the <code>-logfile</code> 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.
        * <P>
  -     * 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 <code>MSG_ERR</code>, <code>MSG_WARN</code>,

  +     * <code>MSG_INFO</code>, <code>MSG_VERBOSE</code>, 
  +     * <code>MSG_DEBUG</code>.
        *
        * @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 <code>null</code>.
        */
       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 <code>true</code> 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 <code>null<code>.
        */
       void setErrorPrintStream(PrintStream err);    
   }
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message