InputHandler

Overview

When a task wants to prompt a user for input, it doesn't simplyread the input from the console as this would make it impossible toembed Apache Ant in an IDE. Instead it asks an implementation of theorg.apache.tools.ant.input.InputHandler interface toprompt the user and hand the user input back to the task.

To do this, the task creates an InputRequest objectand passes it to the InputHandler Such anInputRequest may know whether a given user input is validand the InputHandler is supposed to reject all invalidinput.

Exactly one InputHandler instance is associated withevery Ant process, users can specify the implementation using the-inputhandler command line switch.

InputHandler

The InputHandler interface contains exactly onemethod

 void handleInput(InputRequest request) throws org.apache.tools.ant.BuildException;

with some pre- and postconditions. The main postcondition is thatthis method must not return unless the request considersthe user input valid, it is allowed to throw an exception in thissituation.

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. Thisimplementation will print the prompt encapsulated in therequest object to Ant's logging system and re-prompt forinput until the user enters something that is considered valid inputby the request object. Input will be read from theconsole and the user will need to press the Return key.

PropertyFileInputHandler

This implementation is useful if you want to run unattended buildprocesses. It reads all input from a properties file and makes thebuild fail if it cannot find valid input in this file. The name ofthe properties file must be specified in the Java system propertyant.input.properties.

The prompt encapsulated in a request will be used asthe key when looking up the input inside the properties file. If noinput can be found, the input is considered invalid and an exceptionwill be thrown.

Note that ant.input.properties mustbe a Java system property, not an Ant property. I.e. you cannotdefine it as a simple parameter to ant, but you candefine it inside the ANT_OPTS environment variable.

GreedyInputHandler

Like the default implementation, this InputHandler reads from standardinput. However, it consumes all available input. This behavior isuseful for sending Ant input via an OS pipe. Since Ant 1.7.

SecureInputHandler

This InputHandler calls System.console().readPassword(),available since Java 1.6. On earlier platforms it falls back to thebehavior of DefaultInputHandler. Since Ant 1.7.1.

InputRequest

Instances of org.apache.tools.ant.input.InputRequestencapsulate the information necessary to ask a user for input andvalidate this input.

The instances of InputRequest itself will accept anyinput, but subclasses may use stricter validations.org.apache.tools.ant.input.MultipleChoiceInputRequestshould be used if the user input must be part of a predefined set ofchoices.