bodewig 01/12/14 04:23:50
Modified: docs/manual credits.html running.html toc.html
src/main/org/apache/tools/ant/listener MailLogger.java
Added: docs/manual listeners.html
Log:
Add documentation on Loggers and Listeners.
Submitted by: Erik Hatcher <[EMAIL PROTECTED]>
Revision Changes Path
1.8 +3 -3 jakarta-ant/docs/manual/credits.html
Index: credits.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/credits.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- credits.html 2001/11/25 07:54:28 1.7
+++ credits.html 2001/12/14 12:23:50 1.8
@@ -20,6 +20,7 @@
<li>James Duncan Davidson (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Tom Dimock (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Peter Donald (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
+ <li>Erik Hatcher (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Diane Holt (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Bill Kelly (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Arnout J. Kuiper (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
@@ -37,12 +38,11 @@
<center>
<p>Version: @VERSION@<br>
-$Id: credits.html,v 1.7 2001/11/25 07:54:28 umagesh Exp $</p>
+$Id: credits.html,v 1.8 2001/12/14 12:23:50 bodewig Exp $</p>
</center>
<hr>
<p align="center">Copyright © 2000,2001 Apache Software Foundation. All
rights
Reserved.</p>
</body>
-</html>
-
+</html>
\ No newline at end of file
1.7 +3 -0 jakarta-ant/docs/manual/running.html
Index: running.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/running.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- running.html 2001/12/13 17:16:26 1.6
+++ running.html 2001/12/14 12:23:50 1.7
@@ -76,6 +76,9 @@
-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 & Listeners</a>
<h3>Examples</h3>
<blockquote>
<pre>ant</pre>
1.10 +2 -2 jakarta-ant/docs/manual/toc.html
Index: toc.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/toc.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- toc.html 2001/12/13 17:16:26 1.9
+++ toc.html 2001/12/14 12:23:50 1.10
@@ -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 & 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>
\ No newline at end of file
1.1 jakarta-ant/docs/manual/listeners.html
Index: listeners.html
===================================================================
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Apache Ant User Manual</title>
</head>
<body>
<h1>Listeners & 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 "localhost"</td>
</tr>
<tr>
<td width="337">MailLogger.from</td>
<td width="63%">Mail "from" 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 "true"</td>
</tr>
<tr>
<td width="337">MailLogger.success.notify </td>
<td width="63%">Send build success e-mails?</td>
<td width="63%">No, default "true"</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 "Build Failure"</td>
</tr>
<tr>
<td width="337">MailLogger.success.subject </td>
<td width="63%">Subject of successful build</td>
<td width="63%">No, default "Build Success"</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. 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 © 2000,2001 Apache Software Foundation. All
rights
Reserved.</p>
</body>
</html>
1.2 +27 -22
jakarta-ant/src/main/org/apache/tools/ant/listener/MailLogger.java
Index: MailLogger.java
===================================================================
RCS file:
/home/cvs/jakarta-ant/src/main/org/apache/tools/ant/listener/MailLogger.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- MailLogger.java 2001/12/13 12:23:17 1.1
+++ MailLogger.java 2001/12/14 12:23:50 1.2
@@ -73,15 +73,16 @@
* 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 @@
* </ul>
* 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
- * <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.
*
- [EMAIL PROTECTED] Erik Hatcher <a href="mailto:[EMAIL
PROTECTED]">[EMAIL PROTECTED]</a>
+ [EMAIL PROTECTED] Erik Hatcher <a href="mailto:[EMAIL
PROTECTED]">[EMAIL PROTECTED]
+ * </a>
[EMAIL PROTECTED] 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 @@
}
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 @@
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 @@
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 @@
* Gets the value of a property.
*
[EMAIL PROTECTED] properties Properties to obtain value from
- [EMAIL PROTECTED] name suffix of property name. "MailLogger."
- will be prepended internally.
- [EMAIL PROTECTED] defaultValue value returned if not present in the
- properties. Set to null to make required.
- [EMAIL PROTECTED] The value of the property, or default
- value.
- [EMAIL PROTECTED] Exception thrown if no default value is specified
- and the property is not present in properties.
+ [EMAIL PROTECTED] name suffix of property name. "MailLogger."
will be
+ * prepended internally.
+ [EMAIL PROTECTED] defaultValue value returned if not present in the
properties. Set
+ * to null to make required.
+ [EMAIL PROTECTED] The value of the property, or default
value.
+ [EMAIL PROTECTED] 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 {
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
