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

  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, collectionType, copyCollection, copyList, copyMap, copySet, deepCopy, nonNullCollection, nonNullList, nonNullMap, nonNullSet, singleton, state, 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 Details

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

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