103 lines
4.7 KiB
HTML
103 lines
4.7 KiB
HTML
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
|
|
<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 Apache Ant in an IDE. Instead it asks an implementation
|
|
of the <code class="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 class="code">InputRequest</code> object and passes it to
|
|
the <code class="code">InputHandler</code>. Such an <code class="code">InputRequest</code> may know
|
|
whether a given user input is valid and the <code class="code">InputHandler</code> is supposed to
|
|
reject all invalid input.</p>
|
|
|
|
<p>Exactly one <code class="code">InputHandler</code> instance is associated with every Ant process,
|
|
users can specify the implementation using the <kbd>-inputhandler</kbd> command line switch.</p>
|
|
|
|
<h2>InputHandler</h2>
|
|
|
|
<p>The <code class="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 three built-in implementations of this interface:</p>
|
|
|
|
<h3 id="defaulthandler">DefaultInputHandler</h3>
|
|
|
|
<p>This is the implementation you get, when you don't use the <kbd>-inputhandler</kbd> 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 <kbd>ant</kbd>, but you can
|
|
define it inside the <code>ANT_OPTS</code> environment variable.</p>
|
|
|
|
<h3>GreedyInputHandler</h3>
|
|
<p><em>Since Ant 1.7</em></p>
|
|
<p>Like the default implementation, this InputHandler reads from standard input. However, it
|
|
consumes <em>all</em> available input. This behavior is useful for sending Ant input via an OS
|
|
pipe.</p>
|
|
|
|
<h3>SecureInputHandler</h3>
|
|
<p><em>Since Ant 1.7.1</em></p>
|
|
<p>This InputHandler calls <code class="code">System.console().readPassword()</code>, available
|
|
since Java 6. On earlier platforms it falls back to the behavior
|
|
of <code class="code">DefaultInputHandler</code>.</p>
|
|
|
|
<h2>InputRequest</h2>
|
|
|
|
<p>Instances of <code class="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 class="code">InputRequest</code> itself will accept any input, but
|
|
subclasses may use stricter
|
|
validations. <code class="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>
|
|
|
|
</body>
|
|
</html>
|