ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject cvs commit: jakarta-ant/src/main/org/apache/tools/ant Main.java
Date Mon, 22 Apr 2002 13:22:57 GMT
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 <bzip2> and <bunzip2> to pack and unpack files using the 
     BZip2 alogrithm.
   
  -* New tasks <replaceregexp>, <checksum>, <translate>, <waitfor>,
<input>,
  +* New tasks <replaceregexp>, <checksum>, <translate>, <waitfor>,

     <manifest>, <vsscp>, <vssadd>, <vsscreate>, <splash>, <basename>,
<dirname>,
     <concat>.
   
  @@ -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 <input> 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 @@
   <a href="develop.html#writingowntask">Writing Your Own Task</a><br>
   <a href="develop.html#buildevents">Build Events</a><br>
   <a href="develop.html#integration">Source-code Integration</a><br>
  +<a href="inputhandler.html">InputHandler</a><br>
   
   </body>
   </html>
  
  
  
  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&lt;property&gt;=&lt;value&gt;   use value for given property
     -propertyfile &lt;name&gt;   load all properties from file with -D
                            properties taking precedence
  +  -inputhandler &lt;class&gt;  the class which will handle input requests
     -find &lt;file&gt;           search for buildfile towards the root of the
                            filesystem and use it
   </pre>
   <p>For more information about <code>-logger</code> and
   <code>-listener</code> see the section <a
   href="listeners.html">Loggers &amp; Listeners</a>
  +<p>For more information about <code>-inputhandler</code> see the
  +section <a href="inputhandler.html">InputHandler</a>
   <h3>Examples</h3>
   <blockquote>
     <pre>ant</pre>
  
  
  
  1.1                  jakarta-ant/docs/manual/inputhandler.html
  
  Index: inputhandler.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <html>
  <head>
  <meta http-equiv="Content-Language" content="en-us">
  <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 Ant in an IDE.  Instead it asks an implementation of the
  <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>InputRequest</code> object
  and passes it to the <code>InputHandler</code> Such an
  <code>InputRequest</code> may know whether a given user input is valid
  and the <code>InputHandler</code> is supposed to reject all invalid
  input.</p>
  
  <p>Exactly one <code>InputHandler</code> instance is associated with
  every Ant process, users can specify the implementation using the
  <code>-inputhandler</code> command line switch.</p>
  
  <h2>InputHandler</h2>
  
  <p>The <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 two built-in implementations of this interface:</p>
  
  <h3><a name="defaulthandler">DefaultInputHandler</a></h3>
  
  <p>This is the implementation you get, when you don't use the
  <code>-inputhandler</code> 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 <code>ant</code>, but you can
  define it inside the <code>ANT_OPTS</code> environment variable.</p>
  
  <h2>InputRequest</h2>
  
  <p>Instances of <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>InputRequest</code> itself will accept any
  input, but subclasses may use stricter validations.
  <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>
  
  <hr>
  <p align="center">Copyright &copy; 2002 Apache Software Foundation. All rights
  Reserved.</p>
  </html>
  
  
  
  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 @@
   
   <h2><a name="input">Input</a></h2>
   <h3>Description</h3>
  -<p>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.
  -</p>
  -<p>The message displayed can be set via the message attribute
  -or as character data nested into the element.</p>
  -<p>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.</p>
  -<p>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 <a href="property.html">property task</a> which means that existing properties
  -cannot be overriden.</p>
  +
  +<p>Allows user interaction during the build process by prompting for
  +input.  To do so, it uses the configured 
  +<a href="../inputhandler.html">InputHandler</a>.</p>
  +
  +<p>The prompt can be set via the message attribute or as character
  +data nested into the element.</p>
  +
  +<p>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.</p>
  +
  +<p>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 <a href="property.html">property
  +task</a> which means that existing properties cannot be overriden.</p>
  +
   <h3>Parameters</h3>
   <table border="1" cellpadding="2" cellspacing="0">
     <tr>
  @@ -31,37 +35,44 @@
     </tr>
     <tr>
       <td valign="top">message</td>
  -    <td valign="top">the Message which gets displayed to the user during the build
run.</td>
  +    <td valign="top">the Message which gets displayed to the user
  +    during the build run.</td>
       <td valign="top" align="center">No</td>
     </tr>
     <tr>
       <td valign="top">validargs</td>
  -    <td valign="top">comma 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.</td>
  +    <td valign="top">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.</td>
       <td valign="top" align="center">No</td>
     </tr>
     <tr>
       <td valign="top">addproperty</td>
  -    <td valign="top">the name of a property to be created from input. Behaviour is
equal
  -	    to  <a href="property.html">property task</a> which means that existing
properties
  -  		cannot be overriden.</td>
  +    <td valign="top">the name of a property to be created from
  +    input. Behaviour is equal to <a href="property.html">property
  +    task</a> which means that existing properties cannot be
  +    overriden.</td>
       <td valign="top" align="center">No</td>
     </tr>
   </table>
   <h3>Examples</h3>
   <pre>  &lt;input/&gt;</pre>
  -<p>Will pause the build run until return key is pressed.</p>
  +<p>Will pause the build run until return key is pressed when using the
  +<a href="../inputhandler.html#defaulthandler">default
  +InputHandler</a>, the concrete behavior is defined by the InputHandler
  +implementation you use.</p>
   <pre>  &lt;input&gt;Press Return key to continue...&lt;/input&gt;</pre>
  -<p>Will display the message &quot;Press Return key to continue...&quot; and
pause
  -the build run until return key is pressed.</p>
  +<p>Will display the message &quot;Press Return key to
  +continue...&quot; and pause the build run until return key is pressed
  +(again, the concrete behavior is implementation dependent).</p>
   <pre>  &lt;input
       message=&quot;Press Return key to continue...&quot;
     /&gt;</pre>
  -<p>Will display the message &quot;Press Return key to continue...&quot; and
pause
  -the build run until return key is pressed.</p>
  +<p>Will display the message &quot;Press Return key to
  +continue...&quot; and pause the build run until return key is pressed
  +(see above).</p>
   <pre>
     &lt;input
       message=&quot;All data is going to be deleted from DB continue (y/n)?&quot;
  @@ -73,9 +84,10 @@
     &lt;/condition&gt;
     &lt;fail if=&quot;do.abort&quot;&gt;Build aborted by user.&lt;/fail&gt;
   </pre>
  -<p>Will display the message &quot;All data is going to be deleted from DB continue
  -(y/n)?&quot; and require 'y+retrun key' to continue build or 'n+return key'
  -to exit build with following message &quot;Build aborted by user.&quot;.</p>
  +<p>Will display the message &quot;All data is going to be deleted from
  +DB continue (y/n)?&quot; and require 'y' to continue build or 'n' to
  +exit build with following message &quot;Build aborted by
  +user.&quot;.</p>
   <pre>  &lt;input
       message=&quot;Please enter db-username:&quot;
       addproperty=&quot;db.user&quot;
  @@ -84,7 +96,7 @@
   property <code>db.user</code> to the value entered by the user.</p>
   
   <hr>
  -<p align="center">Copyright &copy; 2001 Apache Software Foundation. All rights
  +<p align="center">Copyright &copy; 2001-2002 Apache Software Foundation. All
rights
   Reserved.</p>
   </body>
   </html>
  
  
  
  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<property>=<value>   use value for given property"
+ lSep);
           msg.append("  -propertyfile <name>   load all properties from file with -D"
+ lSep);
           msg.append("                         properties taking precedence" + lSep);
  +        msg.append("  -inputhandler <class>  the class which will handle input requests"
+ lSep);
           msg.append("  -find <file>           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:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message