Add documentation on Loggers and Listeners.

Submitted by: Erik Hatcher <jakarta-ant@ehatchersolutions.com> git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@270143 13f79535-47bb-0310-9956-ffa450edef68
24 years ago · ccb4460206
--- a/docs/manual/credits.html
+++ b/docs/manual/credits.html
@@ -20,6 +20,7 @@
  <li>James Duncan Davidson (<a href="mailto:duncan@x180.com">duncan@x180.com</a>)</li>
  <li>Tom Dimock (<a href="mailto:tad1@cornell.edu">tad1@cornell.edu</a>)</li>
  <li>Peter Donald (<a href="mailto:donaldp@apache.org">donaldp@apache.org</a>)</li>
  <li>Erik Hatcher (<a href="mailto:erik@hatcher.net">erik@hatcher.net</a>)</li>
  <li>Diane Holt (<a href="mailto:holtdl@yahoo.com">holtdl@yahoo.com</a>)</li>
  <li>Bill Kelly (<a href="mailto:bill.kelly@softwired-inc.com">bill.kelly@softwired-inc.com</a>)</li>
  <li>Arnout J. Kuiper (<a href="mailto:ajkuiper@wxs.nl">ajkuiper@wxs.nl</a>)</li>
@@ -44,5 +45,4 @@ $Id$</p>
 Reserved.</p>
 </body>
 </html>
 </html>
--- a/docs/manual/listeners.html
+++ b/docs/manual/listeners.html
@@ -0,0 +1,216 @@
 <html>
 <head>
 <meta http-equiv="Content-Language" content="en-us">
 <title>Apache Ant User Manual</title>
 </head>
 <body>
 <h1>Listeners &amp; Loggers</h1>
 <h2><a name="Overview">Overview</a></h2>
 <p>Ant has two related features to allow the build process to be monitored: 
 listeners and loggers.</p>
 <h3><a name="Listeners">Listeners</a></h3>
 <p>A listener is alerted of the following events:</p>
 <ul>
  <li>build started</li>
  <li>build finished</li>
  <li>target started</li>
  <li>target finished</li>
  <li>task started</li>
  <li>task finished</li>
  <li>message logged</li>
 </ul>
 <h3><a name="Loggers">Loggers</a></h3>
 <p>Loggers extend the capabilities of listeners and add the following features:</p>
 <ul>
  <li>Receives a handle to the standard output and error print streams and 
  therefore can log information to the console or the -logfile specified file.</li>
  <li>Logging level (-quiet, -verbose, -debug) aware</li>
  <li>Emacs-mode aware</li>
 </ul>
 <h2><a name="builtin">Built-in Listeners/Loggers</a></h2>
 <table border="1" cellspacing="1" width="100%" id="AutoNumber1">
  <tr>
    <td width="33%">Classname</td>
    <td width="33%">Description</td>
    <td width="34%">Type</td>
  </tr>
  <tr>
    <td width="33%"><code><a href="#DefaultLogger">org.apache.tools.ant.DefaultLogger</a></code></td>
    <td width="33%">The logger used implicitly unless overridden with the 
    <code>-logger</code> command-line switch.</td>
    <td width="34%">BuildLogger</td>
  </tr>
  <tr>
    <td width="33%"><code><a href="#NoBannerLogger">
    org.apache.tools.ant.NoBannerLogger</a></code></td>
    <td width="33%">This logger omits output of empty target output.</td>
    <td width="34%">BuildLogger</td>
  </tr>
  <tr>
    <td width="33%"><code><a href="#MailLogger">
    org.apache.tools.ant.listener.MailLogger</a></code></td>
    <td width="33%">Extends DefaultLogger such that output is still generated 
    the same, and when the build is finished an e-mail can be sent.</td>
    <td width="34%">BuildLogger</td>
  </tr>
  <tr>
    <td width="33%"><code><a href="#Log4jListener">
    org.apache.tools.ant.listener.Log4jListener</a></code></td>
    <td width="33%">Passes events to Log4j for highly customizable logging.</td>
    <td width="34%">BuildListener</td>
  </tr>
  <tr>
    <td width="33%"><code><a href="#XmlLogger">org.apache.tools.ant.XmlLogger</a></code></td>
    <td width="33%">Writes the build information to an XML file.</td>
    <td width="34%">BuildListener</td>
  </tr>
 </table>
 <h3><a name="DefaultLogger">DefaultLogger</a></h3>
 <p>Simply run Ant normally, or:</p>
 <blockquote>
 <p><code>ant -logger org.apache.tools.ant.DefaultLogger</code></p>
 </blockquote>
 <h3><a name="NoBannerLogger">NoBannerLogger</a></h3>
 <p>Removes output of empty target output.</p>
 <blockquote>
 <p><code>ant -logger org.apache.tools.ant.NoBannerLogger</code></p>
 </blockquote>
 <h3><a name="MailLogger">MailLogger</a></h3>
 <p>The MailLogger captures all output logged through DefaultLogger (standard Ant 
 output) and will send success and failure messages to unique e-mail lists, with 
 control for turning off success or failure messages individually.</p>
 <p>Properties controlling the operation of MailLogger:</p>
 <table border="1" cellspacing="1" width="100%" id="AutoNumber2">
  <tr>
    <th width="337">Property</th>
    <th width="63%">Description</th>
    <th width="63%">Required</th>
  </tr>
  <tr>
    <td width="337">MailLogger.mailhost </td>
    <td width="63%">Mail server to use</td>
    <td width="63%">No, default &quot;localhost&quot;</td>
  </tr>
  <tr>
    <td width="337">MailLogger.from</td>
    <td width="63%">Mail &quot;from&quot; address</td>
    <td width="63%">Yes, if mail needs to be sent</td>
  </tr>
  <tr>
    <td width="337">MailLogger.failure.notify </td>
    <td width="63%">Send build failure e-mails?</td>
    <td width="63%">No, default &quot;true&quot;</td>
  </tr>
  <tr>
    <td width="337">MailLogger.success.notify </td>
    <td width="63%">Send build success e-mails?</td>
    <td width="63%">No, default &quot;true&quot;</td>
  </tr>
  <tr>
    <td width="337">MailLogger.failure.to </td>
    <td width="63%">Address(es) to send failure messages to, comma-separated</td>
    <td width="63%">Yes, if failure mail is to be sent</td>
  </tr>
  <tr>
    <td width="337">MailLogger.success.to </td>
    <td width="63%">Address(es) to send success messages to, comma-separated</td>
    <td width="63%">Yes, if success mail is to be sent</td>
  </tr>
  <tr>
    <td width="337">MailLogger.failure.subject </td>
    <td width="63%">Subject of failed build</td>
    <td width="63%">No, default &quot;Build Failure&quot;</td>
  </tr>
  <tr>
    <td width="337">MailLogger.success.subject </td>
    <td width="63%">Subject of successful build</td>
    <td width="63%">No, default &quot;Build Success&quot;</td>
  </tr>
  <tr>
    <td width="337">MailLogger.properties.file </td>
    <td width="63%">Filename of properties file that will override other values.</td>
    <td width="63%">No</td>
  </tr>
 </table>
 <blockquote>
 <p><code>ant -logger org.apache.tools.ant.MailLogger</code></p>
 </blockquote>
 <h3><a name="Log4jListener">Log4jListener</a></h3>
 <p>Passes build events to Log4j, using the full classname's of the generator of 
 each build event as the category:</p>
 <ul>
  <li>build started / build finished - org.apache.tools.ant.Project</li>
  <li>target started / target finished - org.apache.tools.ant.Target</li>
  <li>task started / task finished - the fully qualified classname of the task</li>
  <li>message logged - the classname of one of the above, so if a task logs a 
  message, its classname is the category used, and so on.</li>
 </ul>
 <p>All start events are logged as INFO.&nbsp; Finish events are either logged as 
 INFO or ERROR depending on whether the build failed during that stage. Message 
 events are logged according to their Ant logging level, mapping directly to a 
 corresponding Log4j level.</p>
 <blockquote>
 <p><code>ant -listener org.apache.tools.ant.listener.Log4jListener</code></p>
 </blockquote>
 <h3><a name="XmlLogger">XmlLogger</a></h3>
 <p>Writes all build information out to an XML file named log.xml, or the value 
 of the XmlLogger.file property if present.</p>
 <blockquote>
 <p><code>ant -listener org.apache.tools.ant.XmlLogger</code></p>
 </blockquote>
 <h2><a name="dev">Writing your own</a></h2>
 <p>See the <a href="develop.html#buildevents">Build Events</a> section for 
 developers.</p>
 <p>Notes:</p>
 <ul>
  <li>A listener or logger should not write to standard output or error - Ant 
  captures these internally and may cause an infinite loop.</li>
 </ul>
 <hr>
 <p align="center">Copyright &copy; 2000,2001 Apache Software Foundation. All rights
 Reserved.</p>
 </body>
 </html>
--- a/docs/manual/running.html
+++ b/docs/manual/running.html
@@ -76,6 +76,9 @@ Options:
 -find <i>file</i>             search for buildfile towards the root of the filesystem and use the first one found
 -D<i>property</i>=<i>value</i>       set <i>property</i> to <i>value</i>
 </pre>
 <p>For more information about <code>-logger</code> and
 <code>-listener</code> see the section <a
 href="listeners.html">Loggers &amp; Listeners</a>
 <h3>Examples</h3>
 <blockquote>
  <pre>ant</pre>
--- a/docs/manual/toc.html
+++ b/docs/manual/toc.html
@@ -15,6 +15,7 @@
 <a href="runninglist.html" target="navFrame">Running Ant</a><br>
 <a href="coretasklist.html" target="navFrame">Built-in Tasks</a><br>
 <a href="optionaltasklist.html" target="navFrame">Optional Tasks</a><br>
 <a target="mainFrame" href="listeners.html">Loggers &amp; Listeners</a><br>
 <a href="ide.html" target="navFrame">Editor/IDE Integration</a><br>
 <a href="developlist.html" target="navFrame">Developing with Ant</a><br>
 <a href="api/index.html" target="_top">Ant API</a><br>
@@ -23,5 +24,4 @@
 <a href="credits.html">Authors</a><br>
 </body>
 </html>
 </html>
--- a/src/main/org/apache/tools/ant/listener/MailLogger.java
+++ b/src/main/org/apache/tools/ant/listener/MailLogger.java
@@ -73,15 +73,16 @@ import org.apache.tools.mail.MailMessage;
 *  results. The following Project properties are used to send the mail.
 *  <ul>
 *    <li> MailLogger.mailhost [default: localhost] - Mail server to use</li>
 *
 *    <li> MailLogger.from [required] - Mail "from" address</li>
 *    <li> MailLogger.failure.notify [default: true] - Send build failure
 *    e-mails?</li>
 *    <li> MailLogger.success.notify [default: true] - Send build success
 *    e-mails?</li>
 *    <li> MailLogger.failure.to [required if build failed] - Address to send
 *    failure messages to</li>
 *    <li> MailLogger.success.to [required if build failed] - Address to send
 *    success messages to</li>
 *    <li> MailLogger.failure.to [required if failure mail to be sent] - Address
 *    to send failure messages to</li>
 *    <li> MailLogger.success.to [required if success mail to be sent] - Address
 *    to send success messages to</li>
 *    <li> MailLogger.failure.subject [default: "Build Failure"] - Subject of
 *    failed build</li>
 *    <li> MailLogger.success.subject [default: "Build Success"] - Subject of
@@ -89,17 +90,19 @@ import org.apache.tools.mail.MailMessage;
 *  </ul>
 *  These properties are set using standard Ant property setting mechanisms
 *  (&lt;property&gt;, command-line -D, etc). Ant properties can be overridden
 *  by specifying the filename of a properties file in the
 *  <i>MailLogger.properties.file property</i>. Any properties defined in that file
 *  will override Ant properties.
 *  by specifying the filename of a properties file in the <i>
 *  MailLogger.properties.file property</i> . Any properties defined in that
 *  file will override Ant properties.
 *
 *@author     Erik Hatcher <a href="mailto:erik@hatcher.net">erik@hatcher.net</a>
 *@author     Erik Hatcher <a href="mailto:erik@hatcher.net">erik@hatcher.net
 *      </a>
 *@created    December 12, 2001
 */
 public class MailLogger extends DefaultLogger {
  private StringBuffer buffer = new StringBuffer();
  /**
   *  Sends an e-mail with the log results.
   *
@@ -125,11 +128,14 @@ public class MailLogger extends DefaultLogger {
      }
      catch (IOException ioe) {
        // ignore because properties file is not required
      } finally {
      }
      finally {
        if (is != null) {
          try {
            is.close();
          } catch (IOException e) {}
          }
          catch (IOException e) {
          }
        }
      }
    }
@@ -143,9 +149,6 @@ public class MailLogger extends DefaultLogger {
    String prefix = success ? "success" : "failure";
    try {
      String mailhost = getValue(properties, "mailhost", "localhost");
      String from = getValue(properties, "from", null);
      boolean notify = Project.toBoolean(getValue(properties,
          prefix + ".notify", "on"));
@@ -153,6 +156,9 @@ public class MailLogger extends DefaultLogger {
        return;
      }
      String mailhost = getValue(properties, "mailhost", "localhost");
      String from = getValue(properties, "from", null);
      String toList = getValue(properties, prefix + ".to", null);
      String subject = getValue(properties, prefix + ".subject",
          (success) ? "Build Success" : "Build Failure");
@@ -180,14 +186,13 @@ public class MailLogger extends DefaultLogger {
   *  Gets the value of a property.
   *
   *@param  properties     Properties to obtain value from
   *@param  name           suffix of property name. "MailLogger."
   will be prepended internally.
   *@param  defaultValue   value returned if not present in the
   properties. Set to null to make required.
   *@return                The value of the property, or default
   value.
   *@exception  Exception  thrown if no default value is specified
   and the property is not present in properties.
   *@param  name           suffix of property name. "MailLogger." will be
   *      prepended internally.
   *@param  defaultValue   value returned if not present in the properties. Set
   *      to null to make required.
   *@return                The value of the property, or default value.
   *@exception  Exception  thrown if no default value is specified and the
   *      property is not present in properties.
   */
  private String getValue(Hashtable properties, String name, String defaultValue)
       throws Exception {