Save This Page
Home » apache-ant-1.8.1 » org.apache.tools » ant » types » selectors » modifiedselector » [javadoc | source]
org.apache.tools.ant.types.selectors.modifiedselector
public class: ModifiedSelector [javadoc | source]
java.lang.Object
   org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.types.DataType
         org.apache.tools.ant.types.selectors.BaseSelector
            org.apache.tools.ant.types.selectors.BaseExtendSelector
               org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector

All Implemented Interfaces:
    ResourceSelector, BuildListener, ExtendFileSelector, FileSelector, Cloneable

Selector class that uses Algorithm, Cache and Comparator for its work. The Algorithm is used for computing a hashvalue for a file. The Comparator decides whether to select or not. The Cache stores the other value for comparison by the Comparator in a persistent manner.

The ModifiedSelector is implemented as a CoreSelector and uses default values for all its attributes therefore the simpliest example is

  <copy todir="dest">
      <filelist dir="src">
          <modified/>
      </filelist>
  </copy>

The same example rewritten as CoreSelector with setting the all values (same as defaults are) would be

  <copy todir="dest">
      <filelist dir="src">
          <modified update="true"
                    cache="propertyfile"
                    algorithm="digest"
                    comparator="equal">
              <param name="cache.cachefile"     value="cache.properties"/>
              <param name="algorithm.algorithm" value="MD5"/>
          </modified>
      </filelist>
  </copy>

And the same rewritten as CustomSelector would be

  <copy todir="dest">
      <filelist dir="src">
          <custom class="org.apache.tools.ant.type.selectors.ModifiedSelector">
              <param name="update"     value="true"/>
              <param name="cache"      value="propertyfile"/>
              <param name="algorithm"  value="digest"/>
              <param name="comparator" value="equal"/>
              <param name="cache.cachefile"     value="cache.properties"/>
              <param name="algorithm.algorithm" value="MD5"/>
          </custom>
      </filelist>
  </copy>

If you want to provide your own interface implementation you can do that via the *classname attributes. If the classes are not on Ant's core classpath, you will have to provide the path via nested <classpath> element, so that the selector can find the classes.

  <modified cacheclassname="com.mycompany.MyCache">
      <classpath>
          <pathelement location="lib/mycompony-antutil.jar"/>
      </classpath>
  </modified>

All these three examples copy the files from src to dest using the ModifiedSelector. The ModifiedSelector uses the PropertyfileCache , the DigestAlgorithm and the EqualComparator for its work. The PropertyfileCache stores key-value-pairs in a simple java properties file. The filename is cache.properties. The update flag lets the selector update the values in the cache (and on first call creates the cache). The DigestAlgorithm computes a hashvalue using the java.security.MessageDigest class with its MD5-Algorithm and its standard provider. The new computed hashvalue and the stored one are compared by the EqualComparator which returns 'true' (more correct a value not equals zero (1)) if the values are not the same using simple String comparison.

A useful scenario for this selector is inside a build environment for homepage generation (e.g. with Apache Forrest).

<target name="generate-and-upload-site">
    <echo> generate the site using forrest </echo>
    <antcall target="site"/>

    <echo> upload the changed files </echo>
    <ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.pwd}">
        <fileset dir="htdocs/manual">
            <modified/>
        </fileset>
    </ftp>
</target>
Here all changed files are uploaded to the server. The ModifiedSelector saves therefore much upload time.

This selector uses reflection for setting the values of its three interfaces (using org.apache.tools.ant.IntrospectionHelper) therefore no special 'configuration interfaces' has to be implemented by new caches, algorithms or comparators. All present setXX methods can be used. E.g. the DigestAlgorithm can use a specified provider for computing its value. For selecting this there is a setProvider(String providername) method. So you can use a nested <param name="algorithm.provider" value="MyProvider"/>.

Nested Class Summary:
public static class  ModifiedSelector.CacheName  The enumerated type for cache. The values are "propertyfile". 
public static class  ModifiedSelector.AlgorithmName  The enumerated type for algorithm. The values are "hashValue", "digest" and "checksum". 
public static class  ModifiedSelector.ComparatorName  The enumerated type for algorithm. The values are "equal" and "rule". 
Fields inherited from org.apache.tools.ant.types.selectors.BaseExtendSelector:
parameters
Fields inherited from org.apache.tools.ant.types.DataType:
ref,  checked
Fields inherited from org.apache.tools.ant.ProjectComponent:
project,  location,  description
Constructor:
 public ModifiedSelector() 
Method from org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector Summary:
addClasspath,   addParam,   addParam,   buildFinished,   buildStarted,   configure,   getAlgorithm,   getCache,   getClassLoader,   getComparator,   getDelayUpdate,   getModified,   isSelected,   isSelected,   loadClass,   messageLogged,   saveCache,   setAlgorithm,   setAlgorithmClass,   setCache,   setCacheClass,   setClassLoader,   setComparator,   setComparatorClass,   setDelayUpdate,   setModified,   setParameters,   setSeldirs,   setSelres,   setUpdate,   targetFinished,   targetStarted,   taskFinished,   taskStarted,   toString,   tryToSetAParameter,   useParameter,   verifySettings
Methods from org.apache.tools.ant.types.selectors.BaseExtendSelector:
getParameters,   isSelected,   setParameters
Methods from org.apache.tools.ant.types.selectors.BaseSelector:
getError,   isSelected,   setError,   validate,   verifySettings
Methods from org.apache.tools.ant.types.DataType:
checkAttributesAllowed,   checkChildrenAllowed,   circularReference,   clone,   dieOnCircularReference,   dieOnCircularReference,   dieOnCircularReference,   getCheckedRef,   getCheckedRef,   getCheckedRef,   getCheckedRef,   getDataTypeName,   getRefid,   invokeCircularReferenceCheck,   isChecked,   isReference,   noChildrenAllowed,   pushAndInvokeCircularReferenceCheck,   setChecked,   setRefid,   toString,   tooManyAttributes
Methods from org.apache.tools.ant.ProjectComponent:
clone,   getDescription,   getLocation,   getProject,   log,   log,   setDescription,   setLocation,   setProject
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector Detail:
 public  void addClasspath(Path path) 
    Add the classpath.
 public  void addParam(Parameter parameter) 
    Support for nested <param> tags.
 public  void addParam(String key,
    Object value) 
    Support for nested <param> tags.
 public  void buildFinished(BuildEvent event) 
    Signals that the last target has finished.
 public  void buildStarted(BuildEvent event) 
    Signals that a build has started.
 public  void configure() 
    Configures this Selector. Does this work only once per Selector object.

    Because some problems while configuring from Selector the configuration is done in the following order:

    1. collect the configuration data
    2. wait for the first isSelected() call
    3. set the default values
    4. set values for name pattern '*': update, cache, algorithm, comparator
    5. set values for name pattern '*.*: cache.cachefile, ...

    This configuration algorithm is needed because you don't know the order of arriving config-data. E.g. if you first set the cache.cachefilename and after that the cache itself, the default value for cachefilename is used, because setting the cache implies creating a new Cache instance - with its defaults.

 public Algorithm getAlgorithm() 
    Get the algorithm type to use.
 public Cache getCache() 
    Get the cache type to use.
 public ClassLoader getClassLoader() 
    Returns and initializes the classloader for this class.
 public Comparator getComparator() 
    Get the comparator type to use.
 public boolean getDelayUpdate() 
    Getter for the delay update
 public int getModified() 
    Getter for the modified count
 public boolean isSelected(Resource resource) 
    Implementation of ResourceSelector.isSelected().
 public boolean isSelected(File basedir,
    String filename,
    File file) 
    Implementation of BaseExtendSelector.isSelected().
 protected Object loadClass(String classname,
    String msg,
    Class type) 
    Loads the specified class and initializes an object of that class. Throws a BuildException using the given message if an error occurs during loading/instantiation or if the object is not from the given type.
 public  void messageLogged(BuildEvent event) 
    Signals a message logging event.
 protected  void saveCache() 
    save the cache file
 public  void setAlgorithm(AlgorithmName name) 
    Set the algorithm type to use.
 public  void setAlgorithmClass(String classname) 
    Setter for algorithmClass.
 public  void setCache(CacheName name) 
    Set the cache type to use.
 public  void setCacheClass(String classname) 
    Setter for cacheClass.
 public  void setClassLoader(ClassLoader loader) 
    Set the used ClassLoader. If you invoke this selector by API (e.g. inside some testcases) the selector will use a different classloader for loading the interface implementations than the caller. Therefore you will get a ClassCastException if you get the implementations from the selector and cast them.
 public  void setComparator(ComparatorName name) 
    Set the comparator type to use.
 public  void setComparatorClass(String classname) 
    Setter for comparatorClass.
 public  void setDelayUpdate(boolean delayUpdate) 
    Setter for the delay update
 public  void setModified(int modified) 
    Setter for the modified count
 public  void setParameters(Parameter[] parameters) 
    Defined in org.apache.tools.ant.types.Parameterizable. Overwrite implementation in superclass because only special parameters are valid.
 public  void setSeldirs(boolean seldirs) 
    Support for seldirs attribute.
 public  void setSelres(boolean newValue) 
    Support for selres attribute.
 public  void setUpdate(boolean update) 
    Support for update attribute.
 public  void targetFinished(BuildEvent event) 
    Signals that a target has finished.
 public  void targetStarted(BuildEvent event) 
    Signals that a target is starting.
 public  void taskFinished(BuildEvent event) 
    Signals that a task has finished.
 public  void taskStarted(BuildEvent event) 
    Signals that a task is starting.
 public String toString() 
    Override Object.toString().
 protected  void tryToSetAParameter(Object obj,
    String name,
    String value) 
    Try to set a value on an object using reflection. Helper method for easier access to IntrospectionHelper.setAttribute().
 public  void useParameter(Parameter parameter) 
    Support for nested tags. Parameter named cache, algorithm, comparator or update are mapped to the respective set-Method. Parameter which names starts with cache. or algorithm. or comparator. are tried to set on the appropriate object via its set-methods. Other parameters are invalid and an BuildException will be thrown.
 public  void verifySettings() 
    Overrides BaseSelector.verifySettings().