From 150545be2fb2f82b5fe56dbe108049a1501c03e6 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Mon, 22 Apr 2002 13:22:57 +0000 Subject: [PATCH] Add documentation for new input stuff. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272545 13f79535-47bb-0310-9956-ffa450edef68 --- WHATSNEW | 10 ++- docs/manual/CoreTasks/input.html | 74 +++++++++++--------- docs/manual/developlist.html | 1 + docs/manual/inputhandler.html | 89 +++++++++++++++++++++++++ docs/manual/running.html | 3 + src/main/org/apache/tools/ant/Main.java | 1 + 6 files changed, 146 insertions(+), 32 deletions(-) create mode 100644 docs/manual/inputhandler.html diff --git a/WHATSNEW b/WHATSNEW index 7875e2f08..0c25ab4dc 100644 --- a/WHATSNEW +++ b/WHATSNEW @@ -141,7 +141,7 @@ Other changes: * New tasks and to pack and unpack files using the BZip2 alogrithm. -* New tasks , , , , , +* New tasks , , , , , , , , , , , . @@ -329,6 +329,14 @@ Other changes: 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 =========================================== diff --git a/docs/manual/CoreTasks/input.html b/docs/manual/CoreTasks/input.html index f70d6dcbd..674b8acd9 100644 --- a/docs/manual/CoreTasks/input.html +++ b/docs/manual/CoreTasks/input.html @@ -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 @@ cannot be overriden.

- + - + - +
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 @@ the build run until return key is pressed.

   </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 @@ to exit build with following message "Build aborted by user.".

 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.

 
 
\ No newline at end of file
diff --git a/docs/manual/developlist.html b/docs/manual/developlist.html
index 82efc7795..928d5d34f 100644
--- a/docs/manual/developlist.html
+++ b/docs/manual/developlist.html
@@ -15,6 +15,7 @@
 Writing Your Own Task

 Build Events

 Source-code Integration

+InputHandler

 
 
 
diff --git a/docs/manual/inputhandler.html b/docs/manual/inputhandler.html
new file mode 100644
index 000000000..b73eb42c1
--- /dev/null
+++ b/docs/manual/inputhandler.html
@@ -0,0 +1,89 @@
+
+
+
+
+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.

+
diff --git a/docs/manual/running.html b/docs/manual/running.html
index f4a785c0d..5b9bb9960 100644
--- a/docs/manual/running.html
+++ b/docs/manual/running.html
@@ -76,12 +76,15 @@ Options:
   -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
diff --git a/src/main/org/apache/tools/ant/Main.java b/src/main/org/apache/tools/ant/Main.java index 427bb1690..abdadf5d1 100644 --- a/src/main/org/apache/tools/ant/Main.java +++ b/src/main/org/apache/tools/ant/Main.java @@ -740,6 +740,7 @@ public class Main { 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());