ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Rees <d.ree...@usa.net>
Subject [SUBMIT] file set cullers
Date Sat, 24 Mar 2001 04:39:40 GMT
Attached is my second cut at the culler functionality I mentioned
last week. It doesn't include HTML docs yet because I think text will
be easier to discuss. If you agree to the submission I can submit the
docs pretty quickly.

As before, my thoughts for how this "should" be done in Ant2 will be
in different post (later).

dave


*** Usage

Cullers provide finer-grained control over the files selected in a
fileset. Specific culler types support selecting files based on their
attributes or perhaps contents. Cullers are added sub-elements of
FileSet.

An example says it best, the following selects all files that end in
".txt" and are read only.


<copy toDir="\tmp\toDir">
  <fileset dir="\tmp\fromDir">
    <include name="*.txt" />
    <FileAttributeCuller canWrite="no" />
  </fileset>
</copy>


*** Culler Types

Note that it easy to add additional cullers. See "developing cullers"
for more information.

** FileAttributeCuller

Supports selecting files based on their attributes. The default for
all attributes is to ignore that attribute so a blank
FileAttributeCuller will select all files.

* Basic Attributes:
Each attribute corresponds to the similar method on the Java File
class.
canRead
  true/yes, false/no, *ignore
canWrite
  true/yes, false/no, *ignore
exists
  true/yes, false/no, *ignore
fileDir
  file, dir, *ignore

* Date Attributes:
For date attributes any String that can be read by Java Date or
"ignore" is supported. This includes minutes, seconds and
milliseconds.
dateEquals
  Selects file if its date is the same to the millisecond as the
indicated date
dateNotEquals
  Selects file if its date is the different (to the millisecond) from
the indicated date
dateAfter
  Selects file if its date is after the indicated date
dateBefore
  Selects file if its date is before the indicated date

* Length Attributes
For length attributes, any long that can be read by Java Long or
"ignore" is supported. The length is in bytes.
lengthEqual
  Selects file if its length equals the indicated length.
lengthNotEqual
  Selects file if its length does not equal the indicated length.
lengthLessThan
  Selects file if its length is less than the indicated length.
lengthGreaterThan
  Selects file if its length is greater than the indicated length.

* Examples

Select only files:
<fileset dir="${from.dir}" >
  <fileattributeculler fileDir="file" />
</fileset>

Select files created since the start of the millennium:
<fileset dir="\tmp\fromDir">
  <include name="*.txt" />
  <FileAttributeCuller dateAfter="1/1/2001" />
</fileset>

Select non-empty files:
<fileset dir="\tmp\fromDir">
  <include name="*.txt" />
  <FileAttributeCuller lengthNotEqual="0" />
</fileset>


** FileCompareCuller

Supports selecting files relative to another directory. The same set
of attributes as FileAttributeCuller are supported except that they
are applied to the file in the same relative position in compare
directory. In addition, the value "culee" can be used for date/length
attributes to compare the file to the file being selected.

* Examples

Copies only those files that do not exist in the toDir:
<copy toDir="${to.dir}">
  <fileset dir="${from.dir}">
    <filecompareculler compareDir="${to.dir}" exists="no" />
  </fileset>
</copy>

Makes a clone of the fromDir in the toDir. It first deletes those
files that do no exist in the fromDir. Then copies only those files
that don't exist or have changed.

<mkdir dir="${to.dir}" />
<delete>
  <fileset dir="${to.dir}">
    <filecompareculler compareDir="${from.dir}" exists="no" />
  </fileset>
</delete>
<copy toDir="${to.dir}">
  <fileset dir="${from.dir}">
    <cullerset logic="or">
      <filecompareculler compareDir="${to.dir}" exists="no" />
      <filecompareculler
        compareDir="${to.dir}"
        dateNotEqual="cullee" />
    </cullerset>
  </fileset>
</copy>


** CullerSet

A collection of Cullers that is also a Culler itself (they can be
nested). CullerSet supports simple logic for how to combine the
results of its contained cullers. Cullers are tested in the order they
are listed. Short circuiting is used so some cullers may not be called
for a given file (e.g. with "and" logic the first false nested culler
will result in the CullerSet returning false immediately).


* Attributes
logic
  or*, and, xor
  Used to indicate what logic is used to combine my nested cullers.
not
  true/yes, false/no*
  If "true/yes" the CullerSet's value is reversed.

* Examples

Selects all directories and only writable files:
<cullerset logic="or" >
  <fileattributeculler fileDir="dir" />
  <fileattributeculler fileDir="file" canWrite="yes" />
</cullerset>



** Caveats

Unlike patterns, cullers do not effect what directories are scanned,
they only effect what directories are included. This is by design
since the reverse makes them much less useful. Patterns still do
effect what directories are scanned and are applied before a cullers
are applied.

For some sources it is possible that certain cullers (e.g. files for a
FTP culler) may not be valid. In these cases an error is raised.

For developers that use the DirectoryScanner class directly, cullers
do not effect the filesExcluded and dirsExcluded values. A file is
either included or notIncluded.


** Developing Cullers

Additional FileCullers can be added easily by creating a class that
implements the Culler API of shouldCull(). In addition, an
add<YourCullerName> method must be added to FileSet and CullerSet to
allow the culler to be included. The shouldCull() method receives a
CullerSource and a path string relative to the source. A CullerSource
supports getting a File or InputStream object for a given path and is
intended to allow easy addition of new types of sources (FTP, Web,
etc.).

** Possible Plans

Create ContainsFileCuller which will select files based on their
contents using a RegExp.

Create a ByteCompareCuller that compares actual contents.

Better support for FTP/Zip sources (from and to).

Integrate Mappers for the compare options.






Mime
View raw message