youys
/
ant

<!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>