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