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 Details

  - ### 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 Details

  - ### 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`