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

# Class PropertySet

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.types.DataType
org.apache.tools.ant.types.PropertySet

All Implemented Interfaces:
  `Cloneable, Iterable<Resource>, ResourceCollection`

public class PropertySet extends DataType implements ResourceCollection
A set of properties.

Since:
  Ant 1.6

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `PropertySet.BuiltinPropertySetName`
  Used for propertyref's builtin attribute.
  `static class`
  `PropertySet.PropertyRef`
  This is a nested class containing a reference to some properties and optionally a source of properties.

- ## Field Summary

  ### Fields inherited from class DataType

  `checked, ref`
  Modifier and Type
  Field
  Description
  `protected boolean`
  `checked`
  Deprecated.
  since 1.7.
  `protected Reference`
  `ref`
  Deprecated.
  since 1.7.

  ### Fields inherited from class ProjectComponent

  `description, location, project`
  Modifier and Type
  Field
  Description
  `protected String`
  `description`
  Deprecated.
  since 1.6.x.
  `protected Location`
  `location`
  Deprecated.
  since 1.6.x.
  `protected Project`
  `project`
  Deprecated.
  since 1.6.x.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PropertySet()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(FileNameMapper fileNameMapper)`
  Add a nested FileNameMapper.
  `void`
  `addPropertyref(PropertySet.PropertyRef ref)`
  Add a property reference (nested element) to the references to be used.
  `void`
  `addPropertyset(PropertySet ref)`
  Add another property set to this set.
  `void`
  `appendBuiltin(PropertySet.BuiltinPropertySetName b)`
  Allow builtin (all, system or commandline) properties in the set.
  `void`
  `appendName(String name)`
  Allow properties of a particular name in the set.
  `void`
  `appendPrefix(String prefix)`
  Allow properties whose names start with a prefix in the set.
  `void`
  `appendRegex(String regex)`
  Allow properties whose names match a regex in the set.
  `protected final void`
  `assertNotReference()`
  Ensures this data type is not a reference.
  `Mapper`
  `createMapper()`
  Create a mapper to map the property names.
  `protected void`
  `dieOnCircularReference(Stack<Object> stk, Project p)`
  Check to see whether any DataType we hold references to is included in the Stack (which holds all DataType instances that directly or indirectly reference this instance, including this instance itself).
  `boolean`
  `getDynamic()`
  Get the dynamic attribute.
  `Mapper`
  `getMapper()`
  Get the mapper attribute.
  `Properties`
  `getProperties()`
  This is the operation to get the existing or recalculated properties.
  `protected PropertySet`
  `getRef()`
  Performs the check for circular references and returns the referenced PropertySet.
  `boolean`
  `isFilesystemOnly()`
  Fulfill the ResourceCollection contract.
  `Iterator<Resource>`
  `iterator()`
  Fulfill the ResourceCollection interface.
  `void`
  `setDynamic(boolean dynamic)`
  Set whether to reevaluate the set every time the set is used.
  `void`
  `setMapper(String type, String from, String to)`
  Set a mapper to change property names.
  `void`
  `setNegate(boolean negate)`
  Set whether to negate results.
  `final void`
  `setRefid(Reference r)`
  Sets the value of the refid attribute.
  `int`
  `size()`
  Fulfill the ResourceCollection contract.
  `String`
  `toString()`
  A debug toString.

  ### Methods inherited from class DataType

  `checkAttributesAllowed, checkChildrenAllowed, circularReference, clone, dieOnCircularReference, dieOnCircularReference, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getDataTypeName, getRefid, invokeCircularReferenceCheck, isChecked, isReference, noChildrenAllowed, pushAndInvokeCircularReferenceCheck, setChecked, tooManyAttributes`
  Modifier and Type
  Method
  Description
  `protected void`
  `checkAttributesAllowed()`
  check that it is ok to set attributes, i.e that no reference is defined
  `protected void`
  `checkChildrenAllowed()`
  check that it is ok to add children, i.e that no reference is defined
  `protected BuildException`
  `circularReference()`
  Creates an exception that indicates the user has generated a loop of data types referencing each other.
  `Object`
  `clone()`
  `protected void`
  `dieOnCircularReference()`
  Convenience method.
  `protected void`
  `dieOnCircularReference(Project p)`
  Convenience method.
  `protected <T> T`
  `getCheckedRef()`
  Deprecated.
  use getCheckedRef(Class)
  `protected <T> T`
  `getCheckedRef(Class<T> requiredClass)`
  Performs the check for circular references and returns the referenced object.
  `protected <T> T`
  `getCheckedRef(Class<T> requiredClass, String dataTypeName)`
  Performs the check for circular references and returns the referenced object.
  `protected <T> T`
  `getCheckedRef(Class<T> requiredClass, String dataTypeName, Project project)`
  Performs the check for circular references and returns the referenced object.
  `protected <T> T`
  `getCheckedRef(Project p)`
  Deprecated.
  use getCheckedRef(Class)
  `protected String`
  `getDataTypeName()`
  Gets as descriptive as possible a name used for this datatype instance.
  `Reference`
  `getRefid()`
  get the reference set on this object
  `static void`
  `invokeCircularReferenceCheck(DataType dt, Stack<Object> stk, Project p)`
  Allow DataTypes outside org.apache.tools.ant.types to indirectly call dieOnCircularReference on nested DataTypes.
  `protected boolean`
  `isChecked()`
  The flag that is used to indicate that circular references have been checked.
  `boolean`
  `isReference()`
  Has the refid attribute of this element been set?
  `protected BuildException`
  `noChildrenAllowed()`
  Creates an exception that indicates that this XML element must not have child elements if the refid attribute is set.
  `static void`
  `pushAndInvokeCircularReferenceCheck(DataType dt, Stack<Object> stk, Project p)`
  Allow DataTypes outside org.apache.tools.ant.types to indirectly call dieOnCircularReference on nested DataTypes.
  `protected void`
  `setChecked(boolean checked)`
  Set the flag that is used to indicate that circular references have been checked.
  `protected BuildException`
  `tooManyAttributes()`
  Creates an exception that indicates that refid has to be the only attribute if it is set.

  ### Methods inherited from class ProjectComponent

  `getDescription, getLocation, getProject, log, log, setDescription, setLocation, setProject`
  Modifier and Type
  Method
  Description
  `String`
  `getDescription()`
  Returns the description of the current action.
  `Location`
  `getLocation()`
  Returns the file/location where this task was defined.
  `Project`
  `getProject()`
  Returns the project to which this component belongs.
  `void`
  `log(String msg)`
  Logs a message with the default (INFO) priority.
  `void`
  `log(String msg, int msgLevel)`
  Logs a message with the given priority.
  `void`
  `setDescription(String desc)`
  Sets a description of the current action.
  `void`
  `setLocation(Location location)`
  Sets the file/location where this task was defined.
  `void`
  `setProject(Project project)`
  Sets the project object of this component.

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Iterable

  `forEach, spliterator`

  ### Methods inherited from interface ResourceCollection

  `isEmpty, stream`
  Modifier and Type
  Method
  Description
  `default boolean`
  `isEmpty()`
  Learn whether this `ResourceCollection` is empty.
  `default Stream<? extends Resource>`
  `stream()`
  Return a `Stream` over this `ResourceCollection`.

- ## Constructor Details

  - ### PropertySet

    public PropertySet()

- ## Method Details

  - ### appendName

    public void appendName(String name)
    Allow properties of a particular name in the set.
    Parameters:
      `name` - the property name to allow.

  - ### appendRegex

    public void appendRegex(String regex)
    Allow properties whose names match a regex in the set.
    Parameters:
      `regex` - the regular expression to use.

  - ### appendPrefix

    public void appendPrefix(String prefix)
    Allow properties whose names start with a prefix in the set.
    Parameters:
      `prefix` - the prefix to use.

  - ### appendBuiltin

    public void appendBuiltin(PropertySet.BuiltinPropertySetName b)
    Allow builtin (all, system or commandline) properties in the set.
    Parameters:
      `b` - the type of builtin properties.

  - ### setMapper

    public void setMapper(String type, String from, String to)
    Set a mapper to change property names.
    Parameters:
      `type` - mapper type.
      `from` - source pattern.
      `to` - output pattern.

  - ### addPropertyref

    public void addPropertyref(PropertySet.PropertyRef ref)
    Add a property reference (nested element) to the references to be used.
    Parameters:
      `ref` - a property reference.

  - ### addPropertyset

    public void addPropertyset(PropertySet ref)
    Add another property set to this set.
    Parameters:
      `ref` - another property set.

  - ### createMapper

    public Mapper createMapper()
    Create a mapper to map the property names.
    Returns:
      a mapper to be configured.

  - ### add

    public void add(FileNameMapper fileNameMapper)
    Add a nested FileNameMapper.
    Parameters:
      `fileNameMapper` - the mapper to add.
    Since:
      Ant 1.6.3

  - ### setDynamic

    public void setDynamic(boolean dynamic)
    Set whether to reevaluate the set every time the set is used. Default is true.
    Parameters:
      `dynamic` - if true, reevaluate the property set each time the set is used. if false cache the property set the first time and use the cached set on subsequent occasions.

  - ### setNegate

    public void setNegate(boolean negate)
    Set whether to negate results. If "true", all properties not selected by nested elements will be returned. Default is "false".
    Parameters:
      `negate` - if true, negate the selection criteria.

  - ### getDynamic

    public boolean getDynamic()
    Get the dynamic attribute.
    Returns:
      true if the property set is to be evaluated each time it is used.

  - ### getMapper

    public Mapper getMapper()
    Get the mapper attribute.
    Returns:
      the mapper attribute.

  - ### getProperties

    public Properties getProperties()
    This is the operation to get the existing or recalculated properties.
    Returns:
      the properties for this propertyset.

  - ### getRef

    protected PropertySet getRef()
    Performs the check for circular references and returns the referenced PropertySet.
    Returns:
      the referenced PropertySet.

  - ### setRefid

    public final void setRefid(Reference r)
    Sets the value of the refid attribute.
    Overrides:
      `setRefid` in class `DataType`
    Parameters:
      `r` - the reference this datatype should point to.
    Throws:
      `BuildException` - if another attribute was set, since refid and all other attributes are mutually exclusive.

  - ### assertNotReference

    protected final void assertNotReference()
    Ensures this data type is not a reference.

    Calling this method as the first line of every bean method of this data type (setXyz, addXyz, createXyz) ensure proper handling of the refid attribute.

    Throws:
      `BuildException` - if the refid attribute was already set, since refid and all other attributes are mutually exclusive.

  - ### toString

    public String toString()
    A debug toString. This gets a comma separated list of key=value pairs for the properties in the set. The output order is sorted according to the keys' natural order.
    Overrides:
      `toString` in class `DataType`
    Returns:
      a string rep of this object.

  - ### iterator

    public Iterator<Resource> iterator()
    Fulfill the ResourceCollection interface.
    Specified by:
      `iterator` in interface `Iterable<Resource>`
    Returns:
      an Iterator of Resources.
    Since:
      Ant 1.7

  - ### size

    public int size()
    Fulfill the ResourceCollection contract.
    Specified by:
      `size` in interface `ResourceCollection`
    Returns:
      the size of this ResourceCollection.

  - ### isFilesystemOnly

    public boolean isFilesystemOnly()
    Fulfill the ResourceCollection contract.
    Specified by:
      `isFilesystemOnly` in interface `ResourceCollection`
    Returns:
      whether this is a filesystem-only resource collection.

  - ### dieOnCircularReference

    protected void dieOnCircularReference(Stack<Object> stk, Project p) throws BuildException
    Description copied from class: `DataType`
    Check to see whether any DataType we hold references to is included in the Stack (which holds all DataType instances that directly or indirectly reference this instance, including this instance itself).

    If one is included, throw a BuildException created by `circularReference`.

    This implementation is appropriate only for a DataType that cannot hold other DataTypes as children.

    The general contract of this method is that it shouldn't do anything if `DataType.checked` is true and set it to true on exit.

    Overrides:
      `dieOnCircularReference` in class `DataType`
    Parameters:
      `stk` - the stack of references to check.
      `p` - the project to use to dereference the references.
    Throws:
      `BuildException` - on error.