Added a 'srcfile' attribute (PR 1681).

(But also found a NPE bug in the mapper stuff :( -- will try
to fix in a separate change.)
PR:
Obtained from:
Submitted by:
Reviewed by:


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272126 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/CoreTasks/uptodate.html

@@ -9,19 +9,24 @@
 
 <h2><a name="uptodate">Uptodate</a></h2>
 <h3>Description</h3>
-<p>Sets a property if a target files are more up to date than a set of
-Source files. Source files are specified by nested &lt;srcfiles&gt;
-elements, these are <a href="../CoreTypes/fileset.html">FileSet</a>s, while target
-files are specified using a nested <a href="../CoreTypes/mapper.html">mapper</a>
-element.</p>
-<p>The value part of the property being set is <i>true</i> if the
-timestamp of the target files is more recent than the timestamp of
-every corresponding source file.</p>
-<p>The default behavior is to use a <a href="../CoreTypes/mapper.html#merge-mapper">merge
-mapper</a> with the <code>to</code> attribute set to the value of the
-targetfile attribute.</p>
-<p>Normally, this task is used to set properties that are useful to avoid target
-execution depending on the relative age of the specified files.</p>
+<p>Sets a property if a target file or set of target files is more up-to-date
+than a source file or set of source files. A single source file is specified
+using the <code>srcfile</code> attribute. A set of source files is specified
+using the nested <code>&lt;srcfiles&gt;</code>
+elements. These are <a href="../CoreTypes/fileset.html">FileSet</a>s,
+whereas multiple target files are specified using a nested
+<a href="../CoreTypes/mapper.html"><code>&lt;mapper&gt;</code></a> element.</p>
+<p>By default, the value of the property is set to <code>true</code> if
+the timestamp of the target file(s) is more recent than the timestamp of
+the corresponding source file(s). You can set the value to something other
+than the default by specifying the <code>value</code> attribute.</p>
+<p>If a <code>&lt;srcfiles&gt;</code> element is used, without also specifying
+a <code>&lt;mapper&gt;</code> element, the default behavior is to use a
+<a href="../CoreTypes/mapper.html#merge-mapper">merge mapper</a>, with the
+<code>to</code> attribute set to the value of the
+<code>targetfile</code> attribute.</p>
+<p>Normally, this task is used to set properties that are useful to avoid
+target execution depending on the relative age of the specified files.</p>
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
@@ -31,36 +36,71 @@ execution depending on the relative age of the specified files.</p>
   </tr>
   <tr>
     <td valign="top">property</td>
-    <td valign="top">the name of the property to set.</td>
+    <td valign="top">The name of the property to set.</td>
     <td valign="top" align="center">Yes</td>
   </tr>
   <tr>
     <td valign="top">value</td>
-    <td valign="top">the value to set the property to. Defaults to &quot;true&quot;.</td>
-    <td valign="top" align="center">No</td>
+    <td valign="top">The value to set the property to.</td>
+    <td valign="top" align="center">No; defaults to <code>true</code>.</td>
+  </tr>
+  <tr>
+    <td valign="top">srcfile</td>
+    <td valign="top">The file to check against the target file.</td>
+    <td valign="top" align="center">Yes, unless a nested
+      <code>&lt;srcfiles&gt;</code> element is present.</td>
   </tr>
   <tr>
     <td valign="top">targetfile</td>
-    <td valign="top">the file for which we want to determine the status.</td>
-    <td valign="top" align="center">Yes, unless a nested mapper element is 
-      present.</td>
+    <td valign="top">The file for which we want to determine the status.</td>
+    <td valign="top" align="center">Yes, unless a nested
+      <code>&lt;mapper&gt;</code> element is present.</td>
   </tr>
 </table>
+
+<h3>Parameters specified as nested elements</h3>
+<h4><a name="srcfiles">srcfiles</a></h4>
+<p>The nested <code>&lt;srcfiles&gt;</code> element allows you to specify a
+set of files to check against the target file(s).</p>
+
+<p><strong>Note:</strong> You can specify either the <code>srcfile</code>
+attribute or nested <code>&lt;srcfiles&gt;</code> elements, but not both.
+
+<h4><a name="mapper">mapper</a></h4>
+<p>The nested <code>&lt;mapper&gt;</code> element allows you to specify
+a set of target files to check for being up-to-date with respect to a
+set of source files.</p>
+
+<p><strong>Note:</strong> The nested <code>&lt;mapper&gt;</code> element is
+only valid when used with the <code>&lt;srcfiles&gt;</code> element.
+
 <h3>Examples</h3>
 <pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot; targetfile=&quot;${deploy}\xmlClasses.jar&quot; &gt;
     &lt;srcfiles dir= &quot;${src}/xml&quot; includes=&quot;**/*.dtd&quot;/&gt;
   &lt;/uptodate&gt;</pre>
-<p>sets the property <code><i>xmlBuild.notRequired</i></code> to the value &quot;true&quot;
-if the <i>${deploy}/xmlClasses.jar</i> is more up to date than any of the DTD files in the <i>${src}/xml</i> directory.</p>
-<p>This can be written as</p>
-<pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot;  &gt;
+<p>sets the property <code>xmlBuild.notRequired</code> to <code>true</code>
+if the <code>${deploy}/xmlClasses.jar</code> file is more up-to-date than
+any of the DTD files in the <code>${src}/xml</code> directory.</p>
+<p>This can be written as:</p>
+<pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot;&gt;
     &lt;srcfiles dir= &quot;${src}/xml&quot; includes=&quot;**/*.dtd&quot;/&gt;
     &lt;mapper type=&quot;merge&quot; to=&quot;${deploy}\xmlClasses.jar&quot;/&gt;
   &lt;/uptodate&gt;</pre>
-<p>as well.</p>
+as well.
+</p>
+
+<pre>  &lt;uptodate property=&quot;isUpToDate&quot;
+            srcfile=&quot;/usr/local/bin/testit&quot;
+            targetfile=&quot;${build}/.flagfile&quot;/&gt;
+</pre>
+<p>sets the property <code>isUpToDate</code> to <code>true</code>
+if <code>/usr/local/bin/testit</code> is newer than
+<code>${build}/.flagfile</code>.</p>
+</p>
+
 <hr>
-<p align="center">Copyright &copy; 2001 Apache Software Foundation. All rights
-Reserved.</p>
+<p align="center">Copyright &copy; 2001,2002 Apache Software Foundation.
+All rights Reserved.</p>
 
 </body>
 </html>

src/main/org/apache/tools/ant/taskdefs/UpToDate.java

@@ -83,26 +83,27 @@ public class UpToDate extends MatchingTask implements Condition {
 
     private String _property;
     private String _value;
+    private File _sourceFile;
     private File _targetFile;
     private Vector sourceFileSets = new Vector();
 
     protected Mapper mapperElement = null;
 
     /**
-     * The property to set if the target file is more up to date than each of
-     * the source files.
+     * The property to set if the target file is more up-to-date than
+     * (each of) the source file(s).
      *
-     * @param property the name of the property to set if Target is up to date.
+     * @param property the name of the property to set if Target is up-to-date.
      */
     public void setProperty(String property) {
         _property = property;
     }
 
     /**
-     * The value to set the named property to if the target file is more up to
-     * date than each of the source files. Defaults to 'true'.
+     * The value to set the named property to if the target file is more
+     * up-to-date than (each of) the source file(s). Defaults to 'true'.
      *
-     * @param value the value to set the property to if Target is up to date
+     * @param value the value to set the property to if Target is up-to-date
      */
     public void setValue(String value) {
         _value = value;
@@ -116,15 +117,25 @@ public class UpToDate extends MatchingTask implements Condition {
     } 
 
     /**
-     * The file which must be more up to date than each of the source files
+     * The file which must be more up-to-date than (each of) the source file(s)
      * if the property is to be set.
      *
-     * @param file the file which we are checking against.
+     * @param file the file we are checking against.
      */
     public void setTargetFile(File file) {
         _targetFile = file;
     }
 
+    /**
+     * The file that must be older than the target file
+     * if the property is to be set.
+     *
+     * @param file the file we are checking against the target file.
+     */
+    public void setSrcfile(File file) {
+        _sourceFile = file;
+    }
+
     /**
      * Nested <srcfiles> element.
      */
@@ -145,47 +156,66 @@ public class UpToDate extends MatchingTask implements Condition {
     }
 
     /**
-     * Evaluate all target and source files, see if the targets are up-to-date.
+     * Evaluate (all) target and source file(s) to
+     * see if the target(s) is/are up-to-date.
      */
     public boolean eval() {
-        if (sourceFileSets.size() == 0) {
-          throw new BuildException("At least one <srcfiles> element must be set");
+        if (sourceFileSets.size() == 0 && _sourceFile == null) {
+          throw new BuildException("At least one srcfile or a nested <srcfiles> element must be set.");
+        }
+
+        if (sourceFileSets.size() > 0 && _sourceFile != null) {
+          throw new BuildException("Cannot specify both the srcfile attribute and a nested <srcfiles> element.");
         }
 
         if (_targetFile == null && mapperElement == null) {
-          throw new BuildException("The targetfile attribute or a nested mapper element must be set");
+          throw new BuildException("The targetfile attribute or a nested mapper element must be set.");
+        }
+
+        if (_sourceFile != null && mapperElement != null) {
+          throw new BuildException("Cannot specify both the srcfile attribute and a nested mapper element.");
         }
 
-        // if not there then it can't be up to date
+        // if the target file is not there, then it can't be up-to-date
         if (_targetFile != null && !_targetFile.exists()) {
           return false;
         } 
 
+        // if the source file isn't there, throw an exception
+        if (_sourceFile != null && !_sourceFile.exists()) {
+          throw new BuildException(_sourceFile.getAbsolutePath() + " not found.");
+        } 
+
         Enumeration enum = sourceFileSets.elements();
         boolean upToDate = true;
         while (upToDate && enum.hasMoreElements()) {
             FileSet fs = (FileSet) enum.nextElement();
             DirectoryScanner ds = fs.getDirectoryScanner(project);
-            upToDate = upToDate && scanDir(fs.getDir(project), 
-                                           ds.getIncludedFiles());
+                upToDate = upToDate && scanDir(fs.getDir(project), 
+                                               ds.getIncludedFiles());
+        }
+        if (_sourceFile != null) {
+            File srcfile = new File(_sourceFile.getAbsolutePath());
+            File tgtfile = new File(_targetFile.getAbsolutePath());
+            upToDate = (tgtfile.lastModified() > srcfile.lastModified());
         }
         return upToDate;
     }
 
 
     /**
-     * Sets property to true if target files have a more recent timestamp than
-     * each of the corresponding source files.
+     * Sets property to true if target file(s) have a more recent timestamp
+     * than (each of) the corresponding source file(s).
      */
     public void execute() throws BuildException {
         boolean upToDate = eval();
         if (upToDate) {
             this.project.setProperty(_property, this.getValue());
             if (mapperElement == null) {
-                log("File \"" + _targetFile.getAbsolutePath() + "\" is up to date.",
+                log("File \"" + _targetFile.getAbsolutePath() + "\" is up-to-date.",
                     Project.MSG_VERBOSE);
             } else {
-                log("All target files have been up to date.",
+                log("All target files are up-to-date.",
                     Project.MSG_VERBOSE);
             }
         }