bodewig 02/04/22 06:22:57 Modified: . WHATSNEW docs/manual developlist.html running.html docs/manual/CoreTasks input.html src/main/org/apache/tools/ant Main.java Added: docs/manual inputhandler.html Log: Add documentation for new input stuff. Revision Changes Path 1.257 +9 -1 jakarta-ant/WHATSNEW Index: WHATSNEW =================================================================== RCS file: /home/cvs/jakarta-ant/WHATSNEW,v retrieving revision 1.256 retrieving revision 1.257 diff -u -r1.256 -r1.257 --- WHATSNEW 18 Apr 2002 14:18:59 -0000 1.256 +++ WHATSNEW 22 Apr 2002 13:22:56 -0000 1.257 @@ -141,7 +141,7 @@ * New tasks and to pack and unpack files using the BZip2 alogrithm. -* New tasks , , , , , +* New tasks , , , , , , , , , , , . @@ -328,6 +328,14 @@ generated by tests will be sent to Ant's logging system as well as to the formatters (instead of sending it to the formatters exclusively). + +* Ant has now a pluggable way to prompt users for input, which is used + by the new task. IDE integrators can provide an + implementation of the InputHandler interface to decouple Ant's input + from the console. An implementation that gets its input from a file + for unattended builds is part of Ant's distribution. + + For more details see docs/manual/inputhandler.html. Changes from Ant 1.4 to Ant 1.4.1 =========================================== 1.2 +1 -0 jakarta-ant/docs/manual/developlist.html Index: developlist.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/manual/developlist.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- developlist.html 13 Dec 2001 17:16:26 -0000 1.1 +++ developlist.html 22 Apr 2002 13:22:56 -0000 1.2 @@ -15,6 +15,7 @@ Writing Your Own Task
Build Events
Source-code Integration
+InputHandler
1.12 +3 -0 jakarta-ant/docs/manual/running.html Index: running.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/manual/running.html,v retrieving revision 1.11 retrieving revision 1.12 diff -u -r1.11 -r1.12 --- running.html 4 Feb 2002 20:57:49 -0000 1.11 +++ running.html 22 Apr 2002 13:22:56 -0000 1.12 @@ -76,12 +76,15 @@ -D<property>=<value> use value for given property -propertyfile <name> load all properties from file with -D properties taking precedence + -inputhandler <class> the class which will handle input requests -find <file> search for buildfile towards the root of the filesystem and use it

For more information about -logger and -listener see the section Loggers & Listeners +

For more information about -inputhandler see the +section InputHandler

Examples

ant
1.1 jakarta-ant/docs/manual/inputhandler.html Index: inputhandler.html =================================================================== InputHandler

InputHandler

Overview

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 Ant in an IDE. Instead it asks an implementation of the org.apache.tools.ant.input.InputHandler interface to prompt the user and hand the user input back to the task.

To do this, the task creates an InputRequest object and passes it to the InputHandler Such an InputRequest may know whether a given user input is valid and the InputHandler is supposed to reject all invalid input.

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

InputHandler

The InputHandler interface contains exactly one method

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

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

Ant comes with two 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. This implementation will print the prompt encapsulated in the request object to Ant's logging system and re-prompt for input until the user enters something that is considered valid input by the request object. Input will be read from the console and the user will need to press the Return key.

PropertyFileInputHandler

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 ant.input.properties.

The prompt encapsulated in a request 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.

Note that ant.input.properties must be a Java system property, not an Ant property. I.e. you cannot define it as a simple parameter to ant, but you can define it inside the ANT_OPTS environment variable.

InputRequest

Instances of org.apache.tools.ant.input.InputRequest encapsulate the information necessary to ask a user for input and validate this input.

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


Copyright © 2002 Apache Software Foundation. All rights Reserved.

1.6 +43 -31 jakarta-ant/docs/manual/CoreTasks/input.html Index: input.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/manual/CoreTasks/input.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- input.html 3 Feb 2002 22:00:42 -0000 1.5 +++ input.html 22 Apr 2002 13:22:56 -0000 1.6 @@ -9,19 +9,23 @@

Input

Description

-

Allows user interaction during the build process by displaying a message and -reading a line of input from the console (System.in). The user will need to press -the Return key. -

-

The message displayed can be set via the message attribute -or as character data nested into the element.

-

Optinonally a set of valid imput arguments can be defined via the validargs -attribute. Input task will require the user to reenter values until the entered -value matches one of the predefined.

-

Optionally a property can be created from the value entered by the user. This -property can then be used during the following build run. Input behaves according -to property task which means that existing properties -cannot be overriden.

+ +

Allows user interaction during the build process by prompting for +input. To do so, it uses the configured +InputHandler.

+ +

The prompt can be set via the message attribute or as character +data nested into the element.

+ +

Optinonally a set of valid imput arguments can be defined via the +validargs attribute. Input task will no accept value that don't match +one of the predefined.

+ +

Optionally a property can be created from the value entered by the +user. This property can then be used during the following build +run. Input behaves according to property +task which means that existing properties cannot be overriden.

+

Parameters

@@ -31,37 +35,44 @@ - + - + - +
messagethe Message which gets displayed to the user during the build run.the Message which gets displayed to the user + during the build run. No
validargscomma separated String containing valid input arguments. If set, - input task will reject any input not defined here and input task will - require the user to reenter arguments until the entered one matches one of the - predefined. Validargs are compared case sensitive. If you want 'a' and 'A' to - be accepted you will need to define both arguments within validargs.comma separated String containing valid input + arguments. If set, input task will reject any input not defined + here. Validargs are compared case sensitive. If you want 'a' and + 'A' to be accepted you will need to define both arguments within + validargs. No
addpropertythe name of a property to be created from input. Behaviour is equal - to property task which means that existing properties - cannot be overriden.the name of a property to be created from + input. Behaviour is equal to property + task which means that existing properties cannot be + overriden. No

Examples

  <input/>
-

Will pause the build run until return key is pressed.

+

Will pause the build run until return key is pressed when using the +default +InputHandler, the concrete behavior is defined by the InputHandler +implementation you use.

  <input>Press Return key to continue...</input>
-

Will display the message "Press Return key to continue..." and pause -the build run until return key is pressed.

+

Will display the message "Press Return key to +continue..." and pause the build run until return key is pressed +(again, the concrete behavior is implementation dependent).

  <input
       message="Press Return key to continue..."
     />
-

Will display the message "Press Return key to continue..." and pause -the build run until return key is pressed.

+

Will display the message "Press Return key to +continue..." and pause the build run until return key is pressed +(see above).

     <input
       message="All data is going to be deleted from DB continue (y/n)?"
  @@ -73,9 +84,10 @@
     </condition>
     <fail if="do.abort">Build aborted by user.</fail>
   
-

Will display the message "All data is going to be deleted from DB continue -(y/n)?" and require 'y+retrun key' to continue build or 'n+return key' -to exit build with following message "Build aborted by user.".

+

Will display the message "All data is going to be deleted from +DB continue (y/n)?" and require 'y' to continue build or 'n' to +exit build with following message "Build aborted by +user.".

  <input
       message="Please enter db-username:"
       addproperty="db.user"
  @@ -84,7 +96,7 @@
   property db.user to the value entered by the user.


-

Copyright © 2001 Apache Software Foundation. All rights +

Copyright © 2001-2002 Apache Software Foundation. All rights Reserved.

1.64 +1 -0 jakarta-ant/src/main/org/apache/tools/ant/Main.java Index: Main.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/Main.java,v retrieving revision 1.63 retrieving revision 1.64 diff -u -r1.63 -r1.64 --- Main.java 22 Apr 2002 11:55:21 -0000 1.63 +++ Main.java 22 Apr 2002 13:22:57 -0000 1.64 @@ -740,6 +740,7 @@ msg.append(" -D= use value for given property" + lSep); msg.append(" -propertyfile load all properties from file with -D" + lSep); msg.append(" properties taking precedence" + lSep); + msg.append(" -inputhandler the class which will handle input requests" + lSep); msg.append(" -find search for buildfile towards the root of the" + lSep); msg.append(" filesystem and use it" + lSep); System.out.println(msg.toString()); -- To unsubscribe, e-mail: For additional commands, e-mail: