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 Apache Ant in an IDE. Instead it asks an implementation
of the org.apache.tools.ant.input.InputHandler interface to prompt the
user and hand the user input back to the task.
To do this, the task creates an InputRequest object and passes it to
the InputHandler. Such an InputRequest may know
whether a given user input is valid and the InputHandler is supposed to
reject all invalid input.
Exactly one InputHandler instance is associated with every Ant process,
users can specify the implementation using the -inputhandler command line switch.
The InputHandler interface contains exactly one method
void handleInput(InputRequest request)
throws org.apache.tools.ant.BuildException;
with some pre- and postconditions. The main postcondition is that this method must not return
unless the request considers the user input valid; it is allowed to throw an exception
in this situation.
Ant comes with three built-in implementations of this interface:
This is the implementation you get, when you don't use the -inputhandler command line
switch at all. This implementation will print the prompt encapsulated in the request
object to Ant's logging system and re-prompt for input until the user enters something that is
considered valid input by the request object. Input will be read from the console and
the user will need to press the Return key.
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 ant.input.properties.
The prompt encapsulated in a request 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.
Note that ant.input.properties must be a Java system property, not
an Ant property. I.e. you cannot define it as a simple parameter to ant, but you can
define it inside the ANT_OPTS environment variable.
Since Ant 1.7
Like the default implementation, this InputHandler reads from standard input. However, it consumes all available input. This behavior is useful for sending Ant input via an OS pipe.
Since Ant 1.7.1
This InputHandler calls System.console().readPassword(), available
since Java 6. On earlier platforms it falls back to the behavior
of DefaultInputHandler.
Instances of org.apache.tools.ant.input.InputRequest encapsulate the
information necessary to ask a user for input and validate this input.
The instances of InputRequest itself will accept any input, but
subclasses may use stricter
validations. org.apache.tools.ant.input.MultipleChoiceInputRequest should
be used if the user input must be part of a predefined set of choices.