Package org.apache.sis.metadata.iso.identification

## Class DefaultDataIdentification

- Object
- - AbstractMetadata
  - - ModifiableMetadata
    - - ISOMetadata
      - - AbstractIdentification
        - - DefaultDataIdentification

- All Implemented Interfaces:
    `Serializable`, `Emptiable`, `LenientComparable`, `IdentifiedObject`, `DataIdentification`, `Identification`

      public class DefaultDataIdentification
      extends AbstractIdentification
      implements DataIdentification

  Information required to identify a dataset. The following properties are mandatory or conditional (i.e. mandatory under some circumstances) in a well-formed metadata according ISO 19115:
  `MD_DataIdentification` `├─citation………………………………………` Citation data for the resource(s). `│ ├─title……………………………………` Name by which the cited resource is known. `│ └─date………………………………………` Reference date for the cited resource. `├─abstract………………………………………` Brief narrative summary of the content of the resource(s). `├─language………………………………………` Language(s) used within the dataset. `├─characterSet……………………………` Full name of the character coding standard(s) used for the dataset. `├─topicCategory…………………………` Main theme(s) of the dataset. `└─extent……………………………………………` Bounding polygon, vertical, and temporal extent of the dataset. `├─description……………………` The spatial and temporal extent for the referring object. `├─geographicElement……` Geographic component of the extent of the referring object. `├─temporalElement…………` Temporal component of the extent of the referring object. `└─verticalElement…………` Vertical component of the extent of the referring object.

  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
    --- | ---
    `DefaultDataIdentification()` | Constructs an initially empty data identification.
    `DefaultDataIdentification​(Citation citation, CharSequence abstracts, Locale language, TopicCategory topicCategory)` | Creates a data identification initialized to the specified values.
    `DefaultDataIdentification​(DataIdentification 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 DefaultDataIdentification` | `castOrCopy​(DataIdentification object)` | Returns a SIS metadata implementation with the values of the given arbitrary implementation.
    `Collection<CharacterSet>` | `getCharacterSets()` | Deprecated. Replaced by `getLocalesAndCharsets()​.values()`.
    `InternationalString` | `getEnvironmentDescription()` | Returns a description of the resource in the producer's processing environment.
    `Collection<Locale>` | `getLanguages()` | Deprecated. Replaced by `getLocalesAndCharsets()​.keySet()`.
    `Map<Locale,​Charset>` | `getLocalesAndCharsets()` | Returns the language(s) and character set(s) used within the dataset.
    `InternationalString` | `getSupplementalInformation()` | Any other descriptive information about the resource.
    `void` | `setCharacterSets​(Collection<? extends CharacterSet> newValues)` | Deprecated. Replaced by putting values in `getLocalesAndCharsets()` map.
    `void` | `setEnvironmentDescription​(InternationalString newValue)` | Sets the description of the resource in the producers processing environment.
    `void` | `setLanguages​(Collection<? extends Locale> newValues)` | Deprecated. Replaced by putting keys in `getLocalesAndCharsets()` map.
    `void` | `setLocalesAndCharsets​(Map<? extends Locale,​? extends Charset> newValues)` | Sets the language(s) and character set(s) used within the dataset.
    `void` | `setSupplementalInformation​(InternationalString newValue)` | Sets any other descriptive information about the resource.

    - ### Methods inherited from class AbstractIdentification

      `castOrCopy, getAbstract, getAdditionalDocumentations, getAggregationInfo, getAssociatedResources, getCitation, getCredits, getDescriptiveKeywords, getExtents, getGraphicOverviews, getPointOfContacts, getProcessingLevel, getPurpose, getResourceConstraints, getResourceFormats, getResourceMaintenances, getResourceSpecificUsages, getSpatialRepresentationTypes, getSpatialResolutions, getStatus, getTopicCategories, setAbstract, setAdditionalDocumentations, setAggregationInfo, setAssociatedResources, setCitation, setCredits, setDescriptiveKeywords, setExtents, setGraphicOverviews, setPointOfContacts, setProcessingLevel, setPurpose, setResourceConstraints, setResourceFormats, setResourceMaintenances, setResourceSpecificUsages, setSpatialRepresentationTypes, setSpatialResolutions, setStatus, setTopicCategories`

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

    - ### Methods inherited from interface DataIdentification

      `getExtents, getSpatialRepresentationTypes, getSpatialResolutions, getTopicCategories`

    - ### Methods inherited from interface Identification

      `getAbstract, getAggregationInfo, getCitation, getCredits, getDescriptiveKeywords, getGraphicOverviews, getPointOfContacts, getPurpose, getResourceConstraints, getResourceFormats, getResourceMaintenances, getResourceSpecificUsages, getStatus`

- - ### Constructor Detail

    - #### DefaultDataIdentification

          public DefaultDataIdentification()

      Constructs an initially empty data identification.

    - #### DefaultDataIdentification

          public DefaultDataIdentification​(Citation citation,
                                           CharSequence abstracts,
                                           Locale language,
                                           TopicCategory topicCategory)

      Creates a data identification initialized to the specified values.
      Parameters:
        `citation` - the citation data for the resource(s), or `null` if none.
        `abstracts` - a brief narrative summary of the content of the resource(s), or `null` if none.
        `language` - the language used within the dataset, or `null` if none.
        `topicCategory` - the main theme of the dataset, or `null` if none.

    - #### DefaultDataIdentification

          public DefaultDataIdentification​(DataIdentification 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(DataIdentification)`

  - ### Method Detail

    - #### castOrCopy

          public static DefaultDataIdentification castOrCopy​(DataIdentification 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 `DefaultDataIdentification`, then it is returned unchanged.
      - Otherwise a new `DefaultDataIdentification` 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.

    - #### getLocalesAndCharsets

          @UML(identifier="defaultLocale+otherLocale",
               obligation=CONDITIONAL,
               specification=ISO_19115)
          public Map<Locale,​Charset> getLocalesAndCharsets()

      Returns the language(s) and character set(s) used within the dataset. The first element in iteration order is the default language. All other elements, if any, are alternate language(s) used within the resource.
      Returns:
        language(s) and character set(s) used within the dataset.
      Since:
        1.0

    - #### setLocalesAndCharsets

          public void setLocalesAndCharsets​(Map<? extends Locale,​? extends Charset> newValues)

      Sets the language(s) and character set(s) used within the dataset. The first element in iteration order should be the default language. All other elements, if any, are alternate language(s) used within the resource.
      Parameters:
        `newValues` - the new language(s) and character set(s) used within the dataset.
      Since:
        1.0

    - #### getLanguages

          @Deprecated
          public Collection<Locale> getLanguages()

      Deprecated.
      Replaced by `getLocalesAndCharsets()​.keySet()`.
      Returns the language(s) used within the resource. The first element in iteration order shall be the default language. All other elements, if any, are alternate language(s) used within the resource.

      The language string representations should use ISO 639-2 language code as returned by `Locale​.getISO3Language()`.

      Specified by:
        `getLanguages` in interface `DataIdentification`
      Returns:
        language(s) used.

    - #### setLanguages

          @Deprecated
          public void setLanguages​(Collection<? extends Locale> newValues)

      Deprecated.
      Replaced by putting keys in `getLocalesAndCharsets()` map.
      Sets the language(s) used within the resource.
      Parameters:
        `newValues` - the new languages.

    - #### getCharacterSets

          @Deprecated
          public Collection<CharacterSet> getCharacterSets()

      Deprecated.
      Replaced by `getLocalesAndCharsets()​.values()`.
      Returns the character coding standard used for the dataset.
      Upcoming API change — JDK integration
      The element type may change to the `Charset` class in GeoAPI 4.0.
      Specified by:
        `getCharacterSets` in interface `DataIdentification`
      Returns:
        character coding standard(s) used.

    - #### setCharacterSets

          @Deprecated
          public void setCharacterSets​(Collection<? extends CharacterSet> newValues)

      Deprecated.
      Replaced by putting values in `getLocalesAndCharsets()` map.
      Sets the character coding standard used for the dataset.
      Upcoming API change — JDK integration
      The element type may change to the `Charset` class in GeoAPI 4.0.
      Parameters:
        `newValues` - the new character sets.

    - #### getEnvironmentDescription

          public InternationalString getEnvironmentDescription()

      Returns a description of the resource in the producer's processing environment. This includes items such as the software, the computer operating system, file name, and the dataset size.
      Specified by:
        `getEnvironmentDescription` in interface `DataIdentification`
      Returns:
        description of the resource in the producer's processing environment, or `null`.

    - #### setEnvironmentDescription

          public void setEnvironmentDescription​(InternationalString newValue)

      Sets the description of the resource in the producers processing environment.
      Parameters:
        `newValue` - the new environment description.

    - #### getSupplementalInformation

          public InternationalString getSupplementalInformation()

      Any other descriptive information about the resource.
      Specified by:
        `getSupplementalInformation` in interface `DataIdentification`
      Returns:
        other descriptive information, or `null`.

    - #### setSupplementalInformation

          public void setSupplementalInformation​(InternationalString newValue)

      Sets any other descriptive information about the resource.
      Parameters:
        `newValue` - the new supplemental information.