Add documentation for new input stuff.

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

WHATSNEW

@@ -141,7 +141,7 @@ Other changes:
 * New tasks <bzip2> and <bunzip2> to pack and unpack files using the 
   BZip2 alogrithm.
 
-* New tasks <replaceregexp>, <checksum>, <translate>, <waitfor>, <input>,
+* New tasks <replaceregexp>, <checksum>, <translate>, <waitfor>, 
   <manifest>, <vsscp>, <vssadd>, <vsscreate>, <splash>, <basename>, <dirname>,
   <concat>.
 
@@ -329,6 +329,14 @@ Other changes:
   to the formatters (instead of sending it to the formatters
   exclusively).
 
+* Ant has now a pluggable way to prompt users for input, which is used
+  by the new <input> task.  IDE integrators can provide an
+  implementation of the InputHandler interface to decouple Ant's input
+  from the console.  An implementation that gets its input from a file
+  for unattended builds is part of Ant's distribution.
+
+  For more details see docs/manual/inputhandler.html.
+
 Changes from Ant 1.4 to Ant 1.4.1
 ===========================================
 

docs/manual/CoreTasks/input.html

@@ -9,19 +9,23 @@
 
 <h2><a name="input">Input</a></h2>
 <h3>Description</h3>
-<p>Allows user interaction during the build process by displaying a message and
-reading a line of input from the console (System.in). The user will need to press
-the Return key.
-</p>
-<p>The message displayed can be set via the message attribute
-or as character data nested into the element.</p>
-<p>Optinonally a set of valid imput arguments can be defined via the validargs
-attribute. Input task will require the user to reenter values until the entered
-value matches one of the predefined.</p>
-<p>Optionally a property can be created from the value entered by the user. This
-property can then be used during the following build run. Input behaves according
-to <a href="property.html">property task</a> which means that existing properties
-cannot be overriden.</p>
+
+<p>Allows user interaction during the build process by prompting for
+input.  To do so, it uses the configured 
+<a href="../inputhandler.html">InputHandler</a>.</p>
+
+<p>The prompt can be set via the message attribute or as character
+data nested into the element.</p>
+
+<p>Optinonally a set of valid imput arguments can be defined via the
+validargs attribute. Input task will no accept value that don't match
+one of the predefined.</p>
+
+<p>Optionally a property can be created from the value entered by the
+user. This property can then be used during the following build
+run. Input behaves according to <a href="property.html">property
+task</a> which means that existing properties cannot be overriden.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
@@ -31,37 +35,44 @@ cannot be overriden.</p>
   </tr>
   <tr>
     <td valign="top">message</td>
-    <td valign="top">the Message which gets displayed to the user during the build run.</td>
+    <td valign="top">the Message which gets displayed to the user
+    during the build run.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">validargs</td>
-    <td valign="top">comma separated String containing valid input arguments. If set,
-	    input task will reject any input not defined here and input task will
-		require the user to reenter arguments until the entered one matches one of the
-		predefined. Validargs are compared case sensitive. If you want 'a' and 'A' to
-    	be accepted you will need to define both arguments within validargs.</td>
+    <td valign="top">comma separated String containing valid input
+    arguments. If set, input task will reject any input not defined
+    here.  Validargs are compared case sensitive. If you want 'a' and
+    'A' to be accepted you will need to define both arguments within
+    validargs.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
     <td valign="top">addproperty</td>
-    <td valign="top">the name of a property to be created from input. Behaviour is equal
-	    to  <a href="property.html">property task</a> which means that existing properties
-  		cannot be overriden.</td>
+    <td valign="top">the name of a property to be created from
+    input. Behaviour is equal to <a href="property.html">property
+    task</a> which means that existing properties cannot be
+    overriden.</td>
     <td valign="top" align="center">No</td>
   </tr>
 </table>
 <h3>Examples</h3>
 <pre>  &lt;input/&gt;</pre>
-<p>Will pause the build run until return key is pressed.</p>
+<p>Will pause the build run until return key is pressed when using the
+<a href="../inputhandler.html#defaulthandler">default
+InputHandler</a>, the concrete behavior is defined by the InputHandler
+implementation you use.</p>
 <pre>  &lt;input&gt;Press Return key to continue...&lt;/input&gt;</pre>
-<p>Will display the message &quot;Press Return key to continue...&quot; and pause
-the build run until return key is pressed.</p>
+<p>Will display the message &quot;Press Return key to
+continue...&quot; and pause the build run until return key is pressed
+(again, the concrete behavior is implementation dependent).</p>
 <pre>  &lt;input
     message=&quot;Press Return key to continue...&quot;
   /&gt;</pre>
-<p>Will display the message &quot;Press Return key to continue...&quot; and pause
-the build run until return key is pressed.</p>
+<p>Will display the message &quot;Press Return key to
+continue...&quot; and pause the build run until return key is pressed
+(see above).</p>
 <pre>
   &lt;input
     message=&quot;All data is going to be deleted from DB continue (y/n)?&quot;
@@ -73,9 +84,10 @@ the build run until return key is pressed.</p>
   &lt;/condition&gt;
   &lt;fail if=&quot;do.abort&quot;&gt;Build aborted by user.&lt;/fail&gt;
 </pre>
-<p>Will display the message &quot;All data is going to be deleted from DB continue
-(y/n)?&quot; and require 'y+retrun key' to continue build or 'n+return key'
-to exit build with following message &quot;Build aborted by user.&quot;.</p>
+<p>Will display the message &quot;All data is going to be deleted from
+DB continue (y/n)?&quot; and require 'y' to continue build or 'n' to
+exit build with following message &quot;Build aborted by
+user.&quot;.</p>
 <pre>  &lt;input
     message=&quot;Please enter db-username:&quot;
     addproperty=&quot;db.user&quot;
@@ -84,7 +96,7 @@ to exit build with following message &quot;Build aborted by user.&quot;.</p>
 property <code>db.user</code> to the value entered by the user.</p>
 
 <hr>
-<p align="center">Copyright &copy; 2001 Apache Software Foundation. All rights
+<p align="center">Copyright &copy; 2001-2002 Apache Software Foundation. All rights
 Reserved.</p>
 </body>
 </html>

docs/manual/developlist.html

@@ -15,6 +15,7 @@
 <a href="develop.html#writingowntask">Writing Your Own Task</a><br>
 <a href="develop.html#buildevents">Build Events</a><br>
 <a href="develop.html#integration">Source-code Integration</a><br>
+<a href="inputhandler.html">InputHandler</a><br>
 
 </body>
 </html>

docs/manual/inputhandler.html

@@ -0,0 +1,89 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<title>InputHandler</title>
+</head>
+
+<body>
+<h1>InputHandler</h1>
+
+<h2>Overview</h2>
+
+<p>When a task wants to prompt a user for input, it doesn't simply
+read the input from the console as this would make it impossible to
+embed Ant in an IDE.  Instead it asks an implementation of the
+<code>org.apache.tools.ant.input.InputHandler</code> interface to
+prompt the user and hand the user input back to the task.</p>
+
+<p>To do this, the task creates an <code>InputRequest</code> object
+and passes it to the <code>InputHandler</code> Such an
+<code>InputRequest</code> may know whether a given user input is valid
+and the <code>InputHandler</code> is supposed to reject all invalid
+input.</p>
+
+<p>Exactly one <code>InputHandler</code> instance is associated with
+every Ant process, users can specify the implementation using the
+<code>-inputhandler</code> command line switch.</p>
+
+<h2>InputHandler</h2>
+
+<p>The <code>InputHandler</code> interface contains exactly one
+method</p>
+
+<pre>
+    void handleInput(InputRequest request) 
+        throws org.apache.tools.ant.BuildException;
+</pre>
+
+<p>with some pre- and postconditions.  The main postcondition is that
+this method must not return unless the <code>request</code> considers
+the user input valid, it is allowed to throw an exception in this
+situation.</p>
+
+<p>Ant comes with two built-in implementations of this interface:</p>
+
+<h3><a name="defaulthandler">DefaultInputHandler</a></h3>
+
+<p>This is the implementation you get, when you don't use the
+<code>-inputhandler</code> command line switch at all.  This
+implementation will print the prompt encapsulated in the
+<code>request</code> object to Ant's logging system and re-prompt for
+input until the user enters something that is considered valid input
+by the <code>request</code> object.  Input will be read from the
+console and the user will need to press the Return key.</p>
+
+<h3>PropertyFileInputHandler</h3>
+
+<p>This implementation is useful if you want to run unattended build
+processes.  It reads all input from a properties file and makes the
+build fail if it cannot find valid input in this file.  The name of
+the properties file must be specified in the Java system property
+<code>ant.input.properties</code>.</p>
+
+<p>The prompt encapsulated in a <code>request</code> will be used as
+the key when looking up the input inside the properties file.  If no
+input can be found, the input is considered invalid and an exception
+will be thrown.</p>
+
+<p><strong>Note</strong> that <code>ant.input.properties</code> must
+be a Java system property, not an Ant property.  I.e. you cannot
+define it as a simple parameter to <code>ant</code>, but you can
+define it inside the <code>ANT_OPTS</code> environment variable.</p>
+
+<h2>InputRequest</h2>
+
+<p>Instances of <code>org.apache.tools.ant.input.InputRequest</code>
+encapsulate the information necessary to ask a user for input and
+validate this input.</p>
+
+<p>The instances of <code>InputRequest</code> itself will accept any
+input, but subclasses may use stricter validations.
+<code>org.apache.tools.ant.input.MultipleChoiceInputRequest</code>
+should be used if the user input must be part of a predefined set of
+choices.</p>
+
+<hr>
+<p align="center">Copyright &copy; 2002 Apache Software Foundation. All rights
+Reserved.</p>
+</html>

docs/manual/running.html

@@ -76,12 +76,15 @@ Options:
   -D<property>=<value>   use value for given property
   -propertyfile <name>   load all properties from file with -D
                          properties taking precedence
+  -inputhandler <class>  the class which will handle input requests
   -find <file>           search for buildfile towards the root of the
                          filesystem and use it
 </pre>
 <p>For more information about <code>-logger</code> and
 <code>-listener</code> see the section <a
 href="listeners.html">Loggers &amp; Listeners</a>
+<p>For more information about <code>-inputhandler</code> see the
+section <a href="inputhandler.html">InputHandler</a>
 <h3>Examples</h3>
 <blockquote>
   <pre>ant</pre>

src/main/org/apache/tools/ant/Main.java

@@ -740,6 +740,7 @@ public class Main {
         msg.append("  -D<property>=<value>   use value for given property" + lSep);
         msg.append("  -propertyfile <name>   load all properties from file with -D" + lSep);
         msg.append("                         properties taking precedence" + lSep);
+        msg.append("  -inputhandler <class>  the class which will handle input requests" + lSep);
         msg.append("  -find <file>           search for buildfile towards the root of the" + lSep);
         msg.append("                         filesystem and use it" + lSep);
         System.out.println(msg.toString());