ModifiedSelector (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.types.selectors.modifiedselector, class: ModifiedSelector

Package org.apache.tools.ant.types.selectors.modifiedselector

# Class ModifiedSelector

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:
  `Cloneable`, `EventListener`, `BuildListener`, `Parameterizable`, `ResourceSelector`, `ExtendFileSelector`, `FileSelector`

public class ModifiedSelector extends BaseExtendSelector implements BuildListener, ResourceSelector

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 simplest example is

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

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

       <copy todir="dest">
           <fileset 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>
           </fileset>
       </copy>

And the same rewritten as CustomSelector would be

       <copy todir="dest">
           <fileset 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>
           </fileset>
       </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/mycompany-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"/>.

Since:
  Ant 1.6

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ModifiedSelector.AlgorithmName`
  The enumerated type for algorithm.
  `static class`
  `ModifiedSelector.CacheName`
  The enumerated type for cache.
  `static class`
  `ModifiedSelector.ComparatorName`
  The enumerated type for algorithm.

- ## Field Summary

  ### Fields inherited from class org.apache.tools.ant.types.selectors.BaseExtendSelector

  `parameters`

  ### Fields inherited from class org.apache.tools.ant.types.DataType

  `checked, ref`

  ### Fields inherited from class org.apache.tools.ant.ProjectComponent

  `description, location, project`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ModifiedSelector()`
  Bean-Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addClasspath(Path path)`
  Add the classpath.
  `void`
  `addParam(String key, Object value)`
  Support for nested <param> tags.
  `void`
  `addParam(Parameter parameter)`
  Support for nested <param> tags.
  `void`
  `buildFinished(BuildEvent event)`
  Signals that the last target has finished.
  `void`
  `buildStarted(BuildEvent event)`
  Signals that a build has started.
  `void`
  `configure()`
  Configures this Selector.
  `Algorithm`
  `getAlgorithm()`
  Get the algorithm type to use.
  `Cache`
  `getCache()`
  Get the cache type to use.
  `ClassLoader`
  `getClassLoader()`
  Returns and initializes the classloader for this class.
  `Comparator<? super String>`
  `getComparator()`
  Get the comparator type to use.
  `boolean`
  `getDelayUpdate()`
  Getter for the delay update
  `int`
  `getModified()`
  Getter for the modified count
  `boolean`
  `isSelected(File basedir, String filename, File file)`
  Implementation of BaseExtendSelector.isSelected().
  `boolean`
  `isSelected(Resource resource)`
  Implementation of ResourceSelector.isSelected().
  `protected <T> T`
  `loadClass(String classname, String msg, Class<? extends T> type)`
  Loads the specified class and initializes an object of that class.
  `void`
  `messageLogged(BuildEvent event)`
  Signals a message logging event.
  `protected void`
  `saveCache()`
  save the cache file
  `void`
  `setAlgorithm(ModifiedSelector.AlgorithmName name)`
  Set the algorithm type to use.
  `void`
  `setAlgorithmClass(String classname)`
  Setter for algorithmClass.
  `void`
  `setCache(ModifiedSelector.CacheName name)`
  Set the cache type to use.
  `void`
  `setCacheClass(String classname)`
  Setter for cacheClass.
  `void`
  `setClassLoader(ClassLoader loader)`
  Set the used ClassLoader.
  `void`
  `setComparator(ModifiedSelector.ComparatorName name)`
  Set the comparator type to use.
  `void`
  `setComparatorClass(String classname)`
  Setter for comparatorClass.
  `void`
  `setDelayUpdate(boolean delayUpdate)`
  Setter for the delay update
  `void`
  `setModified(int modified)`
  Setter for the modified count
  `void`
  `setParameters(Parameter... parameters)`
  Defined in org.apache.tools.ant.types.Parameterizable.
  `void`
  `setSeldirs(boolean seldirs)`
  Support for seldirs attribute.
  `void`
  `setSelres(boolean newValue)`
  Support for selres attribute.
  `void`
  `setUpdate(boolean update)`
  Support for update attribute.
  `void`
  `targetFinished(BuildEvent event)`
  Signals that a target has finished.
  `void`
  `targetStarted(BuildEvent event)`
  Signals that a target is starting.
  `void`
  `taskFinished(BuildEvent event)`
  Signals that a task has finished.
  `void`
  `taskStarted(BuildEvent event)`
  Signals that a task is starting.
  `String`
  `toString()`
  Override Object.toString().
  `protected void`
  `tryToSetAParameter(Object obj, String name, String value)`
  Try to set a value on an object using reflection.
  `void`
  `useParameter(Parameter parameter)`
  Support for nested `<param name="" value=""/>` tags.
  `void`
  `verifySettings()`
  Overrides BaseSelector.verifySettings().

  ### Methods inherited from class org.apache.tools.ant.types.selectors.BaseExtendSelector

  `getParameters`

  ### Methods inherited from class org.apache.tools.ant.types.selectors.BaseSelector

  `getError, setError, setError, validate`

  ### Methods inherited from class org.apache.tools.ant.types.DataType

  `checkAttributesAllowed, checkChildrenAllowed, circularReference, clone, dieOnCircularReference, dieOnCircularReference, dieOnCircularReference, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getDataTypeName, getRefid, invokeCircularReferenceCheck, isChecked, isReference, noChildrenAllowed, pushAndInvokeCircularReferenceCheck, setChecked, setRefid, tooManyAttributes`

  ### Methods inherited from class org.apache.tools.ant.ProjectComponent

  `getDescription, getLocation, getProject, log, log, setDescription, setLocation, setProject`

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### ModifiedSelector

    public ModifiedSelector()
    Bean-Constructor.

- ## Method Details

  - ### verifySettings

    public void verifySettings()
    Overrides BaseSelector.verifySettings().
    Overrides:
      `verifySettings` in class `BaseSelector`

  - ### configure

    public void configure()
    Configures this Selector. Does this work only once per Selector object.

    Because some problems while configuring from <custom>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.

  - ### loadClass

    protected <T> T loadClass(String classname, String msg, Class<? extends T> 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.
    Type Parameters:
      `T` - desired type
    Parameters:
      `classname` - the classname
      `msg` - the message-part for the BuildException
      `type` - the type to check against
    Returns:
      a castable object

  - ### isSelected

    public boolean isSelected(Resource resource)
    Implementation of ResourceSelector.isSelected().
    Specified by:
      `isSelected` in interface `FileSelector`
    Specified by:
      `isSelected` in interface `ResourceSelector`
    Parameters:
      `resource` - The resource to check
    Returns:
      whether the resource is selected
    See Also:
      - `ResourceSelector.isSelected(Resource)`

  - ### isSelected

    public boolean isSelected(File basedir, String filename, File file)
    Implementation of BaseExtendSelector.isSelected().
    Specified by:
      `isSelected` in interface `FileSelector`
    Specified by:
      `isSelected` in class `BaseExtendSelector`
    Parameters:
      `basedir` - as described in BaseExtendSelector
      `filename` - as described in BaseExtendSelector
      `file` - as described in BaseExtendSelector
    Returns:
      as described in BaseExtendSelector

  - ### saveCache

    protected void saveCache()
    save the cache file

  - ### setAlgorithmClass

    public void setAlgorithmClass(String classname)
    Setter for algorithmClass.
    Parameters:
      `classname` - new value

  - ### setComparatorClass

    public void setComparatorClass(String classname)
    Setter for comparatorClass.
    Parameters:
      `classname` - new value

  - ### setCacheClass

    public void setCacheClass(String classname)
    Setter for cacheClass.
    Parameters:
      `classname` - new value

  - ### setUpdate

    public void setUpdate(boolean update)
    Support for update attribute.
    Parameters:
      `update` - new value

  - ### setSeldirs

    public void setSeldirs(boolean seldirs)
    Support for seldirs attribute.
    Parameters:
      `seldirs` - new value

  - ### setSelres

    public void setSelres(boolean newValue)
    Support for selres attribute.
    Parameters:
      `newValue` - the new value

  - ### getModified

    public int getModified()
    Getter for the modified count
    Returns:
      modified count

  - ### setModified

    public void setModified(int modified)
    Setter for the modified count
    Parameters:
      `modified` - count

  - ### getDelayUpdate

    public boolean getDelayUpdate()
    Getter for the delay update
    Returns:
      true if we should delay for performance

  - ### setDelayUpdate

    public void setDelayUpdate(boolean delayUpdate)
    Setter for the delay update
    Parameters:
      `delayUpdate` - true if we should delay for performance

  - ### addClasspath

    public void addClasspath(Path path)
    Add the classpath.
    Parameters:
      `path` - the classpath

  - ### getClassLoader

    public ClassLoader getClassLoader()
    Returns and initializes the classloader for this class.
    Returns:
      the classloader

  - ### setClassLoader

    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.
    Parameters:
      `loader` - the ClassLoader to use

  - ### addParam

    public void addParam(String key, Object value)
    Support for nested <param> tags.
    Parameters:
      `key` - the key of the parameter
      `value` - the value of the parameter

  - ### addParam

    public void addParam(Parameter parameter)
    Support for nested <param> tags.
    Parameters:
      `parameter` - the parameter object

  - ### setParameters

    public void setParameters(Parameter... parameters)
    Defined in org.apache.tools.ant.types.Parameterizable. Overwrite implementation in superclass because only special parameters are valid.
    Specified by:
      `setParameters` in interface `Parameterizable`
    Overrides:
      `setParameters` in class `BaseExtendSelector`
    Parameters:
      `parameters` - the parameters to set.
    See Also:
      - `addParam(String,Object)`

  - ### useParameter

    public void useParameter(Parameter parameter)
    Support for nested `<param name="" value=""/>` 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.
    Parameters:
      `parameter` - Key and value as parameter object

  - ### tryToSetAParameter

    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().
    Parameters:
      `obj` - the object on which the attribute should be set
      `name` - the attributename
      `value` - the new value

  - ### toString

    public String toString()
    Override Object.toString().
    Overrides:
      `toString` in class `DataType`
    Returns:
      information about this selector

  - ### buildFinished

    public void buildFinished(BuildEvent event)
    Signals that the last target has finished.
    Specified by:
      `buildFinished` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent
    See Also:
      - `BuildEvent.getException()`

  - ### targetFinished

    public void targetFinished(BuildEvent event)
    Signals that a target has finished.
    Specified by:
      `targetFinished` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent
    See Also:
      - `BuildEvent.getException()`

  - ### taskFinished

    public void taskFinished(BuildEvent event)
    Signals that a task has finished.
    Specified by:
      `taskFinished` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent
    See Also:
      - `BuildEvent.getException()`

  - ### buildStarted

    public void buildStarted(BuildEvent event)
    Signals that a build has started.
    Specified by:
      `buildStarted` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent

  - ### targetStarted

    public void targetStarted(BuildEvent event)
    Signals that a target is starting.
    Specified by:
      `targetStarted` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent
    See Also:
      - `BuildEvent.getTarget()`

  - ### taskStarted

    public void taskStarted(BuildEvent event)
    Signals that a task is starting.
    Specified by:
      `taskStarted` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent
    See Also:
      - `BuildEvent.getTask()`

  - ### messageLogged

    public void messageLogged(BuildEvent event)
    Signals a message logging event.
    Specified by:
      `messageLogged` in interface `BuildListener`
    Parameters:
      `event` - received BuildEvent
    See Also:
      - `BuildEvent.getMessage()`
      - `BuildEvent.getException()`
      - `BuildEvent.getPriority()`

  - ### getCache

    public Cache getCache()
    Get the cache type to use.
    Returns:
      the enumerated cache type

  - ### setCache

    public void setCache(ModifiedSelector.CacheName name)
    Set the cache type to use.
    Parameters:
      `name` - an enumerated cache type.

  - ### getAlgorithm

    public Algorithm getAlgorithm()
    Get the algorithm type to use.
    Returns:
      the enumerated algorithm type

  - ### setAlgorithm

    public void setAlgorithm(ModifiedSelector.AlgorithmName name)
    Set the algorithm type to use.
    Parameters:
      `name` - an enumerated algorithm type.

  - ### getComparator

    public Comparator<? super String> getComparator()
    Get the comparator type to use.
    Returns:
      the enumerated comparator type

  - ### setComparator

    public void setComparator(ModifiedSelector.ComparatorName name)
    Set the comparator type to use.
    Parameters:
      `name` - an enumerated comparator type.