You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

inputhandler.html 4.7 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="stylesheets/style.css">
  19. <title>InputHandler</title>
  20. </head>
  21. <body>
  22. <h1>InputHandler</h1>
  23. <h2>Overview</h2>
  24. <p>When a task wants to prompt a user for input, it doesn't simply read the input from the console
  25. as this would make it impossible to embed Apache Ant in an IDE. Instead it asks an implementation
  26. of the <code class="code">org.apache.tools.ant.input.InputHandler</code> interface to prompt the
  27. user and hand the user input back to the task.</p>
  28. <p>To do this, the task creates an <code class="code">InputRequest</code> object and passes it to
  29. the <code class="code">InputHandler</code>. Such an <code class="code">InputRequest</code> may know
  30. whether a given user input is valid and the <code class="code">InputHandler</code> is supposed to
  31. reject all invalid input.</p>
  32. <p>Exactly one <code class="code">InputHandler</code> instance is associated with every Ant process,
  33. users can specify the implementation using the <kbd>-inputhandler</kbd> command line switch.</p>
  34. <h2>InputHandler</h2>
  35. <p>The <code class="code">InputHandler</code> interface contains exactly one method</p>
  36. <pre>
  37. void handleInput(InputRequest request)
  38. throws org.apache.tools.ant.BuildException;</pre>
  39. <p>with some pre- and postconditions. The main postcondition is that this method must not return
  40. unless the <code>request</code> considers the user input valid; it is allowed to throw an exception
  41. in this situation.</p>
  42. <p>Ant comes with three built-in implementations of this interface:</p>
  43. <h3 id="defaulthandler">DefaultInputHandler</h3>
  44. <p>This is the implementation you get, when you don't use the <kbd>-inputhandler</kbd> command line
  45. switch at all. This implementation will print the prompt encapsulated in the <code>request</code>
  46. object to Ant's logging system and re-prompt for input until the user enters something that is
  47. considered valid input by the <code>request</code> object. Input will be read from the console and
  48. the user will need to press the Return key.</p>
  49. <h3>PropertyFileInputHandler</h3>
  50. <p>This implementation is useful if you want to run unattended build processes. It reads all input
  51. from a properties file and makes the build fail if it cannot find valid input in this file. The
  52. name of the properties file must be specified in the Java system
  53. property <code>ant.input.properties</code>.</p>
  54. <p>The prompt encapsulated in a <code>request</code> will be used as the key when looking up the
  55. input inside the properties file. If no input can be found, the input is considered invalid and an
  56. exception will be thrown.</p>
  57. <p><strong>Note</strong> that <code>ant.input.properties</code> must be a Java system property, not
  58. an Ant property. I.e. you cannot define it as a simple parameter to <kbd>ant</kbd>, but you can
  59. define it inside the <code>ANT_OPTS</code> environment variable.</p>
  60. <h3>GreedyInputHandler</h3>
  61. <p><em>Since Ant 1.7</em></p>
  62. <p>Like the default implementation, this InputHandler reads from standard input. However, it
  63. consumes <em>all</em> available input. This behavior is useful for sending Ant input via an OS
  64. pipe.</p>
  65. <h3>SecureInputHandler</h3>
  66. <p><em>Since Ant 1.7.1</em></p>
  67. <p>This InputHandler calls <code class="code">System.console().readPassword()</code>, available
  68. since Java 6. On earlier platforms it falls back to the behavior
  69. of <code class="code">DefaultInputHandler</code>.</p>
  70. <h2>InputRequest</h2>
  71. <p>Instances of <code class="code">org.apache.tools.ant.input.InputRequest</code> encapsulate the
  72. information necessary to ask a user for input and validate this input.</p>
  73. <p>The instances of <code class="code">InputRequest</code> itself will accept any input, but
  74. subclasses may use stricter
  75. validations. <code class="code">org.apache.tools.ant.input.MultipleChoiceInputRequest</code> should
  76. be used if the user input must be part of a predefined set of choices.</p>
  77. </body>
  78. </html>