# InputHandler

## Overview

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.

## InputHandler

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:

### DefaultInputHandler

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.

### PropertyFileInputHandler

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.

### GreedyInputHandler

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.

### SecureInputHandler

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`.

## InputRequest

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.