# Interface DirectoryProperty

All Superinterfaces:
  `FileSystemLocationProperty<Directory>, HasConfigurableValue, Property<Directory>, Provider<Directory>, SupportsConvention`

@ManagedType public interface DirectoryProperty extends FileSystemLocationProperty<Directory>
Represents some configurable directory location, whose value is mutable.

Note: This interface is not intended for implementation by build script or plugin authors.

Since:
  4.3
See Also:
  - Create an instance of this as a managed property (preferred).
  - Create an instance of this manually.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DirectoryProperty`
  `convention(@Nullable Directory value)`
  Specifies the value to use as the convention (default value) for this property.
  `DirectoryProperty`
  `convention(Provider<? extends Directory> provider)`
  Specifies the provider to be used to query the convention (default value) for this property.
  `Provider<Directory>`
  `dir(String path)`
  Returns a `Directory` whose value is the given path resolved relative to the value of this directory.
  `Provider<Directory>`
  `dir(Provider<? extends CharSequence> path)`
  Returns a `Directory` whose value is the given path resolved relative to the value of this directory.
  `Provider<RegularFile>`
  `file(String path)`
  Returns a `RegularFile` whose value is the given path resolved relative to the value of this directory.
  `Provider<RegularFile>`
  `file(Provider<? extends CharSequence> path)`
  Returns a `RegularFile` whose value is the given path resolved relative to the value of this directory.
  `DirectoryProperty`
  `fileProvider(Provider<File> provider)`
  Sets the location of this file, using a `File` `Provider` instance.
  `FileCollection`
  `files(@Nullable Object... paths)`
  Returns a `FileCollection` containing the given files, whose locations are the given paths resolved relative to this directory, as defined by `Project.files(Object...)`.
  `DirectoryProperty`
  `fileValue(@Nullable File file)`
  Sets the location of this file, using a `File` instance.
  `FileTree`
  `getAsFileTree()`
  Returns a `FileTree` that allows the files and directories contained in this directory to be queried.
  `DirectoryProperty`
  `value(@Nullable Directory value)`
  Sets the value of the property to the given value, replacing whatever value the property already had.
  `DirectoryProperty`
  `value(Provider<? extends Directory> provider)`
  Sets the property to have the same value as the given provider, replacing whatever value the property already had.

  ### Methods inherited from interface FileSystemLocationProperty

  `getAsFile, getLocationOnly, set`

  ### Methods inherited from interface HasConfigurableValue

  `disallowChanges, disallowUnsafeRead, finalizeValueOnRead`

  ### Methods inherited from interface Property

  `finalizeValue, set, set, unset, unsetConvention`

  ### Methods inherited from interface Provider

  `filter, flatMap, get, getOrElse, getOrNull, isPresent, map, orElse, orElse, zip`

- ## Method Details

  - ### getAsFileTree

    FileTree getAsFileTree()
    Returns a `FileTree` that allows the files and directories contained in this directory to be queried.
    Since:
      4.3

  - ### value

    DirectoryProperty value(@Nullable Directory value)
    Sets the value of the property to the given value, replacing whatever value the property already had. This is the same as `Property.set(Object)` but returns this property to allow method chaining.

    This method can also be used to discard the value of the property, by passing it `null`. When the value is discarded (or has never been set in the first place), the convention (default value) for this property, if specified, will be used to provide the value instead.

    Specified by:
      `value` in interface `Property<Directory>`
    Parameters:
      `value` - The value, can be null.
    Returns:
      this

  - ### value

    DirectoryProperty value(Provider<? extends Directory> provider)
    Sets the property to have the same value as the given provider, replacing whatever value the property already had. This property will track the value of the provider and query its value each time the value of the property is queried. When the provider has no value, this property will also have no value. This is the same as `Property.set(Provider)` but returns this property to allow method chaining.

    This method can NOT be used to discard the value of the property. Specifying a `null` provider will result in an `IllegalArgumentException` being thrown. When the provider has no value, this property will also have no value - regardless of whether or not a convention has been set.

    When the given provider represents a task output, this property will also carry the task dependency information from the provider.

    Specified by:
      `value` in interface `Property<Directory>`
    Parameters:
      `provider` - The provider whose value to use.
    Returns:
      this

  - ### fileValue

    DirectoryProperty fileValue(@Nullable File file)
    Sets the location of this file, using a `File` instance. `File` instances with relative paths are resolved relative to the project directory of the project that owns this property instance.

    This method is the same as `FileSystemLocationProperty.set(File)` but allows method chaining.

    Specified by:
      `fileValue` in interface `FileSystemLocationProperty<Directory>`
    Returns:
      this

  - ### fileProvider

    DirectoryProperty fileProvider(Provider<File> provider)
    Sets the location of this file, using a `File` `Provider` instance. `File` instances with relative paths are resolved relative to the project directory of the project that owns this property instance.
    Specified by:
      `fileProvider` in interface `FileSystemLocationProperty<Directory>`
    Returns:
      this

  - ### convention

    DirectoryProperty convention(@Nullable Directory value)
    Specifies the value to use as the convention (default value) for this property. If the convention is set and no explicit value or value provider has been specified, then the convention will be returned as the value of the property (when queried).

    This method can be used to specify that the property does not have a default value, by passing it `null`.

    Specified by:
      `convention` in interface `Property<Directory>`
    Parameters:
      `value` - The convention value, or `null` if the property should have no default value.
    Returns:
      this

  - ### convention

    DirectoryProperty convention(Provider<? extends Directory> provider)
    Specifies the provider to be used to query the convention (default value) for this property. If a convention provider has been set and no explicit value or value provider has been specified, then the convention provider's value will be returned as the value of the property (when queried).

    The property's convention tracks the convention provider. Whenever the convention's actual value is needed, the convention provider will be queried anew.

    This method can't be used to specify that a property does not have a default value. Passing in a `null` provider will result in an `IllegalArgumentException` being thrown. When the provider doesn't have a value, then the property will behave as if it wouldn't have a convention specified.

    Specified by:
      `convention` in interface `Property<Directory>`
    Parameters:
      `provider` - The provider of the property's convention value, can't be null.
    Returns:
      this

  - ### dir

    Provider<Directory> dir(String path)
    Returns a `Directory` whose value is the given path resolved relative to the value of this directory.
    Parameters:
      `path` - The path. Can be absolute.
    Returns:
      The directory.
    Since:
      4.3

  - ### dir

    Provider<Directory> dir(Provider<? extends CharSequence> path)
    Returns a `Directory` whose value is the given path resolved relative to the value of this directory.
    Parameters:
      `path` - The path. Can have a value that is an absolute path.
    Returns:
      The directory.
    Since:
      4.3

  - ### file

    Provider<RegularFile> file(String path)
    Returns a `RegularFile` whose value is the given path resolved relative to the value of this directory.
    Parameters:
      `path` - The path. Can be absolute.
    Returns:
      The file.
    Since:
      4.3

  - ### file

    Provider<RegularFile> file(Provider<? extends CharSequence> path)
    Returns a `RegularFile` whose value is the given path resolved relative to the value of this directory.
    Parameters:
      `path` - The path. Can have a value that is an absolute path.
    Returns:
      The file.
    Since:
      4.3

  - ### files

    FileCollection files(@Nullable Object... paths)
    Returns a `FileCollection` containing the given files, whose locations are the given paths resolved relative to this directory, as defined by `Project.files(Object...)`. This method can also be used to create an empty collection, but the collection may not be mutated later.
    Parameters:
      `paths` - The paths to the files. May be empty.
    Returns:
      The file collection.
    Since:
      6.0