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:

an object type
an authority
an optional version number (often omitted)
the code
an arbitrary number of parameters

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

String

authority

The authority part of a URI, or null if none (empty).

String

code

The code part of a URI, or null if none (empty).

static final char

COMPONENT_SEPARATOR

The separator between components in a URN.

private static final char

COMPONENT_SEPARATOR_1

The separator between a URL and its first components.

private static final char

COMPONENT_SEPARATOR_2

The separator between components in a URL after the first component.

DefinitionURI[]

components

If the URI contains sub-components, those sub-components.

static final String

DOMAIN

The domain of URLs in the OGC namespace.

boolean

isGML

true if the URI is a "http://www.opengis.net/gml/…" URL.

boolean

isHTTP

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

KEY_VALUE_SEPARATOR

Separator between keys and values in the query part of a URL.

static final String

NO_VERSION

A version number to be considered as if no version were provided.

String[]

parameters

The parameters, or null if none.

private static final Map<String,String>

PATHS

Server and path portions of HTTP URL for various types (currently "crs").

static final String

PREFIX

The "urn:ogc:def" prefix used in all URN supported by this class.

static final char

SEPARATOR

The path separator in URN.

String

type

The type part of a URI, or null if none (empty).

String

version

The version part of a URI, or null if none (empty).
Constructor Summary

Constructors

Modifier

Constructor

Description

private

DefinitionURI()

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.

static DefinitionURI

parse(String uri)

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.

String

toString()

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:
  
  Constant Field Values
- SEPARATOR
  
  public static final char SEPARATOR
  
  The path separator in URN.
  See Also:
  
  Constant Field Values
- 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:
  
  Constant Field Values
- 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:
  
  Constant Field Values
- 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:
  
  Constant Field Values
- 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:
  
  Constant Field Values
- DOMAIN
  
  public static final String DOMAIN
  
  The domain of URLs in the OGC namespace.
  See Also:
  
  Constant Field Values
- 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:
  
  Constant Field Values
- 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:
  
  NameMeaning.toObjectType(Class)
- 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:
  
  "urn:ogc:def:crs:EPSG:9.1:27700"
  
  "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:
  
  "http://http://www.opengis.net/def/crs/EPSG/9.1/27700"
  
  "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.

Class DefinitionURI

Parts of URN

Combined URNs

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

PREFIX

SEPARATOR

COMPONENT_SEPARATOR

COMPONENT_SEPARATOR_1

COMPONENT_SEPARATOR_2

KEY_VALUE_SEPARATOR

DOMAIN

PATHS

NO_VERSION

isHTTP

isGML

type

authority

version

code

parameters

components

Constructor Details

DefinitionURI

Method Details

parse

parse

regionMatches

splitKeyValue

codeOf

codeForGML

skipIdentifierPart

toString

appendStringTo