Class DefinitionURI

java.lang.Object
org.apache.sis.internal.util.DefinitionURI

public final class DefinitionURI extends Object
Utility methods for parsing OGC's URI (URN or URL) in the "urn:ogc:def" namespace.

For example, all the following URIs are for the same object:

  • "EPSG:4326" (older format)
  • "EPSG::4326" (often seen for similarity with URN below)
  • "urn:ogc:def:crs:EPSG::4326" (version number is omitted)
  • "urn:ogc:def:crs:EPSG:8.2:4326" (explicit version number, here 8.2)
  • "urn:x-ogc:def:crs:EPSG::4326" (prior registration of "ogc" to IANA)
  • "http://www.opengis.net/def/crs/EPSG/0/4326"
  • "http://www.opengis.net/gml/srs/epsg.xml#4326"
This class does not attempt to decode URL characters. For example, a URL for "m/s" may be encoded as below, in which case the value in the code field will be "m%2Fs" instead of "m/s".
  • http://www.opengis.net/def/uom/SI/0/m%2Fs

Parts of URN

URN begins with "urn:ogc:def:" (formerly "urn:x-ogc:def:") followed by: The object type can be one of the following name. Mapping between those names and GeoAPI interfaces is provided by the NameMeaning class.
Recognized object types in URN
Object type Meaning
axis Coordinate system axe definition
axisDirection Axis direction code definition
coordinateOperation Coordinate operation definition
crs Coordinate reference system definition
cs Coordinate system definition
datum Datum definition
dataType Data type definition
derivedCRSType Derived CRS type code definition
documentType Document type definition
ellipsoid Ellipsoid definition
featureType Feature type definition
group Operation parameter group definition
meaning Parameter meaning definition
meridian Prime meridian definition
method Operation method definition
nil Explanations for missing information
parameter Operation parameter definition
phenomenon Observable property definition
pixelInCell Pixel in cell code definition
rangeMeaning Range meaning code definition
referenceSystem Value reference system definition
uom Unit of measure definition
verticalDatumType Vertical datum type code definition
Some example of authorities are:
Authority examples
Authority Purpose
"OGC" Objects defined by the Open Geospatial Consortium.
"EPSG" Referencing objects defined in the EPSG database.
"EDCS" Environmental Data Coding Specification.
"SI" International System of Units.
"UCUM" Unified Code for Units of Measure.

Combined URNs

This implementation does not handle combined URNs. An example of combined URN would be "urn:ogc:def:crs,crs:EPSG:6.3:27700,crs:EPSG:6.3:5701".
Since:
0.4
Version:
1.3
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    The authority part of a URI, or null if none (empty).
    The code part of a URI, or null if none (empty).
    static final char
    The separator between components in a URN.
    private static final char
    The separator between a URL and its first components.
    private static final char
    The separator between components in a URL after the first component.
    If the URI contains sub-components, those sub-components.
    static final String
    The domain of URLs in the OGC namespace.
    boolean
    true if the URI is a "http://www.opengis.net/gml/…" URL.
    boolean
    true if the URI is a "http://www.opengis.net/…" URL, or false if the URI is a "urn:ogc:def:…" URN.
    private static final char
    Separator between keys and values in the query part of a URL.
    static final String
    A version number to be considered as if no version were provided.
    The parameters, or null if none.
    private static final Map<String,String>
    Server and path portions of HTTP URL for various types (currently "crs").
    static final String
    The "urn:ogc:def" prefix used in all URN supported by this class.
    static final char
    The path separator in URN.
    The type part of a URI, or null if none (empty).
    The version part of a URI, or null if none (empty).
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    For parse(String) usage only.
  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    appendStringTo(StringBuilder buffer, char separator)
    Formats the string representation of this URI into the given buffer.
    private static String
    codeForGML(String type, String authority, String url, int lower, DefinitionURI result)
    Implementation of URI parser for the HTTP forms in GML namespace.
    static String
    codeOf(String type, String authority, CharSequence uri)
    Returns the code part of the given URI, provided that it matches the given object type and authority.
    Attempts to parse the given URI, which may either a URN or URL.
    private static DefinitionURI
    parse(String uri, boolean prefixIsOptional, int upper, int stopAt)
    Parses a sub-region of the given URI.
    static boolean
    regionMatches(String part, String urn, int lower, int upper)
    Returns true if a sub-region of urn matches the given part, ignoring case, leading and trailing whitespaces.
    private static int
    skipIdentifierPart(String text, int i)
    Returns the index after the last identifier character.
    private static int
    splitKeyValue(String uri, int lower, int upper)
    Returns the index of the '=' character in the given sub-string, provided that all characters before it are spaces or decimal digits.
    Returns a string representation of this URI.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • PREFIX

      public static final String PREFIX
      The "urn:ogc:def" prefix used in all URN supported by this class.
      See Also:
    • SEPARATOR

      public static final char SEPARATOR
      The path separator in URN.
      See Also:
    • COMPONENT_SEPARATOR

      public static final char COMPONENT_SEPARATOR
      The separator between components in a URN.
      Example: in "urn:ogc:def:crs,crs:EPSG:9.1:27700,crs:EPSG:9.1:5701", the components are "crs:EPSG:9.1:27700" and "crs:EPSG:9.1:5701".
      See Also:
    • COMPONENT_SEPARATOR_1

      private static final char COMPONENT_SEPARATOR_1
      The separator between a URL and its first components. In URL syntax, this is the separator between URL path and the query.
      Example: http://www.opengis.net/def/crs-compound?1=…&2=…
      See Also:
    • COMPONENT_SEPARATOR_2

      private static final char COMPONENT_SEPARATOR_2
      The separator between components in a URL after the first component.
      Example: http://www.opengis.net/def/crs-compound?1=…&2=…
      See Also:
    • KEY_VALUE_SEPARATOR

      private static final char KEY_VALUE_SEPARATOR
      Separator between keys and values in the query part of a URL.
      Example: http://www.opengis.net/def/crs-compound?1=…&2=
      See Also:
    • DOMAIN

      public static final String DOMAIN
      The domain of URLs in the OGC namespace.
      See Also:
    • PATHS

      private static final Map<String,String> PATHS
      Server and path portions of HTTP URL for various types (currently "crs"). For each URL, value starts after the protocol part and finishes before the authority filename.

      As of Apache SIS 0.4, this map has a single entry. However, more entries may be added in future SIS versions. If new entries are added, then see the TODO comment in the codeForGML(String, String, String, int, DefinitionURI) method.

    • NO_VERSION

      public static final String NO_VERSION
      A version number to be considered as if no version were provided. This value is part of OGC specification (not a SIS-specific hack).
      See Also:
    • isHTTP

      public boolean isHTTP
      true if the URI is a "http://www.opengis.net/…" URL, or false if the URI is a "urn:ogc:def:…" URN.
    • isGML

      public boolean isGML
      true if the URI is a "http://www.opengis.net/gml/…" URL. A value of true should imply that isHTTP is also true.
    • type

      public String type
      The type part of a URI, or null if none (empty). Note that the set of valid types in OGC namespace is restricted. See class javadoc for more information.
      Example: In the "urn:ogc:def:crs:EPSG:8.2:4326" URN, this is "crs".
      See Also:
    • authority

      public String authority
      The authority part of a URI, or null if none (empty). Note that the set of valid authorities in OGC namespace is restricted. See class javadoc for more information.
      Example: In the "urn:ogc:def:crs:EPSG:8.2:4326" URN, this is "EPSG".
    • version

      public String version
      The version part of a URI, or null if none (empty). This field is null if the version in the parsed string was "0".
      Example: In the "urn:ogc:def:crs:EPSG:8.2:4326" URN, this is "8.2".
    • code

      public String code
      The code part of a URI, or null if none (empty).
      Example: In the "urn:ogc:def:crs:EPSG:8.2:4326" URN, this is "4326".
    • parameters

      public String[] parameters
      The parameters, or null if none.
      Example: In the "urn:ogc:def:crs:OGC:1.3:AUTO42003:1:-100:45" URN, this is {"1", "-100", "45"}}.
    • components

      public DefinitionURI[] components
      If the URI contains sub-components, those sub-components. Otherwise null.
      URN example: if the URI is "urn:ogc:def:crs,crs:EPSG:9.1:27700,crs:EPSG:9.1:5701", then this DefinitionURI will contain the "urn:ogc:def:crs" header with two components:
      1. "urn:ogc:def:crs:EPSG:9.1:27700"
      2. "urn:ogc:def:crs:EPSG:9.1:5701"
      HTTP example: if the URI is "http://www.opengis.net/def/crs-compound?1=(…)/crs/EPSG/9.1/27700&2=(…)/crs/EPSG/9.1/5701", then this DefinitionURI will contain the "http://www.opengis.net/def/crs-compound" header with two components:
      1. "http://http://www.opengis.net/def/crs/EPSG/9.1/27700"
      2. "http://http://www.opengis.net/def/crs/EPSG/9.1/5701"
      Note that this array may contain null elements if we failed to parse the corresponding component.
  • Constructor Details

    • DefinitionURI

      private DefinitionURI()
      For parse(String) usage only.
  • Method Details

    • parse

      public static DefinitionURI parse(String uri)
      Attempts to parse the given URI, which may either a URN or URL. If this method does not recognize the given URI, then it returns null. If the given URI is incomplete, then the code value will be null.
      Parameters:
      uri - the URI to parse.
      Returns:
      the parse result, or null if the given URI is not recognized.
    • parse

      private static DefinitionURI parse(String uri, boolean prefixIsOptional, int upper, int stopAt)
      Parses a sub-region of the given URI. This method can start parsing for an arbitrary URI part, no necessarily the root. The first URI part is identified by an ordinal number: This method may invoke itself recursively if the URI contains sub-components.
      Parameters:
      uri - the URI to parse.
      prefixIsOptional - true if "urn:ogc:def" may not be present.
      upper - upper index of the previous URI part, or -1 if none.
      stopAt - index (exclusive) where to stop parsing.
      Returns:
      the parse result, or null if the URI is not recognized.
    • regionMatches

      public static boolean regionMatches(String part, String urn, int lower, int upper)
      Returns true if a sub-region of urn matches the given part, ignoring case, leading and trailing whitespaces.
      Parameters:
      part - the expected part ("urn", "ogc", "def", etc.)
      urn - the URN for which to test a subregion.
      lower - index of the first character in urn to compare, after skipping whitespaces.
      upper - index after the last character in urn to compare, ignoring whitespaces.
      Returns:
      true if the given sub-region of urn match the given part.
    • splitKeyValue

      private static int splitKeyValue(String uri, int lower, int upper)
      Returns the index of the '=' character in the given sub-string, provided that all characters before it are spaces or decimal digits. Returns -1 if the key-value separator character is not found. Note that a positive return value does not guarantee that the number is parsable.
    • codeOf

      public static String codeOf(String type, String authority, CharSequence uri)
      Returns the code part of the given URI, provided that it matches the given object type and authority. This method is useful when:
      • the URI is expected to have a specific object type and authority;
      • the version number is considered irrelevant;
      • the code is expected to have no parameters.
      This method accepts the following URI representations:
      • The given authority followed by the code (e.g. "EPSG:4326").
      • The URN form (e.g. "urn:ogc:def:crs:EPSG::4326"), ignoring version number. This method accepts also the former "x-ogc" in place of "ogc".
      • The HTTP form (e.g. "http://www.opengis.net/def/crs/EPSG/0/4326").
      • The GML form (e.g. "http://www.opengis.net/gml/srs/epsg.xml#4326").
      Parameters:
      type - the expected object type (e.g. "crs") in lower cases. See class javadoc for a list of types.
      authority - the expected authority, typically "EPSG". See class javadoc for a list of authorities.
      uri - the URI to parse.
      Returns:
      the code part of the given URI, or null if the codespace does not match the given type and authority, the code is empty, or the code is followed by parameters.
    • codeForGML

      private static String codeForGML(String type, String authority, String url, int lower, DefinitionURI result)
      Implementation of URI parser for the HTTP forms in GML namespace. The current implementation recognizes the following types:
      • crs for Coordinate Reference System objects (example: "http://www.opengis.net/gml/srs/epsg.xml#4326")
      Parameters:
      type - the expected type in lower cases, or null for any.
      authority - the expected authority, or null for any.
      url - the URL to parse.
      result - if non-null, store the type, authority and code in that object.
    • skipIdentifierPart

      private static int skipIdentifierPart(String text, int i)
      Returns the index after the last identifier character.
    • toString

      public String toString()
      Returns a string representation of this URI. If the URI were originally a GML's URL, then this method formats the URI in the "http://www.opengis.net/gml/srs/" namespace. Otherwise the URI were originally a URL, then this method formats the URI in the "http://www.opengis.net/" namespace. Otherwise this method formats the URI as a URN.
      Overrides:
      toString in class Object
      Returns:
      the string representation of this URI.
    • appendStringTo

      private void appendStringTo(StringBuilder buffer, char separator)
      Formats the string representation of this URI into the given buffer. This method invoke itself recursively if this URI has components. The "urn:ogc:def" must be appended by the caller, if applicable.
      Parameters:
      buffer - where to format the string representation.
      separator - first separator to append. Ignored if the URI is actually a URL.