Cullers and How they Work

Cullers are a mechanism whereby the files that make up a fileset can be excluded based on criteria other than filename as provided by the <exclude> tag.

How to use a Culler

A culler is an element of PatternSet, and appears within it. FileSets contain a default PatternSet, so they can support cullers directly.

Different cullers have different attributes. All cullers share one common feature, though: they all support the attribute of inverted="true". When this is set on a culler, it reverses all of its selections, so that files which would have been culled are not, and files which would not have been culled are.

Here is a list of the cullers implemented so far.

Size Culler

The <sizecull> tag in a PatternSet will put a limit on the files specified by the include tag, so that tags which do not meet the size limits specified by the culler will not end up being selected.

Attribute	Description	Required
size	The size of the file which should be tested for.	Yes
units	The units that the size is expressed in. When using the standard single letter SI designations, such as "k","M", or "G", multiples of 1000 are used. If you want to use power of 2 units, use the IEC standard: "Ki" for 1024, "Mi" for 1048576, and so on. The default is no units, which means the size attributes expresses the exact number of bytes.	No
when	Indicates how to interpret the size, whether the files to be culled should be larger, smaller, or equal to that value. Acceptable values for this attribute are: less - cull files less than the indicated size more - cull files greater than the indicated size equal - cull files this exact size The default is less.	No
inverted	Reverses the sense of the culler.	No

Here are some examples of how to use the Size Culler:

<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
    <sizecull size="4" units="Ki" when="less"/>
  </patternset>
</fileset>

Selects all JAR files that are 4096 bytes or larger by culling out those that are smaller.

<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
    <sizecull size="4" units="Ki" when="more" inverted="true"/>
  </patternset>
</fileset>

Selects all JAR files that are larger than 4096 bytes by culling out those that are the same size or smaller. It does this by inverting the culling of files larger than 4096 bytes. This means that, unlike the previous example, files that are exactly 4096 bytes will not be selected.

Date Culler

The <datecull> tag in a PatternSet will put a limit on the files specified by the include tag, so that tags whose last modified date does not meet the date limits specified by the culler will not end up being selected.

Attribute	Description	Required
datetime	Specifies the date and time to test for using a string of the format MM/DD/YYYY HH:MM AM_or_PM.	At least one of the two.
millis	The number of milliseconds since 1970 that should be tested for. It is usually much easier to use the datetime attribute. If neither datetime nor millis is specified, then the current date and time is used.	At least one of the two.
when	Indicates how to interpret the date, whether the files to be culled are those whose last modified times should be before, after, or equal to the specified value. Acceptable values for this attribute are: before - cull files whose last modified date is before the indicated date after - cull files whose last modified date is after the indicated date equal - cull files whose last modified date is this exact date The default is before.	No
inverted	Reverses the sense of the culler.	No

Here is an example of how to use the Date Culler:

<fileset dir="${jar.path}" includes="**/*.jar">
    <datecull datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

Selects all JAR files which were last modified at or after midnight January 1, 2001 by culling those that were modified before.

The cullers are coming!

Since this is just a demonstration right now, there are only two cullers to look at. However, I hope to have many more within a few weeks. These include:

Regular Expression culler: allows you to only include files that either do or don't (remember inverted="true") contain lines that match a regular expression.
Dependency culler: Cull (or keep) files that are newer than ones in another directory tree. This culler would support an optional mapper attribute to specify how to match dependent files, and also allow a "granularity" attribute so that the exactness of the match could be specified.
Directory/File culler: cull all directories or all files. This would allow you to duplicate a directory tree without any files in it, for example.
Existence culler: This compares between directory trees, just like the dependency culler. However, it culls based on the existence of a file in one tree and not the other.
Head culler: This culler contains another as an element, and will operate the culler on only the first few lines of a file. Clearly, this is only useful with a culler that operates on the contents of a file, like the Regular Expression culler.
Extend culler: This culler forwards requests on to other cullers which are specified dynamically, either by defining their class name in a properties file or within a "cullerdef" element. The <extendcull> element defines some standard attributes, as well as several generic "att1", "att2", etc. It loads a specified class and forwards set requests to it, as well as all other calls to a culler.

Programming API

Want to define your own cullers? It's easy!

First, create a class that extends org.apache.tools.ant.types.cullers.Culler.
Create a dummy constructor. You can put whatever you want into it.
Create a method with the signature public String checkForError(). It should do the checking to make sure all fields have valid data. The method returns null if there are no errors, and an error message if there are any. An error message will result in a BuildException being thrown with that error.
Create a second method that has the signature public boolean isCulled(String filename, File file) and returns true or false depending on whether the given file should be culled from the list or not.
If you want this to be an official Ant culler, you must add a create method to PatternSet and FileSet. Use the methods that are already there as examples.
If you want to use your culler with the Extend culler, you can either add it to the culler.properties file, or specify the class name in the cullerdef element. (All once the extend culler is written, of course).

And that's it. You too can cull for fun and profit.