Package org.apache.sis.metadata.iso.citation

## Class Citations

- Object
- - Static
  - - Citations

-     public final class Citations
      extends Static

  A set of pre-defined constants and static methods working on citations. This class provides two kinds of `Citation` constants:
  - Instances of `Citation` are references mostly for human reading.
  - Instances of `IdentifierSpace` provide the code spaces for identifiers (most often Coordinate Reference System identifiers) together with information about who maintains those identifiers.
  Example: `"EPSG:4326"` is a widely-used identifier for the “World Geodetic System (WGS) 1984” Coordinate Reference System (CRS). The `"4326"` part is the identifier code and the `"EPSG"` part is the identifier code space. The meaning of codes in that code space is controlled by an authority, the “EPSG Geodetic Parameter Dataset”. The cited responsible party for the EPSG dataset is the “International Association of Oil & Gas producers” (IOGP).
  The constants defined in this class are typically values returned by:
  - `DefaultCitation​.getIdentifiers()` for the `ISBN` and `ISSN` constants.
  - `ImmutableIdentifier​.getAuthority()` for other `IdentifierSpace` constants.
  - `DefaultMetadata​.getMetadataStandards()` for other `Citation` constants.
  The static methods defined in this class are for:
  - Inferring an identifier from a citation (this is useful mostly with `IdentifierSpace` instances).
  - Determining if two instances can be considered the same `Citation` by comparing their titles or their identifiers.
  Since:
    0.3

  Defined in the `sis-metadata` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static IdentifierSpace<Integer>` | `EPSG` | The authority for identifiers of objects defined by the EPSG Geodetic Parameter Dataset.
    `static IdentifierSpace<String>` | `ESRI` | The authority for identifiers of objects defined by ESRI.
    `static IdentifierSpace<Integer>` | `GEOTIFF` | The authority for identifiers of objects defined by the the GeoTIFF specification.
    `static IdentifierSpace<String>` | `ISBN` | The International Standard Book Number (ISBN) defined by ISO-2108.
    `static List<Citation>` | `ISO_19115` | The Geographic Information — Metadata standards defined by ISO 19115.
    `static IdentifierSpace<String>` | `ISSN` | The International Standard Serial Number (ISSN) defined by ISO-3297.
    `static IdentifierSpace<Integer>` | `MAP_INFO` | The authority for identifiers of objects defined by MapInfo.
    `static IdentifierSpace<String>` | `NETCDF` | The authority for identifiers of objects defined by the NetCDF specification.
    `static IdentifierSpace<String>` | `OGC` | The authority for identifiers found in specifications from the Open Geospatial Consortium.
    `static IdentifierSpace<String>` | `PROJ4` | The authority for identifiers of objects defined by the Proj.4 project.
    `static IdentifierSpace<Integer>` | `S57` | The IHO transfer standard for digital hydrographic data specification.
    `static Citation` | `SIS` | The codespace of objects that are specific to the Apache SIS project.
    `static IdentifierSpace<Integer>` | `WMS` | The authority for identifiers of objects defined by the Web Map Service (WMS) specification.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static Citation` | `fromName​(String identifier)` | Returns a citation of the given identifier.
    `static String` | `getCodeSpace​(Citation citation)` | Deprecated. Renamed as `toCodeSpace(Citation)`.
    `static String` | `getIdentifier​(Citation citation)` | Infers an identifier from the given citation, or returns `null` if no identifier has been found.
    `static String` | `getUnicodeIdentifier​(Citation citation)` | Deprecated. Replaced by `toCodeSpace(Citation)` in order to reduce the risk of inconsistent behavior if those two methods are mixed.
    `static boolean` | `identifierMatches​(Citation citation, String identifier)` | Returns `true` if at least one identifier in the given citation have a code matching the given string.
    `static boolean` | `identifierMatches​(Citation c1, Citation c2)` | Returns `true` if at least one identifier code in `c1` is equal to an identifier code in `c2`.
    `static boolean` | `titleMatches​(Citation citation, String title)` | Returns `true` if the title or any alternate title in the given citation matches the given string.
    `static boolean` | `titleMatches​(Citation c1, Citation c2)` | Returns `true` if at least one title or alternate title in `c1` is leniently equal to a title or alternate title in `c2`.
    `static String` | `toCodeSpace​(Citation citation)` | Infers a code space from the given citation, or returns `null` if none.
    `static Citation[]` | `values()` | Returns the values declared in this `Citations` class.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### ISO_19115

          public static final List<Citation> ISO_19115

      The Geographic Information — Metadata standards defined by ISO 19115. This list contains two standards published by the International Organization for Standardization:
      - ISO 19115-1 Geographic Information — Metadata Part 1: Fundamentals
      - ISO 19115-2 Geographic Information — Metadata Part 2: Extensions for imagery and gridded data
      Apache SIS always uses those standards together (actually the SIS's API is a merge of those two standards, providing for example a unified view of `MI_Band` and `MD_Band`). This is why those standards are defined in a collection rather than as separated constants.
      Content and future evolution
      The content of this list may vary in future Apache SIS versions depending on the evolution of standards and in the way that SIS support them. The current content is:
      - ISO 19115-1:2014 at index 0.
      - ISO 19115-2:2019 at index 1.
      Main usage
      This value can be returned by:
      - `DefaultMetadata​.getMetadataStandards()`
      Since:
        0.6

    - #### EPSG

          public static final IdentifierSpace<Integer> EPSG

      The authority for identifiers of objects defined by the EPSG Geodetic Parameter Dataset. EPSG is not an organization by itself, but is the identifier space managed by the International Association of Oil & Gas producers (IOGP) organization for Coordinate Reference System identifiers. EPSG is the default namespace of map projection method and parameter names in Apache SIS.
      Historical note: The EPSG acronym meaning was “European Petroleum Survey Group”. But this meaning does not apply anymore since the European and American associations merged into the “Association of Oil & Gas producers” (OGP), later renamed as IOGP. The legacy acronym now applies only to the database Coordinate Reference System definitions, known as “EPSG Geodetic Parameter Dataset”.
      The citation responsible party is the IOGP organization, but the namespace is `"EPSG"`.
      When to use "EPSG" and "IOGP"
      For all usages except GML, the `"EPSG"` namespace shall be used for identifying Coordinate Reference System objects. But in the particular case of GML, both `"EPSG"` and `"IOGP"` appear in different locations. For example:

      >     <gml:identifier codeSpace="IOGP">urn:ogc:def:crs:EPSG::4326</gml:identifier>

      Guidelines:
      - The `"EPSG"` name shall be used in URN. This part of the URN is called "the authority" and is returned by both `Identifier​.getAuthority()` and `Identifier​.getCodeSpace()`.
      - The `"IOGP"` name appears in the GML `codeSpace` attribute, but despite the attribute name this is not the `Identifier​.getCodeSpace()` value of the `"EPSG:4326"` identifier. Instead, Apache SIS considers `"IOGP"` as the codespace of the `"IOGP:EPSG"` identifier, which is the identifier of this citation.
      In other words, Apache SIS considers "IOGP" as the codespace of the "EPSG" codespace, but there is usually no need to go to such depth in identifier hierarchy except when handling GML documents. For this reason, the `"IOGP:EPSG"` identifier is handled in a special way by `getIdentifier(Citation)`, which return only `"EPSG"`.
      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      - `ConcurrentAuthorityFactory​.getAuthority()` with the addition of version information.
      Since:
        0.4

    - #### WMS

          public static final IdentifierSpace<Integer> WMS

      The authority for identifiers of objects defined by the Web Map Service (WMS) specification. The WMS 1.3 specifications is also known as ISO 19128 Geographic Information — Web map server interface standard.

      The citation responsible parties are the OGC and ISO organizations. The namespace declared by this constant is `"OGC"`, but the `"CRS"`, `"AUTO"` and `"AUTO2"` namespaces are also commonly found in practice.

      Main usage
      This value can be returned by:
      - `CommonAuthorityFactory​.getAuthority()`
      Since:
        0.7

    - #### OGC

          public static final IdentifierSpace<String> OGC

      The authority for identifiers found in specifications from the Open Geospatial Consortium. The name of this identifier space is fixed to `"OGC"`. Apache SIS uses this authority mostly for map projection methods and parameters as they were defined in older OGC specifications (in more recent specifications, EPSG identifiers tend to be more widely used).
      Example the Mercator projection can be defined by an operation method having the `"OGC:Mercator_1SP"` identifier and the following parameters:

      Example of identifiers in OGC name space
      Name in OGC namespace | Name in default namespace (EPSG)
      --- | ---
      `"OGC:semi_major"` |
      `"OGC:semi_minor"` |
      `"OGC:latitude_of_origin"` | Latitude of natural origin
      `"OGC:central_meridian"` | Longitude of natural origin
      `"OGC:scale_factor"` | Scale factor at natural origin
      `"OGC:false_easting"` | False easting
      `"OGC:false_northing"` | False northing

      Specifications referenced
      The specification actually referenced by this citation is implementation dependent and may change in future SIS version. Some of the specifications used are:
      - Coordinate Transformation Service
      - Web Map Service
      - Definition identifier URNs in OGC namespace
      We do not commit to a particular OGC specification in order to keep the flexibility to change the title or URL according newer OGC publications.
      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      See Also:
        `EPSG`, `ESRI`

    - #### ESRI

          public static final IdentifierSpace<String> ESRI

      The authority for identifiers of objects defined by ESRI. The name of this identifier space is fixed to `"ESRI"`. This citation is used as the authority for many map projection method and parameter names other than the EPSG ones.
      Note many parameter names defined by OGC are very similar to the ESRI ones, except for the case. Examples:

      Example of identifiers in ESRI name space
      Name in ESRI namespace | Name in OGC namespace
      --- | ---
      `"ESRI:Semi_Major"` | `"OGC:semi_major"`
      `"ESRI:Semi_Minor"` | `"OGC:semi_minor"`
      `"ESRI:Latitude_Of_Origin"` | `"OGC:latitude_of_origin"`
      `"ESRI:Central_Meridian"` | `"OGC:central_meridian"`
      `"ESRI:Scale_Factor"` | `"OGC:scale_factor"`
      `"ESRI:False_Easting"` | `"OGC:false_easting"`
      `"ESRI:False_Northing"` | `"OGC:false_northing"`

      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      Since:
        0.4
      See Also:
        `OGC`, `EPSG`

    - #### NETCDF

          public static final IdentifierSpace<String> NETCDF

      The authority for identifiers of objects defined by the NetCDF specification. The name of this identifier space is fixed to `"NetCDF"`. This citation is used as the authority for some map projection method and parameter names as used in netCDF files.
      Example the Mercator projection can be defined in a netCDF file with the following parameters:

      Example of identifiers in netCDF name space
      Name in netCDF namespace | Name in default namespace (EPSG)
      --- | ---
      `"NetCDF:semi_major_axis"` |
      `"NetCDF:semi_minor_axis"` |
      `"NetCDF:latitude_of_projection_origin"` | Latitude of natural origin
      `"NetCDF:longitude_of_projection_origin"` | Longitude of natural origin
      `"NetCDF:scale_factor_at_projection_origin"` | Scale factor at natural origin
      `"NetCDF:false_easting"` | False easting
      `"NetCDF:false_northing"` | False northing

      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      Since:
        0.4

    - #### GEOTIFF

          public static final IdentifierSpace<Integer> GEOTIFF

      The authority for identifiers of objects defined by the the GeoTIFF specification. This specification identifies some map projections by their own numerical codes.
      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      Since:
        0.4

    - #### PROJ4

          public static final IdentifierSpace<String> PROJ4

      The authority for identifiers of objects defined by the Proj.4 project.
      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      Since:
        0.4

    - #### MAP_INFO

          public static final IdentifierSpace<Integer> MAP_INFO

      The authority for identifiers of objects defined by MapInfo.
      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      Since:
        0.6

    - #### S57

          public static final IdentifierSpace<Integer> S57

      The IHO transfer standard for digital hydrographic data specification.
      Main usage
      This value can be returned by:
      - `ImmutableIdentifier​.getAuthority()`
      Since:
        0.6

    - #### ISBN

          public static final IdentifierSpace<String> ISBN

      The International Standard Book Number (ISBN) defined by ISO-2108. The ISO 19115 metadata standard defines a specific attribute for this information, but the SIS library handles it like any other identifier.
      Main usage
      This value can be returned by:
      - `DefaultCitation​.getIdentifiers()`
      See Also:
        `DefaultCitation​.getISBN()`

    - #### ISSN

          public static final IdentifierSpace<String> ISSN

      The International Standard Serial Number (ISSN) defined by ISO-3297. The ISO 19115 metadata standard defines a specific attribute for this information, but the SIS library handles it like any other identifier.
      Main usage
      This value can be returned by:
      - `DefaultCitation​.getIdentifiers()`
      See Also:
        `DefaultCitation​.getISSN()`

    - #### SIS

          public static final Citation SIS

      The codespace of objects that are specific to the Apache SIS project.
      Main usage
      This value can be returned by:
      - `DefaultConformanceResult​.getSpecification()`
      Since:
        0.4

  - ### Method Detail

    - #### values

          public static Citation[] values()

      Returns the values declared in this `Citations` class.
      Returns:
        the value declared in this `Citations` class.
      Since:
        1.0

    - #### fromName

          public static Citation fromName​(String identifier)

      Returns a citation of the given identifier. The method makes the following choice:
      - If the given title is `null` or empty (ignoring spaces), then this method returns `null`.
      - Otherwise if the given string matches an identifier of one of the pre-defined constants (`EPSG`, `GEOTIFF`, etc.), then that constant is returned.
      - Otherwise, a new citation is created with the specified name as the title.
      Parameters:
        `identifier` - the citation title (or alternate title), or `null`.
      Returns:
        a citation using the specified name, or `null` if the given title is null or empty.

    - #### titleMatches

          public static boolean titleMatches​(Citation c1,
                                             Citation c2)

      Returns `true` if at least one title or alternate title in `c1` is leniently equal to a title or alternate title in `c2`. The comparison is case-insensitive and ignores every character which is not a letter or a digit. The titles ordering is not significant.
      Parameters:
        `c1` - the first citation to compare, or `null`.
        `c2` - the second citation to compare, or `null`.
      Returns:
        `true` if both arguments are non-null, and at least one title or alternate title matches.

    - #### titleMatches

          public static boolean titleMatches​(Citation citation,
                                             String title)

      Returns `true` if the title or any alternate title in the given citation matches the given string. The comparison is case-insensitive and ignores every character which is not a letter or a digit.
      Parameters:
        `citation` - the citation to check for, or `null`.
        `title` - the title or alternate title to compare, or `null`.
      Returns:
        `true` if both arguments are non-null, and the title or an alternate title matches the given string.

    - #### identifierMatches

          public static boolean identifierMatches​(Citation c1,
                                                  Citation c2)

      Returns `true` if at least one identifier code in `c1` is equal to an identifier code in `c2`. Code spaces are compared only if provided in the two identifiers being compared. Comparisons are case-insensitive and ignores every character which is not a letter or a digit. The identifier ordering is not significant.

      If (and only if) the citations do not contains any identifier, then this method fallback on titles comparison using the `titleMatches` method. This fallback exists for compatibility with client codes using the citation titles without identifiers.

      Parameters:
        `c1` - the first citation to compare, or `null`.
        `c2` - the second citation to compare, or `null`.
      Returns:
        `true` if both arguments are non-null, and at least one identifier matches.

    - #### identifierMatches

          public static boolean identifierMatches​(Citation citation,
                                                  String identifier)

      Returns `true` if at least one identifier in the given citation have a code matching the given string. The comparison is case-insensitive and ignores every character which is not a letter or a digit.

      If (and only if) the citation does not contain any identifier, then this method fallback on titles comparison using the `titleMatches` method. This fallback exists for compatibility with citations using title and alternate titles (often abbreviations) without identifiers.

      Parameters:
        `citation` - the citation to check for, or `null`.
        `identifier` - the identifier to compare, or `null`.
      Returns:
        `true` if both arguments are non-null, and an identifier matches the given string.

    - #### getIdentifier

          public static String getIdentifier​(Citation citation)

      Infers an identifier from the given citation, or returns `null` if no identifier has been found. This method is useful for extracting a short designation of an authority (e.g. `"EPSG"`) for display purpose. This method performs the following choices:
      - If the given citation is `null`, then this method returns `null`.
      - Otherwise if the collection of citation identifiers contains at least one non-deprecated identifier, then:
        - If the codespace (if any) and the code of at least one non-deprecated identifier are valid Unicode identifiers (with relaxed rules regarding the code), then the first of those identifiers is returned in a `"[codespace:]code"` format. If a codespace exists, then the above restriction about the code is relaxed in two ways:
          - The code is allowed to start with a Unicode identifier part (not necessarily start) since the codespace already provides the start character.
          - The code is allowed to contain some other characters (currently `'.'` and `'-'`) commonly found in identifiers in the codespace managed by various authorities.
        - Otherwise the first non-empty and non-deprecated identifier is returned in a `"[codespace:]code"` format, despite not being a valid Unicode identifier.
      - Otherwise if the citation contains at least one non-deprecated title or alternate title, then:
        - If at least one non-deprecated title is a unicode identifier, then the first of those titles is returned.
        - Otherwise the first non-empty and non-deprecated title is returned, despite not being a valid Unicode identifier.
      - Otherwise this method returns `null`.
      Note: This method searches in alternate titles as a fallback because ISO specification said that those titles are often used for abbreviations. However titles are never searched if the given citation contains at least one non-empty and non-deprecated identifier.
      This method ignores leading and trailing whitespaces in every character sequences. Null or empty trimmed character sequences are ignored. This method does not remove ignorable characters. The result is a string which is likely, but not guaranteed, to be a valid XML or Unicode identifier. The returned string is useful when an "identifier-like" string is desired for display or information purpose, but does not need to be a strictly valid identifier.
      Parameters:
        `citation` - the citation for which to get the identifier, or `null`.
      Returns:
        a non-empty identifier for the given citation without leading or trailing whitespaces, or `null` if the given citation is null or does not declare any identifier or title.

    - #### getUnicodeIdentifier

          @Deprecated
          public static String getUnicodeIdentifier​(Citation citation)

      Deprecated.
      Replaced by `toCodeSpace(Citation)` in order to reduce the risk of inconsistent behavior if those two methods are mixed.
      Infers a valid Unicode identifier from the given citation, or returns `null` if none.
      Parameters:
        `citation` - the citation for which to get the Unicode identifier, or `null`.
      Returns:
        a non-empty Unicode identifier for the given citation without leading or trailing whitespaces, or `null` if the given citation is null or does not have any Unicode identifier or title.
      Since:
        0.6
      See Also:
        `ImmutableIdentifier`, `IdentifiedObjects​.getSimpleNameOrIdentifier(IdentifiedObject)`, `CharSequences​.isUnicodeIdentifier(CharSequence)`

    - #### toCodeSpace

          public static String toCodeSpace​(Citation citation)

      Infers a code space from the given citation, or returns `null` if none. This method is useful for extracting a short designation of an authority (e.g. `"EPSG"`) for processing purpose. This method performs the following actions:
      - If the given citation is an instance of `IdentifierSpace`, returns `IdentifierSpace​.getName()`.
      - Otherwise, performs the same work than `getIdentifier(Citation)` except that `'_'` is used instead of `':'` as the separator between the codespace and the code.
      - If the result of above method call is `null` or is not a valid Unicode identifier, then return `null`.
      - Otherwise remove the ignorable characters, if any, and returns the result.
      Note: examples of ignorable identifier characters are zero width space or word joiner. Those characters are illegal in XML identifiers, and should therfore be removed if the Unicode identifier may also be used as XML identifier.
      If non-null, the result is suitable for use as a XML identifier except for a few uncommon characters.
      Note: the following characters are invalid in XML identifiers. However since they are valid in Unicode identifiers, they could be included in the string returned by this method:
      - `µ`
      - `ª` (feminine ordinal indicator)
      - `º` (masculine ordinal indicator)
      - `⁔`
      Parameters:
        `citation` - the citation for which to infer the code space, or `null`.
      Returns:
        a non-empty code space for the given citation without leading or trailing whitespaces, or `null` if the given citation is null or does not have any Unicode identifier or title.
      Since:
        1.0

    - #### getCodeSpace

          @Deprecated
          public static String getCodeSpace​(Citation citation)

      Deprecated.
      Renamed as `toCodeSpace(Citation)`. The previous name was confusing because this method does not return the namespace of the given citation, but instead represents it as a namespace.
      Since:
        0.8