Package org.apache.sis.metadata.iso.distribution

## Class DefaultFormat

- Object
- - AbstractMetadata
  - - ModifiableMetadata
    - - ISOMetadata
      - - DefaultFormat

- All Implemented Interfaces:
    `Serializable`, `Emptiable`, `LenientComparable`, `IdentifiedObject`, `Format`

      public class DefaultFormat
      extends ISOMetadata
      implements Format

  Description of the computer language construct that specifies the representation of data objects in a record, file, message, storage device or transmission channel. The following properties are mandatory in a well-formed metadata according ISO 19115:
  `MD_Format` `└─formatSpecificationCitation……` Citation/URL of the specification format. `├─title……………………………………………………` Name by which the cited resource is known. `└─date………………………………………………………` Reference date for the cited resource.
  Each `Format` instance should contain a reference to the format specification, for example "PNG (Portable Network Graphics) Specification". The specification often has an abbreviation (for example "PNG") which can be stored as an alternate title.

  Apache SIS provides pre-defined metadata structures for some commonly-used formats. A pre-defined format can be obtained by a call to `lookup(Format​.class, abbreviation)` where abbreviation can be one of the values listed below:

  Specification titles for well-known format names
  Abbreviation | Specification title
  --- | ---
  CSV | Common Format and MIME Type for Comma-Separated Values (CSV) Files
  GeoTIFF | GeoTIFF Coverage Encoding Profile
  NetCDF | NetCDF Classic and 64-bit Offset Format
  PNG | PNG (Portable Network Graphics) Specification

  Above list may be expanded in any future SIS version.

  Limitations:

  - Instances of this class are not synchronized for multi-threading. Synchronization, if needed, is caller's responsibility.
  - Serialized objects of this class are not guaranteed to be compatible with future Apache SIS releases. Serialization support is appropriate for short term storage or RMI between applications running the same version of Apache SIS. For long term storage, use `XML` instead.
  Since:
    0.3
  See Also:
    Serialized Form

  Defined in the `sis-metadata` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class ModifiableMetadata

      `ModifiableMetadata​.State`

  - ### Field Summary

    - ### Fields inherited from class ISOMetadata

      `identifiers`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultFormat()` | Constructs an initially empty format.
    `DefaultFormat​(Format object)` | Constructs a new instance initialized with the values from the specified metadata object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static DefaultFormat` | `castOrCopy​(Format object)` | Returns a SIS metadata implementation with the values of the given arbitrary implementation.
    `InternationalString` | `getAmendmentNumber()` | Returns the amendment number of the format version.
    `InternationalString` | `getFileDecompressionTechnique()` | Returns recommendations of algorithms or processes that can be applied to read or expand resources to which compression techniques have been applied.
    `Collection<Distributor>` | `getFormatDistributors()` | Provides information about the distributor's format.
    `Citation` | `getFormatSpecificationCitation()` | Returns the citation / URL of the specification format.
    `Collection<Medium>` | `getMedia()` | Returns the media used by the format.
    `InternationalString` | `getName()` | Deprecated. As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().getAlternateTitles()`.
    `InternationalString` | `getSpecification()` | Deprecated. As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().getTitle()`.
    `InternationalString` | `getVersion()` | Deprecated. As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().getEdition()`.
    `void` | `setAmendmentNumber​(InternationalString newValue)` | Sets the amendment number of the format version.
    `void` | `setFileDecompressionTechnique​(InternationalString newValue)` | Sets recommendations of algorithms or processes that can be applied to read or expand resources to which compression techniques have been applied.
    `void` | `setFormatDistributors​(Collection<? extends Distributor> newValues)` | Sets information about the distributor's format.
    `void` | `setFormatSpecificationCitation​(Citation newValue)` | Sets the citation / URL of the specification format.
    `void` | `setMedia​(Collection<? extends Medium> newValues)` | Sets the media used by the format.
    `void` | `setName​(InternationalString newValue)` | Deprecated. As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().setAlternateTitles(Collection)`.
    `void` | `setSpecification​(InternationalString newValue)` | Deprecated. As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().setTitle(InternationalString)`.
    `void` | `setVersion​(InternationalString newValue)` | Deprecated. As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().setEdition(InternationalString)`.

    - ### Methods inherited from class ISOMetadata

      `getIdentifier, getIdentifierMap, getIdentifiers, getStandard, setIdentifier, transitionTo`

    - ### Methods inherited from class ModifiableMetadata

      `checkWritePermission, checkWritePermission, collectionType, copyCollection, copyList, copyMap, copySet, freeze, isModifiable, nonNullCollection, nonNullList, nonNullMap, nonNullSet, singleton, state, unmodifiable, writeCollection, writeList, writeMap, writeSet`

    - ### Methods inherited from class AbstractMetadata

      `asMap, asTreeTable, equals, equals, getInterface, hashCode, isEmpty, prune, toString`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultFormat

          public DefaultFormat()

      Constructs an initially empty format.

    - #### DefaultFormat

          public DefaultFormat​(Format object)

      Constructs a new instance initialized with the values from the specified metadata object. This is a shallow copy constructor, since the other metadata contained in the given object are not recursively copied.
      Parameters:
        `object` - the metadata to copy values from, or `null` if none.
      See Also:
        `castOrCopy(Format)`

  - ### Method Detail

    - #### castOrCopy

          public static DefaultFormat castOrCopy​(Format object)

      Returns a SIS metadata implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:
      - If the given object is `null`, then this method returns `null`.
      - Otherwise if the given object is already an instance of `DefaultFormat`, then it is returned unchanged.
      - Otherwise a new `DefaultFormat` instance is created using the copy constructor and returned. Note that this is a shallow copy operation, since the other metadata contained in the given object are not recursively copied.
      Parameters:
        `object` - the object to get as a SIS implementation, or `null` if none.
      Returns:
        a SIS implementation containing the values of the given object (may be the given object itself), or `null` if the argument was null.

    - #### getFormatSpecificationCitation

          @UML(identifier="formatSpecificationCitation",
               obligation=MANDATORY,
               specification=ISO_19115)
          public Citation getFormatSpecificationCitation()

      Returns the citation / URL of the specification format.
      Returns:
        citation / URL of the specification format.
      Since:
        0.5

    - #### setFormatSpecificationCitation

          public void setFormatSpecificationCitation​(Citation newValue)

      Sets the citation / URL of the specification format.
      Parameters:
        `newValue` - the new specification format.
      Since:
        0.5

    - #### getSpecification

          @Deprecated
          public InternationalString getSpecification()

      Deprecated.
      As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().getTitle()`.
      Returns the name of a subset, profile, or product specification of the format.
      Specified by:
        `getSpecification` in interface `Format`
      Returns:
        name of a subset, profile, or product specification of the format, or `null`.

    - #### setSpecification

          @Deprecated
          public void setSpecification​(InternationalString newValue)

      Deprecated.
      As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().setTitle(InternationalString)`.
      Sets the name of a subset, profile, or product specification of the format.
      Parameters:
        `newValue` - the new specification.

    - #### getName

          @Deprecated
          public InternationalString getName()

      Deprecated.
      As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().getAlternateTitles()`. Note that citation alternate titles are often used for abbreviations.
      Returns the name of the data transfer format(s).
      Specified by:
        `getName` in interface `Format`
      Returns:
        name of the data transfer format(s), or `null`.

    - #### setName

          @Deprecated
          public void setName​(InternationalString newValue)

      Deprecated.
      As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().setAlternateTitles(Collection)`.
      Sets the name of the data transfer format(s).
      Parameters:
        `newValue` - the new name.

    - #### getVersion

          @Deprecated
          public InternationalString getVersion()

      Deprecated.
      As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().getEdition()`.
      Returns the version of the format (date, number, etc.).
      Specified by:
        `getVersion` in interface `Format`
      Returns:
        version of the format, or `null`.

    - #### setVersion

          @Deprecated
          public void setVersion​(InternationalString newValue)

      Deprecated.
      As of ISO 19115:2014, replaced by `getFormatSpecificationCitation().setEdition(InternationalString)`.
      Sets the version of the format (date, number, etc.).
      Parameters:
        `newValue` - the new version.

    - #### getAmendmentNumber

          public InternationalString getAmendmentNumber()

      Returns the amendment number of the format version.
      Specified by:
        `getAmendmentNumber` in interface `Format`
      Returns:
        amendment number of the format version, or `null`.

    - #### setAmendmentNumber

          public void setAmendmentNumber​(InternationalString newValue)

      Sets the amendment number of the format version.
      Parameters:
        `newValue` - the new amendment number.

    - #### getFileDecompressionTechnique

          public InternationalString getFileDecompressionTechnique()

      Returns recommendations of algorithms or processes that can be applied to read or expand resources to which compression techniques have been applied.
      Specified by:
        `getFileDecompressionTechnique` in interface `Format`
      Returns:
        processes that can be applied to read resources to which compression techniques have been applied, or `null`.

    - #### setFileDecompressionTechnique

          public void setFileDecompressionTechnique​(InternationalString newValue)

      Sets recommendations of algorithms or processes that can be applied to read or expand resources to which compression techniques have been applied.
      Parameters:
        `newValue` - the new file decompression technique.

    - #### getMedia

          @UML(identifier="medium",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public Collection<Medium> getMedia()

      Returns the media used by the format.
      Returns:
        media used by the format.
      Since:
        0.5

    - #### setMedia

          public void setMedia​(Collection<? extends Medium> newValues)

      Sets the media used by the format.
      Parameters:
        `newValues` - the new media.
      Since:
        0.5

    - #### getFormatDistributors

          public Collection<Distributor> getFormatDistributors()

      Provides information about the distributor's format.
      Specified by:
        `getFormatDistributors` in interface `Format`
      Returns:
        information about the distributor's format.

    - #### setFormatDistributors

          public void setFormatDistributors​(Collection<? extends Distributor> newValues)

      Sets information about the distributor's format.
      Parameters:
        `newValues` - the new format distributors.