| 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 |
|
|---|
| 9 | http://www.apache.org/licenses/LICENSE-2.0
|
|---|
| 10 |
|
|---|
| 11 | Unless required by applicable law or agreed to in writing, software
|
|---|
| 12 | distributed under the License is distributed on an "AS IS" BASIS,
|
|---|
| 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|---|
| 14 | See the License for the specific language governing permissions and
|
|---|
| 15 | limitations under the License.
|
|---|
| 16 | -->
|
|---|
| 17 | <html>
|
|---|
| 18 |
|
|---|
| 19 | <head>
|
|---|
| 20 | <meta http-equiv="Content-Language" content="en-us">
|
|---|
| 21 | <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|---|
| 22 | <title>Input Task</title>
|
|---|
| 23 | </head>
|
|---|
| 24 |
|
|---|
| 25 | <body>
|
|---|
| 26 |
|
|---|
| 27 | <h2><a name="input">Input</a></h2>
|
|---|
| 28 | <h3>Description</h3>
|
|---|
| 29 |
|
|---|
| 30 | <p>Allows user interaction during the build process by prompting for
|
|---|
| 31 | input. To do so, it uses the configured
|
|---|
| 32 | <a href="../inputhandler.html">InputHandler</a>.</p>
|
|---|
| 33 |
|
|---|
| 34 | <p>The prompt can be set via the message attribute or as character
|
|---|
| 35 | data nested into the element.</p>
|
|---|
| 36 |
|
|---|
| 37 | <p>Optionally a set of valid input arguments can be defined via the
|
|---|
| 38 | validargs attribute. Input task will not accept a value that doesn't match
|
|---|
| 39 | one of the predefined.</p>
|
|---|
| 40 |
|
|---|
| 41 | <p>Optionally a property can be created from the value entered by the
|
|---|
| 42 | user. This property can then be used during the following build
|
|---|
| 43 | run. Input behaves according to <a href="property.html">property
|
|---|
| 44 | task</a> which means that existing properties cannot be overriden.
|
|---|
| 45 | Since Ant 1.6, <code><input></code> will not prompt for input if
|
|---|
| 46 | a property should be set by the task that has already been set in the
|
|---|
| 47 | project (and the task wouldn't have any effect).</p>
|
|---|
| 48 |
|
|---|
| 49 | <p>A regular complaint about this task is that it echoes characters to the
|
|---|
| 50 | console, this is a critical security defect, we must fix it immediately, etc, etc.
|
|---|
| 51 | We know it leaves something to be desired, but the problem is Java, not Ant.
|
|---|
| 52 | There is nothing we can do to stop the console echoing. </p>
|
|---|
| 53 |
|
|---|
| 54 | <p>
|
|---|
| 55 | IDE behaviour depends upon the IDE: some hang waiting for input, some let you
|
|---|
| 56 | type it in. For this situation, place the password in a (secured) property
|
|---|
| 57 | file and load in before the input task.</p>
|
|---|
| 58 |
|
|---|
| 59 | <h3>Parameters</h3>
|
|---|
| 60 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 61 | <tr>
|
|---|
| 62 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 63 | <td valign="top"><b>Description</b></td>
|
|---|
| 64 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 65 | </tr>
|
|---|
| 66 | <tr>
|
|---|
| 67 | <td valign="top">message</td>
|
|---|
| 68 | <td valign="top">the Message which gets displayed to the user
|
|---|
| 69 | during the build run.</td>
|
|---|
| 70 | <td valign="top" align="center">No</td>
|
|---|
| 71 | </tr>
|
|---|
| 72 | <tr>
|
|---|
| 73 | <td valign="top">validargs</td>
|
|---|
| 74 | <td valign="top">comma separated String containing valid input
|
|---|
| 75 | arguments. If set, input task will reject any input not defined
|
|---|
| 76 | here. Validargs are compared case sensitive. If you want 'a' and
|
|---|
| 77 | 'A' to be accepted you will need to define both arguments within
|
|---|
| 78 | validargs.</td>
|
|---|
| 79 | <td valign="top" align="center">No</td>
|
|---|
| 80 | </tr>
|
|---|
| 81 | <tr>
|
|---|
| 82 | <td valign="top">addproperty</td>
|
|---|
| 83 | <td valign="top">the name of a property to be created from
|
|---|
| 84 | input. Behaviour is equal to <a href="property.html">property
|
|---|
| 85 | task</a> which means that existing properties cannot be
|
|---|
| 86 | overridden.</td>
|
|---|
| 87 | <td valign="top" align="center">No</td>
|
|---|
| 88 | </tr>
|
|---|
| 89 | <tr>
|
|---|
| 90 | <td valign="top">defaultvalue</td>
|
|---|
| 91 | <td valign="top">Defines the default value of the property to be
|
|---|
| 92 | created from input. Property value will be set to default if no
|
|---|
| 93 | input is received.</td>
|
|---|
| 94 | <td valign="top" align="center">No</td>
|
|---|
| 95 | </tr>
|
|---|
| 96 | </table>
|
|---|
| 97 | <h3>Parameters Specified as Nested Elements</h3>
|
|---|
| 98 | <h4>Handler</h4>
|
|---|
| 99 | <p>Since <b>Ant 1.7</b>, a nested <handler> element can be used to
|
|---|
| 100 | specify an InputHandler, so that different InputHandlers may be used
|
|---|
| 101 | among different Input tasks.
|
|---|
| 102 |
|
|---|
| 103 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 104 | <tr>
|
|---|
| 105 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 106 | <td valign="top"><b>Description</b></td>
|
|---|
| 107 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 108 | </tr>
|
|---|
| 109 | <tr>
|
|---|
| 110 | <td valign="top">type</td>
|
|---|
| 111 | <td valign="top">one of "default","propertyfile", or "greedy".
|
|---|
| 112 | </td>
|
|---|
| 113 | <td align="center" valign="top" rowspan="3">One of these</td>
|
|---|
| 114 | </tr>
|
|---|
| 115 | <tr>
|
|---|
| 116 | <td valign="top">refid</td>
|
|---|
| 117 | <td valign="top">Reference to an <code>InputHandler</code>
|
|---|
| 118 | defined elsewhere in the project.
|
|---|
| 119 | </td>
|
|---|
| 120 | </tr>
|
|---|
| 121 | <tr>
|
|---|
| 122 | <td valign="top">classname</td>
|
|---|
| 123 | <td valign="top">The name of an <code>InputHandler</code> subclass.</td>
|
|---|
| 124 | </tr>
|
|---|
| 125 | <tr>
|
|---|
| 126 | <td valign="top">classpath</td>
|
|---|
| 127 | <td valign="top">The classpath to use with <i>classname</i>.</td>
|
|---|
| 128 | <td valign="top">No</td>
|
|---|
| 129 | </tr>
|
|---|
| 130 | <tr>
|
|---|
| 131 | <td valign="top">classpathref</td>
|
|---|
| 132 | <td valign="top">The refid of a classpath to use with <i>classname</i>.</td>
|
|---|
| 133 | <td valign="top">No</td>
|
|---|
| 134 | </tr>
|
|---|
| 135 | <tr>
|
|---|
| 136 | <td valign="top">loaderref</td>
|
|---|
| 137 | <td valign="top">The refid of a classloader to use with <i>classname</i>.
|
|---|
| 138 | </td>
|
|---|
| 139 | <td valign="top">No</td>
|
|---|
| 140 | </tr>
|
|---|
| 141 | </table>
|
|---|
| 142 | <br />
|
|---|
| 143 | The classpath can also be specified by means of one or more nested
|
|---|
| 144 | <classpath> elements.</p>
|
|---|
| 145 |
|
|---|
| 146 | <h3>Examples</h3>
|
|---|
| 147 | <pre> <input/></pre>
|
|---|
| 148 | <p>Will pause the build run until return key is pressed when using the
|
|---|
| 149 | <a href="../inputhandler.html#defaulthandler">default
|
|---|
| 150 | InputHandler</a>, the concrete behavior is defined by the InputHandler
|
|---|
| 151 | implementation you use.</p>
|
|---|
| 152 | <pre> <input>Press Return key to continue...</input></pre>
|
|---|
| 153 | <p>Will display the message "Press Return key to
|
|---|
| 154 | continue..." and pause the build run until return key is pressed
|
|---|
| 155 | (again, the concrete behavior is implementation dependent).</p>
|
|---|
| 156 | <pre> <input
|
|---|
| 157 | message="Press Return key to continue..."
|
|---|
| 158 | /></pre>
|
|---|
| 159 | <p>Will display the message "Press Return key to
|
|---|
| 160 | continue..." and pause the build run until return key is pressed
|
|---|
| 161 | (see above).</p>
|
|---|
| 162 | <pre>
|
|---|
| 163 | <input
|
|---|
| 164 | message="All data is going to be deleted from DB continue (y/n)?"
|
|---|
| 165 | validargs="y,n"
|
|---|
| 166 | addproperty="do.delete"
|
|---|
| 167 | />
|
|---|
| 168 | <condition property="do.abort">
|
|---|
| 169 | <equals arg1="n" arg2="${do.delete}"/>
|
|---|
| 170 | </condition>
|
|---|
| 171 | <fail if="do.abort">Build aborted by user.</fail>
|
|---|
| 172 | </pre>
|
|---|
| 173 | <p>Will display the message "All data is going to be deleted from
|
|---|
| 174 | DB continue (y/n)?" and require 'y' to continue build or 'n' to
|
|---|
| 175 | exit build with following message "Build aborted by
|
|---|
| 176 | user.".</p>
|
|---|
| 177 | <pre> <input
|
|---|
| 178 | message="Please enter db-username:"
|
|---|
| 179 | addproperty="db.user"
|
|---|
| 180 | /></pre>
|
|---|
| 181 | <p>Will display the message "Please enter db-username:" and set the
|
|---|
| 182 | property <code>db.user</code> to the value entered by the user.</p>
|
|---|
| 183 |
|
|---|
| 184 | <pre> <input
|
|---|
| 185 | message="Please enter db-username:"
|
|---|
| 186 | addproperty="db.user"
|
|---|
| 187 | defaultvalue="Scott-Tiger"
|
|---|
| 188 | /></pre>
|
|---|
| 189 | <p>Same as above, but will set <code>db.user</code> to the value
|
|---|
| 190 | <i>Scott- Tiger</i> if the user enters no value (simply types
|
|---|
| 191 | <return>).</p>
|
|---|
| 192 |
|
|---|
| 193 |
|
|---|
| 194 | </body>
|
|---|
| 195 | </html>
|
|---|
