bodewig 02/04/22 06:22:57
Modified: . WHATSNEW
docs/manual developlist.html running.html
docs/manual/CoreTasks input.html
src/main/org/apache/tools/ant Main.java
Added: docs/manual inputhandler.html
Log:
Add documentation for new input stuff.
Revision Changes Path
1.257 +9 -1 jakarta-ant/WHATSNEW
Index: WHATSNEW
===================================================================
RCS file: /home/cvs/jakarta-ant/WHATSNEW,v
retrieving revision 1.256
retrieving revision 1.257
diff -u -r1.256 -r1.257
--- WHATSNEW 18 Apr 2002 14:18:59 -0000 1.256
+++ WHATSNEW 22 Apr 2002 13:22:56 -0000 1.257
@@ -141,7 +141,7 @@
* 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>.
@@ -328,6 +328,14 @@
generated by tests will be sent to Ant's logging system as well as
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
===========================================
1.2 +1 -0 jakarta-ant/docs/manual/developlist.html
Index: developlist.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/developlist.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- developlist.html 13 Dec 2001 17:16:26 -0000 1.1
+++ developlist.html 22 Apr 2002 13:22:56 -0000 1.2
@@ -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>
1.12 +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.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- running.html 4 Feb 2002 20:57:49 -0000 1.11
+++ running.html 22 Apr 2002 13:22:56 -0000 1.12
@@ -76,12 +76,15 @@
-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 & 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>
1.1 jakarta-ant/docs/manual/inputhandler.html
Index: inputhandler.html
===================================================================
<!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 © 2002 Apache Software Foundation. All rights
Reserved.</p>
</html>
1.6 +43 -31 jakarta-ant/docs/manual/CoreTasks/input.html
Index: input.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/CoreTasks/input.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- input.html 3 Feb 2002 22:00:42 -0000 1.5
+++ input.html 22 Apr 2002 13:22:56 -0000 1.6
@@ -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 @@
</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> <input/></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> <input>Press Return key to continue...</input></pre>
-<p>Will display the message "Press Return key to continue..." and
pause
-the build run until return key is pressed.</p>
+<p>Will display the message "Press Return key to
+continue..." and pause the build run until return key is pressed
+(again, the concrete behavior is implementation dependent).</p>
<pre> <input
message="Press Return key to continue..."
/></pre>
-<p>Will display the message "Press Return key to continue..." and
pause
-the build run until return key is pressed.</p>
+<p>Will display the message "Press Return key to
+continue..." and pause the build run until return key is pressed
+(see above).</p>
<pre>
<input
message="All data is going to be deleted from DB continue
(y/n)?"
@@ -73,9 +84,10 @@
</condition>
<fail if="do.abort">Build aborted by user.</fail>
</pre>
-<p>Will display the message "All data is going to be deleted from DB
continue
-(y/n)?" and require 'y+retrun key' to continue build or 'n+return key'
-to exit build with following message "Build aborted by user.".</p>
+<p>Will display the message "All data is going to be deleted from
+DB continue (y/n)?" and require 'y' to continue build or 'n' to
+exit build with following message "Build aborted by
+user.".</p>
<pre> <input
message="Please enter db-username:"
addproperty="db.user"
@@ -84,7 +96,7 @@
property <code>db.user</code> to the value entered by the user.</p>
<hr>
-<p align="center">Copyright © 2001 Apache Software Foundation. All
rights
+<p align="center">Copyright © 2001-2002 Apache Software Foundation. All
rights
Reserved.</p>
</body>
</html>
1.64 +1 -0 jakarta-ant/src/main/org/apache/tools/ant/Main.java
Index: Main.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/Main.java,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -r1.63 -r1.64
--- Main.java 22 Apr 2002 11:55:21 -0000 1.63
+++ Main.java 22 Apr 2002 13:22:57 -0000 1.64
@@ -740,6 +740,7 @@
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());
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
