From ccb44602065cdba71ee47022e8fe49bf67d7d60e Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 14 Dec 2001 12:23:50 +0000 Subject: [PATCH] Add documentation on Loggers and Listeners. Submitted by: Erik Hatcher git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@270143 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/credits.html | 4 +- docs/manual/listeners.html | 216 ++++++++++++++++++ docs/manual/running.html | 3 + docs/manual/toc.html | 4 +- .../apache/tools/ant/listener/MailLogger.java | 49 ++-- 5 files changed, 250 insertions(+), 26 deletions(-) create mode 100644 docs/manual/listeners.html diff --git a/docs/manual/credits.html b/docs/manual/credits.html index dec169003..0ef55501c 100644 --- a/docs/manual/credits.html +++ b/docs/manual/credits.html @@ -20,6 +20,7 @@
  • James Duncan Davidson (duncan@x180.com)
  • Tom Dimock (tad1@cornell.edu)
  • Peter Donald (donaldp@apache.org)
    • +
  • Erik Hatcher (erik@hatcher.net)
  • Diane Holt (holtdl@yahoo.com)
  • Bill Kelly (bill.kelly@softwired-inc.com)
  • Arnout J. Kuiper (ajkuiper@wxs.nl)
    • @@ -44,5 +45,4 @@ $Id$

    Reserved.

    - - + \ No newline at end of file diff --git a/docs/manual/listeners.html b/docs/manual/listeners.html new file mode 100644 index 000000000..054046c73 --- /dev/null +++ b/docs/manual/listeners.html @@ -0,0 +1,216 @@ + + + + +Apache Ant User Manual + + + +

    Listeners & Loggers

    + +

    Overview

    + +

    Ant has two related features to allow the build process to be monitored: +listeners and loggers.

    + +

    Listeners

    + +

    A listener is alerted of the following events:

    + + + +

    Loggers

    + +

    Loggers extend the capabilities of listeners and add the following features:

    + + + +

    Built-in Listeners/Loggers

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ClassnameDescriptionType
    org.apache.tools.ant.DefaultLoggerThe logger used implicitly unless overridden with the + -logger command-line switch.BuildLogger
    + org.apache.tools.ant.NoBannerLoggerThis logger omits output of empty target output.BuildLogger
    + org.apache.tools.ant.listener.MailLoggerExtends DefaultLogger such that output is still generated + the same, and when the build is finished an e-mail can be sent.BuildLogger
    + org.apache.tools.ant.listener.Log4jListenerPasses events to Log4j for highly customizable logging.BuildListener
    org.apache.tools.ant.XmlLoggerWrites the build information to an XML file.BuildListener
    +

    DefaultLogger

    + +

    Simply run Ant normally, or:

    + +
    + +

    ant -logger org.apache.tools.ant.DefaultLogger

    + +
    + +

    NoBannerLogger

    + +

    Removes output of empty target output.

    + +
    + +

    ant -logger org.apache.tools.ant.NoBannerLogger

    + +
    + +

    MailLogger

    + +

    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.

    +

    Properties controlling the operation of MailLogger:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PropertyDescriptionRequired
    MailLogger.mailhost Mail server to useNo, default "localhost"
    MailLogger.fromMail "from" addressYes, if mail needs to be sent
    MailLogger.failure.notify Send build failure e-mails?No, default "true"
    MailLogger.success.notify Send build success e-mails?No, default "true"
    MailLogger.failure.to Address(es) to send failure messages to, comma-separatedYes, if failure mail is to be sent
    MailLogger.success.to Address(es) to send success messages to, comma-separatedYes, if success mail is to be sent
    MailLogger.failure.subject Subject of failed buildNo, default "Build Failure"
    MailLogger.success.subject Subject of successful buildNo, default "Build Success"
    MailLogger.properties.file Filename of properties file that will override other values.No
    +
    + +

    ant -logger org.apache.tools.ant.MailLogger

    + +
    + +

    Log4jListener

    + +

    Passes build events to Log4j, using the full classname's of the generator of +each build event as the category:

    + + + +

    All start events are logged as INFO.  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.

    + +
    + +

    ant -listener org.apache.tools.ant.listener.Log4jListener

    + +
    + +

    XmlLogger

    + +

    Writes all build information out to an XML file named log.xml, or the value +of the XmlLogger.file property if present.

    + +
    + +

    ant -listener org.apache.tools.ant.XmlLogger

    + +
    + +

    Writing your own

    + +

    See the Build Events section for +developers.

    + +

    Notes:

    + + + +
    +

    Copyright © 2000,2001 Apache Software Foundation. All rights +Reserved.

    + + + \ No newline at end of file diff --git a/docs/manual/running.html b/docs/manual/running.html index b70685bae..ab79249ff 100644 --- a/docs/manual/running.html +++ b/docs/manual/running.html @@ -76,6 +76,9 @@ Options: -find file search for buildfile towards the root of the filesystem and use the first one found -Dproperty=value set property to value +

    For more information about -logger and +-listener see the section Loggers & Listeners

    Examples

    ant
    diff --git a/docs/manual/toc.html b/docs/manual/toc.html index 0c878c47c..ac10af1a4 100644 --- a/docs/manual/toc.html +++ b/docs/manual/toc.html @@ -15,6 +15,7 @@ Running Ant
    Built-in Tasks
    Optional Tasks
    +Loggers & Listeners
    Editor/IDE Integration
    Developing with Ant
    Ant API
    @@ -23,5 +24,4 @@ Authors
    - - + \ No newline at end of file diff --git a/src/main/org/apache/tools/ant/listener/MailLogger.java b/src/main/org/apache/tools/ant/listener/MailLogger.java index 37b987b3e..5a0609ffe 100644 --- 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. *
      *
    • MailLogger.mailhost [default: localhost] - Mail server to use
      • + * *
    • MailLogger.from [required] - Mail "from" address
      • *
    • MailLogger.failure.notify [default: true] - Send build failure * e-mails?
      • *
    • MailLogger.success.notify [default: true] - Send build success * e-mails?
      • - *
    • MailLogger.failure.to [required if build failed] - Address to send - * failure messages to
      • - *
    • MailLogger.success.to [required if build failed] - Address to send - * success messages to
      • + *
    • MailLogger.failure.to [required if failure mail to be sent] - Address + * to send failure messages to
      • + *
    • MailLogger.success.to [required if success mail to be sent] - Address + * to send success messages to
      • *
    • MailLogger.failure.subject [default: "Build Failure"] - Subject of * failed build
      • *
    • MailLogger.success.subject [default: "Build Success"] - Subject of @@ -89,17 +90,19 @@ import org.apache.tools.mail.MailMessage; *
    * These properties are set using standard Ant property setting mechanisms * (<property>, command-line -D, etc). Ant properties can be overridden - * by specifying the filename of a properties file in the - * MailLogger.properties.file property. Any properties defined in that file - * will override Ant properties. + * by specifying the filename of a properties file in the + * MailLogger.properties.file property . Any properties defined in that + * file will override Ant properties. * - *@author Erik Hatcher erik@hatcher.net + *@author Erik Hatcher erik@hatcher.net + * *@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 {