Module java.desktop
Package javax.imageio.plugins.tiff

## Class TIFFDirectory

- java.lang.Object
- - javax.imageio.plugins.tiff.TIFFDirectory

- All Implemented Interfaces:
    `Cloneable`

      public class TIFFDirectory
      extends Object
      implements Cloneable

  A convenience class for simplifying interaction with TIFF native image metadata. A TIFF image metadata tree represents an Image File Directory (IFD) from a TIFF 6.0 stream. An IFD consists of a number of IFD Entries each of which associates an identifying tag number with a compatible value. A `TIFFDirectory` instance corresponds to an IFD and contains a set of `TIFFField`s each of which corresponds to an IFD Entry in the IFD.

  When reading, a `TIFFDirectory` may be created by passing the value returned by `ImageReader.getImageMetadata()` to `createFromMetadata()`. The `TIFFField`s in the directory may then be obtained using the accessor methods provided in this class.

  When writing, an `IIOMetadata` object for use by one of the `write()` methods of `ImageWriter` may be created from a `TIFFDirectory` by `getAsMetadata()`. The `TIFFDirectory` itself may be created by construction or from the `IIOMetadata` object returned by `ImageWriter.getDefaultImageMetadata()`. The `TIFFField`s in the directory may be set using the mutator methods provided in this class.

  A `TIFFDirectory` is aware of the tag numbers in the group of `TIFFTagSet`s associated with it. When a `TIFFDirectory` is created from a native image metadata object, these tag sets are derived from the `tagSets` attribute of the `TIFFIFD` node.

  A `TIFFDirectory` might also have a parent `TIFFTag`. This will occur if the directory represents an IFD other than the root IFD of the image. The parent tag is the tag of the IFD Entry which is a pointer to the IFD represented by this `TIFFDirectory`. The `TIFFTag.isIFDPointer()` method of this parent `TIFFTag` must return `true`. When a `TIFFDirectory` is created from a native image metadata object, the parent tag set is set from the `parentTagName` attribute of the corresponding `TIFFIFD` node. Note that a `TIFFDirectory` instance which has a non-`null` parent tag will be contained in the data field of a `TIFFField` instance which has a tag field equal to the contained directory's parent tag.

  As an example consider an Exif image. The `TIFFDirectory` instance corresponding to the Exif IFD in the Exif stream would have parent tag `TAG_EXIF_IFD_POINTER` and would include `ExifTIFFTagSet` in its group of known tag sets. The `TIFFDirectory` corresponding to this Exif IFD will be contained in the data field of a `TIFFField` which will in turn be contained in the `TIFFDirectory` corresponding to the primary IFD of the Exif image which will itself have a `null`-valued parent tag.

  Note that this implementation is not synchronized. If multiple threads use a `TIFFDirectory` instance concurrently, and at least one of the threads modifies the directory, for example, by adding or removing `TIFFField`s or `TIFFTagSet`s, it must be synchronized externally.

  Since:
    9
  See Also:
    `IIOMetadata`, `TIFFField`, `TIFFTag`, `TIFFTagSet`

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TIFFDirectory​(TIFFTagSet[] tagSets, TIFFTag parentTag)` | Constructs a `TIFFDirectory` which is aware of a given group of `TIFFTagSet`s.

  - ### Method Summary

    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addTagSet​(TIFFTagSet tagSet)` | Adds an element to the group of `TIFFTagSet`s of which this directory is aware.
    `void` | `addTIFFField​(TIFFField f)` | Adds a TIFF field to the directory.
    `TIFFDirectory` | `clone()` | Clones the directory and all the fields contained therein.
    `boolean` | `containsTIFFField​(int tagNumber)` | Determines whether a TIFF field with the given tag number is contained in this directory.
    `static TIFFDirectory` | `createFromMetadata​(IIOMetadata tiffImageMetadata)` | Creates a `TIFFDirectory` instance from the contents of an image metadata object.
    `IIOMetadata` | `getAsMetadata()` | Converts the directory to a metadata object.
    `int` | `getNumTIFFFields()` | Returns the number of `TIFFField`s in this directory.
    `TIFFTag` | `getParentTag()` | Returns the parent `TIFFTag` of this directory if one has been defined or `null` otherwise.
    `TIFFTag` | `getTag​(int tagNumber)` | Returns the `TIFFTag` which has tag number equal to `tagNumber` or `null` if no such tag exists in the `TIFFTagSet`s associated with this directory.
    `TIFFTagSet[]` | `getTagSets()` | Returns the `TIFFTagSet`s of which this directory is aware.
    `TIFFField` | `getTIFFField​(int tagNumber)` | Retrieves a TIFF field from the directory.
    `TIFFField[]` | `getTIFFFields()` | Retrieves all TIFF fields from the directory.
    `void` | `removeTagSet​(TIFFTagSet tagSet)` | Removes an element from the group of `TIFFTagSet`s of which this directory is aware.
    `void` | `removeTIFFField​(int tagNumber)` | Removes a TIFF field from the directory.
    `void` | `removeTIFFFields()` | Removes all TIFF fields from the directory.

    - ### Methods declared in class java.lang.Object

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

- - ### Constructor Detail

    - #### TIFFDirectory

          public TIFFDirectory​(TIFFTagSet[] tagSets,
                               TIFFTag parentTag)

      Constructs a `TIFFDirectory` which is aware of a given group of `TIFFTagSet`s. An optional parent `TIFFTag` may also be specified.
      Parameters:
        `tagSets` - The `TIFFTagSets` associated with this directory.
        `parentTag` - The parent `TIFFTag` of this directory; may be `null`.
      Throws:
        `NullPointerException` - if `tagSets` is `null`.

  - ### Method Detail

    - #### createFromMetadata

          public static TIFFDirectory createFromMetadata​(IIOMetadata tiffImageMetadata)
                                                  throws IIOInvalidTreeException

      Creates a `TIFFDirectory` instance from the contents of an image metadata object. The supplied object must support an image metadata format supported by the TIFF `ImageWriter` plug-in. This will usually be either the TIFF native image metadata format `javax_imageio_tiff_image_1.0` or the Java Image I/O standard metadata format `javax_imageio_1.0`.
      Parameters:
        `tiffImageMetadata` - A metadata object which supports a compatible image metadata format.
      Returns:
        A `TIFFDirectory` populated from the contents of the supplied metadata object.
      Throws:
        `NullPointerException` - if `tiffImageMetadata` is `null`.
        `IllegalArgumentException` - if `tiffImageMetadata` does not support a compatible image metadata format.
        `IIOInvalidTreeException` - if the supplied metadata object cannot be parsed.

    - #### getTagSets

          public TIFFTagSet[] getTagSets()

      Returns the `TIFFTagSet`s of which this directory is aware.
      Returns:
        The `TIFFTagSet`s associated with this `TIFFDirectory`.

    - #### addTagSet

          public void addTagSet​(TIFFTagSet tagSet)

      Adds an element to the group of `TIFFTagSet`s of which this directory is aware.
      Parameters:
        `tagSet` - The `TIFFTagSet` to add.
      Throws:
        `NullPointerException` - if `tagSet` is `null`.

    - #### removeTagSet

          public void removeTagSet​(TIFFTagSet tagSet)

      Removes an element from the group of `TIFFTagSet`s of which this directory is aware.
      Parameters:
        `tagSet` - The `TIFFTagSet` to remove.
      Throws:
        `NullPointerException` - if `tagSet` is `null`.

    - #### getParentTag

          public TIFFTag getParentTag()

      Returns the parent `TIFFTag` of this directory if one has been defined or `null` otherwise.
      Returns:
        The parent `TIFFTag` of this `TIFFDiectory` or `null`.

    - #### getTag

          public TIFFTag getTag​(int tagNumber)

      Returns the `TIFFTag` which has tag number equal to `tagNumber` or `null` if no such tag exists in the `TIFFTagSet`s associated with this directory.
      Parameters:
        `tagNumber` - The tag number of interest.
      Returns:
        The corresponding `TIFFTag` or `null`.

    - #### getNumTIFFFields

          public int getNumTIFFFields()

      Returns the number of `TIFFField`s in this directory.
      Returns:
        The number of `TIFFField`s in this `TIFFDirectory`.

    - #### containsTIFFField

          public boolean containsTIFFField​(int tagNumber)

      Determines whether a TIFF field with the given tag number is contained in this directory.
      Parameters:
        `tagNumber` - The tag number.
      Returns:
        Whether a `TIFFTag` with tag number equal to `tagNumber` is present in this `TIFFDirectory`.

    - #### addTIFFField

          public void addTIFFField​(TIFFField f)

      Adds a TIFF field to the directory.
      Parameters:
        `f` - The field to add.
      Throws:
        `NullPointerException` - if `f` is `null`.

    - #### getTIFFField

          public TIFFField getTIFFField​(int tagNumber)

      Retrieves a TIFF field from the directory.
      Parameters:
        `tagNumber` - The tag number of the tag associated with the field.
      Returns:
        A `TIFFField` with the requested tag number of `null` if no such field is present.

    - #### removeTIFFField

          public void removeTIFFField​(int tagNumber)

      Removes a TIFF field from the directory.
      Parameters:
        `tagNumber` - The tag number of the tag associated with the field.

    - #### getTIFFFields

          public TIFFField[] getTIFFFields()

      Retrieves all TIFF fields from the directory.
      Returns:
        An array of all TIFF fields in order of numerically increasing tag number.

    - #### removeTIFFFields

          public void removeTIFFFields()

      Removes all TIFF fields from the directory.

    - #### getAsMetadata

          public IIOMetadata getAsMetadata()

      Converts the directory to a metadata object.
      Returns:
        A metadata instance initialized from the contents of this `TIFFDirectory`.

    - #### clone

          public TIFFDirectory clone()
                              throws CloneNotSupportedException

      Clones the directory and all the fields contained therein.
      Overrides:
        `clone` in class `Object`
      Returns:
        A clone of this `TIFFDirectory`.
      Throws:
        `CloneNotSupportedException` - if the instance cannot be cloned.
      See Also:
        `Cloneable`