New task <fail> which does nothing but throw an exception.

Submitted by:	Nico Seessle <nico@seessle.de>


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@267974 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -35,7 +35,7 @@ behavior has been dropped.
 Other changes:
 --------------
 
-* New tasks: antstructure, cab, execon, ftp, genkey, junit, sql, javacc, jjtree, starteam.
+* New tasks: antstructure, cab, execon, fail, ftp, genkey, junit, sql, javacc, jjtree, starteam.
 
 * New tasks mparse pending documentation.
 

docs/index.html

@@ -836,6 +836,7 @@ same patterns as the example before.</p>
   <li><a href="#echo">Echo</a></li>
   <li><a href="#exec">Exec</a></li>
   <li><a href="#exec">ExecOn</a></li>
+  <li><a href="#fail">Fail</a></li>
   <li><a href="#filter">Filter</a></li>
   <li><a href="#fixcrlf">FixCRLF</a></li>
   <li><a href="#genkey">GenKey</a></li>
@@ -1646,11 +1647,47 @@ files below <code>/tmp</code> not ending in <code>.txt</code> and all
 files of the FileSet with <code>id</code> <code>other.files</code> to
 the command line.</p>
 <hr>
+<h2><a name="fail">Fail</a></h2>
+<h3>Description</h3>
+<p>Exits the current build (just throwing a BuildException), optionally printing additional information.</p>
+<h3>Parameters</h3>
+<table border="1" cellpadding="2" cellspacing="0">
+  <tr>
+    <td valign="top"><b>Attribute</b></td>
+    <td valign="top"><b>Description</b></td>
+    <td align="center" valign="top"><b>Required</b></td>
+  </tr>
+  <tr>
+    <td valign="top">message</td>
+    <td valign="top">A message giving further information on why the build exited</td>
+    <td align="center" valign="top">No</td>
+  </tr>
+</table>
+<h3>Examples</h3>
+<pre>  &lt;fail/&gt;</pre>
+<p>will exit the current build with no further information given.
+<pre>
+BUILD FAILED
+
+build.xml:4: No message
+</pre>
+</p>
+<pre>  &lt;fail message=&quot;Something wrong here.&quot;/&gt;</pre>
+<p>will exit the current build and print something like the following to whereever
+your output goes:
+<pre>
+BUILD FAILED
+
+build.xml:4: Something wrong here.
+</pre>
+</p>
+<hr>
 <h2><a name="filter">Filter</a></h2>
 <h3>Description</h3>
 <p>Sets a token filter for this project. Token filters are used by all tasks
 that perform file copying operations through the Project commodity methods.</p>
 <p>Note: the token string must not contain the separators chars (@).</p>
+<hr>
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>

src/main/org/apache/tools/ant/taskdefs/Exit.java

@@ -0,0 +1,79 @@
+/*
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2000 The Apache Software Foundation.  All rights 
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer. 
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:  
+ *       "This product includes software developed by the 
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written 
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+
+package org.apache.tools.ant.taskdefs;
+
+import org.apache.tools.ant.*;
+
+/**
+ * Just exit the active build, giving an additional message 
+ * if available.
+ *
+ * @author Nico Seessle <nico@seessle.de>
+ */
+public class Exit extends Task { 
+    private String message;
+    
+    public void setMessage(String value) { 
+        this.message = value;
+    }
+    
+    public void execute() throws BuildException {
+        if (message != null && message.length() > 0) { 
+            throw new BuildException(message);
+        } else {
+            throw new BuildException("No message");
+        }
+    }
+}

src/main/org/apache/tools/ant/taskdefs/defaults.properties

@@ -41,6 +41,7 @@ execon=org.apache.tools.ant.taskdefs.ExecuteOn
 antcall=org.apache.tools.ant.taskdefs.CallTarget
 sql=org.apache.tools.ant.taskdefs.SQLExec
 mail=org.apache.tools.ant.taskdefs.SendEmail
+fail=org.apache.tools.ant.taskdefs.Exit
 
 # optional tasks
 script=org.apache.tools.ant.taskdefs.optional.Script