org.geotoolkit.metadata.iso.citation.Citations Maven / Gradle / Ivy
Show all versions of geotk-metadata Show documentation
/*
* Geotoolkit.org - An Open Source Java GIS Toolkit
* http://www.geotoolkit.org
*
* (C) 2005-2011, Open Source Geospatial Foundation (OSGeo)
* (C) 2009-2011, Geomatys
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* This package contains documentation from OpenGIS specifications.
* OpenGIS consortium's work is fully acknowledged here.
*/
package org.geotoolkit.metadata.iso.citation;
import org.opengis.metadata.citation.Role;
import org.opengis.metadata.citation.Citation;
import org.opengis.metadata.citation.OnLineFunction;
import org.opengis.metadata.citation.PresentationForm;
import org.geotoolkit.lang.Static;
import org.geotoolkit.resources.Vocabulary;
import org.geotoolkit.util.ArgumentChecks;
import org.geotoolkit.util.SimpleInternationalString;
import org.geotoolkit.metadata.iso.DefaultIdentifier;
import static java.util.Arrays.asList;
import static java.util.Collections.singleton;
/**
* A set of pre-defined constants and static methods working on {@linkplain Citation citations}.
* Pre-defined metadata constants are usually declared in implementation classes like
* {@link DefaultResponsibleParty}. But citations are an exception since they are extensively
* referenced in the Geotk library, and handling citations requires some convenience methods.
* They are factored out in this {@code Citations} class for clarity.
*
* Citations may be about an organization (e.g. {@linkplain #OPEN_GIS OpenGIS}),
* a specification (e.g. {@linkplain #WMS}) or an authority that
* maintains definitions of codes (e.g. {@linkplain #EPSG}). In the later case, the citation
* contains an {@linkplain Citation#getIdentifiers identifier} which is the namespace of the
* codes maintained by the authority. For example the identifier for the {@link #EPSG} citation
* is {@code "EPSG"}, and EPSG codes look like {@code "EPSG:4326"}.
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Jody Garnett (Refractions)
* @version 3.18
*
* @since 2.2
* @module
*/
public final class Citations extends Static {
/**
* Do not allows instantiation of this class.
*/
private Citations() {
}
///////////////////////////////////////////////////////////////////////
//////// ////////
//////// O R G A N I S A T I O N S ////////
//////// ////////
///////////////////////////////////////////////////////////////////////
/**
* The Open Geospatial consortium organisation.
* "Open Geospatial consortium" is the new name for "OpenGIS consortium".
* An {@linkplain Citation#getAlternateTitles alternate title} for this citation is "OGC"
* (according ISO 19115, alternate titles often contain abbreviations).
*
* @see DefaultResponsibleParty#OGC
* @see #OPEN_GIS
* @category Organisation
*/
public static final Citation OGC;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.OGC, "OGC");
c.setIdentifier("OGC");
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL);
c.freeze();
OGC = c;
// NOTE: Most OGC properties will be copied into OPEN_GIS as well.
}
/**
* The OpenGIS consortium organisation.
* "OpenGIS consortium" is the old name for "Open Geospatial consortium".
* {@linkplain Citation#getAlternateTitles Alternate titles} for this citation are
* "OpenGIS" and "OGC" (according ISO 19115, alternate titles often contain abbreviations).
*
* @see DefaultResponsibleParty#OPEN_GIS
* @see #OGC
* @category Organisation
*/
public static final Citation OPEN_GIS;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.OPEN_GIS, "OPEN_GIS");
c.setPresentationForms(OGC.getPresentationForms());
c.setAlternateTitles (OGC.getAlternateTitles());
c.setIdentifiers (OGC.getIdentifiers());
c.getIdentifiers().add(new DefaultIdentifier("OpenGIS"));
c.freeze();
OPEN_GIS = c;
}
/**
* The ESRI organisation.
*
* @see DefaultResponsibleParty#ESRI
* @category Organisation
*/
public static final Citation ESRI;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.ESRI, "ESRI");
c.setIdentifier("ESRI");
c.freeze();
ESRI = c;
}
/**
* The Oracle organisation.
*
* @see DefaultResponsibleParty#ORACLE
* @category Organisation
*/
public static final Citation ORACLE;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.ORACLE, "ORACLE");
c.setIdentifier("Oracle");
c.freeze();
ORACLE = c;
}
/**
* The PostGIS project.
*
* @see DefaultResponsibleParty#POSTGIS
* @category Organisation
*
* @since 2.4
*/
public static final Citation POSTGIS;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.POSTGIS, "POSTGIS");
c.setIdentifier("PostGIS");
c.freeze();
POSTGIS = c;
}
/**
* The Geotoolkit.org project.
*
* @see DefaultResponsibleParty#GEOTOOLKIT
* @category Organisation
*/
public static final Citation GEOTOOLKIT;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.GEOTOOLKIT, "GEOTOOLKIT");
c.setIdentifier("Geotk");
c.freeze();
GEOTOOLKIT = c;
}
/**
* The GeoTools project.
*
* @see DefaultResponsibleParty#GEOTOOLS
* @category Organisation
*/
public static final Citation GEOTOOLS;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.GEOTOOLS, "GEOTOOLS");
c.setIdentifier("GeoTools");
c.freeze();
GEOTOOLS = c;
}
///////////////////////////////////////////////////////////////////////
//////// ////////
//////// S P E C I F I C A T I O N S ////////
//////// ////////
///////////////////////////////////////////////////////////////////////
// Do not put the ...files/?artifact... link in the head sentence: it break javadoc formatting.
/**
* The Web Map Service specification. {@linkplain Citation#getAlternateTitles Alternate titles}
* for this citation are "WMS", "WMS 1.3.0", "OGC 04-024" and "ISO 19128". Note that the
* version numbers may be upgrated in future Geotk versions.
*
* @see Open Geospatial Consortium
* @see WMS 1.1.1 specification
* @see WMS 1.3.0 specification
* @see DefaultResponsibleParty#OGC
* @see DefaultOnlineResource#WMS
* @category Specification
*/
public static final Citation WMS;
static {
final CitationConstant c = new CitationConstant("Web Map Service", "WMS");
c.setIdentifier("WMS");
c.setAlternateTitles(asList(
new SimpleInternationalString("WMS 1.3.0"),
new SimpleInternationalString("OGC 04-024"),
new SimpleInternationalString("ISO 19128")));
c.setCitedResponsibleParties(asList(
DefaultResponsibleParty.OGC,
DefaultResponsibleParty.OGC(Role.PUBLISHER, DefaultOnlineResource.WMS)));
/*
* The WMS specification is a model in a programming point of view, but this is not
* the purpose of ISO 19115 PresentationForm.MODEL_DIGITAL in my understanding. The
* later rather looks like the output of a numerical model (e.g. meteorological model).
* The WMS specification is distributed as a PDF document.
*/
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL);
c.freeze();
WMS = c;
}
/**
* The NetCDF specification.
*
* @see DefaultResponsibleParty#NETCDF
* @category Specification
*
* @since 3.08
*/
public static final Citation NETCDF;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.NETCDF, "NETCDF");
c.setIdentifier("NetCDF");
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL);
c.freeze();
NETCDF = c;
}
/**
* The GeoTIFF specification.
*
* @see DefaultResponsibleParty#GEOTIFF
* @category Specification
*/
public static final Citation GEOTIFF;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.GEOTIFF, "GEOTIFF");
c.setIdentifier("GeoTIFF");
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL);
c.freeze();
GEOTIFF = c;
}
/**
* The Java Advanced Imaging library.
* An {@linkplain Citation#getAlternateTitles alternate title} for this citation is "JAI"
* (according ISO 19115, alternate titles often contain abbreviations).
*
* @see DefaultResponsibleParty#SUN_MICROSYSTEMS
* @category Specification
*/
public static final Citation JAI;
static {
final CitationConstant c = new CitationConstant("Java Advanced Imaging", "JAI");
c.setAuthority("JAI");
c.setCitedResponsibleParties(singleton(DefaultResponsibleParty.SUN_MICROSYSTEMS));
c.freeze();
JAI = c;
}
///////////////////////////////////////////////////////////////////////
//////// ////////
//////// C R S A U T H O R I T I E S ////////
//////// ////////
///////////////////////////////////////////////////////////////////////
/**
* The European Petroleum Survey Group authority.
* An {@linkplain Citation#getAlternateTitles alternate title} for this citation is
* "EPSG" (according ISO 19115, alternate titles often contain abbreviations). In
* addition, this citation contains the "EPSG" {@linkplain Citation#getIdentifiers identifier}.
*
* This citation is used as an authority for
* {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}
* identifiers. When searching an {@linkplain org.opengis.referencing.crs.CRSAuthorityFactory CRS
* authority factory} on EPSG data, Geotk compares the {@code "EPSG"} string against the
* {@linkplain Citation#getIdentifiers identifiers} (or against the {@linkplain Citation#getTitle
* title} and {@linkplain Citation#getAlternateTitles alternate titles} if there is no identifier)
* using the {@link #identifierMatches(Citation,String) identifierMatches} method.
*
* @see DefaultResponsibleParty#EPSG
* @see #AUTO
* @see #AUTO2
* @see #CRS
* @category Code space
*/
public static final Citation EPSG;
static {
final CitationConstant c = new CitationConstant(DefaultResponsibleParty.EPSG, "EPSG");
c.setAuthority("EPSG");
c.setPresentationForm(PresentationForm.TABLE_DIGITAL);
c.freeze();
EPSG = c;
}
/**
* The WMS 1.1.1 "Automatic Projections"
* authority. An {@linkplain Citation#getAlternateTitles alternate title} for this citation is
* "AUTO" (according ISO 19115, alternate titles often contain abbreviations). In addition, this
* citation contains the "AUTO" {@linkplain Citation#getIdentifiers identifier}.
*
* Warning: {@code AUTO} is different from {@link #AUTO2} used for WMS 1.3.0.
*
* This citation is used as an authority for
* {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}
* identifiers. When searching an {@linkplain org.opengis.referencing.crs.CRSAuthorityFactory CRS
* authority factory} on AUTO data, Geotk compares the {@code "AUTO"} string against the
* {@linkplain Citation#getIdentifiers identifiers} (or against the {@linkplain Citation#getTitle
* title} and {@linkplain Citation#getAlternateTitles alternate titles} if there is no identifier)
* using the {@link #identifierMatches(Citation,String) identifierMatches} method.
*
* @see Open Geospatial Consortium
* @see WMS 1.1.1 specification
* @see #WMS
* @see #AUTO2
* @see #CRS
* @see #EPSG
* @category Code space
*/
public static final Citation AUTO;
static { // Sanity check ensure that all @see tags are actually available in the metadata
final CitationConstant c = new CitationConstant("Automatic Projections", "AUTO");
c.setIdentifier("AUTO");
/*
* Do not put "WMS 1.1.1" and "OGC 01-068r3" as alternative titles. They are alternative
* titles for the WMS specification (see the WMS constant in this class), not for the
* AUTO authority name.
*/
c.setCitedResponsibleParties(asList(
DefaultResponsibleParty.OGC,
DefaultResponsibleParty.OGC(Role.PUBLISHER, OnLineFunction.DOWNLOAD, "http://www.opengis.org/docs/01-068r3.pdf")));
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL); // See comment in WMS.
c.freeze();
AUTO = c;
}
// Do not put the ...files/?artifact... link in the head sentence: it break javadoc formatting.
/**
* The WMS 1.3.0 "Automatic Projections" authority. An {@linkplain Citation#getAlternateTitles
* alternate title} for this citation is "AUTO2" (according ISO 19115, alternate titles often
* contain abbreviations). In addition, this citation contains the "AUTO2"
* {@linkplain Citation#getIdentifiers identifier}.
*
* Warning: {@code AUTO2} is different from {@link #AUTO} used for WMS 1.1.1
* and earlier.
*
* This citation is used as an authority for
* {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}
* identifiers. When searching an {@linkplain org.opengis.referencing.crs.CRSAuthorityFactory CRS
* authority factory} on AUTO2 data, Geotk compares the {@code "AUTO2"} string against the
* {@linkplain Citation#getIdentifiers identifiers} (or against the {@linkplain Citation#getTitle
* title} and {@linkplain Citation#getAlternateTitles alternate titles} if there is no identifier)
* using the {@link #identifierMatches(Citation,String) identifierMatches} method.
*
* @see Open Geospatial Consortium
* @see WMS 1.3.0 specification
* @see #WMS
* @see #AUTO
* @see #CRS
* @see #EPSG
* @category Code space
*/
public static final Citation AUTO2;
static {
final CitationConstant c = new CitationConstant("Automatic Projections", "AUTO2");
c.setIdentifier("AUTO2");
/*
* Do not put "WMS 1.3.0" and "OGC 04-024" as alternative titles. They are alternative
* titles for the WMS specification (see the WMS constant in this class), not for the
* AUTO2 authority name.
*/
c.setCitedResponsibleParties(asList(
DefaultResponsibleParty.OGC,
DefaultResponsibleParty.OGC(Role.PUBLISHER, DefaultOnlineResource.WMS)));
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL); // See comment in WMS.
c.freeze();
AUTO2 = c;
}
// Do not put the ...files/?artifact... link in the head sentence: it break javadoc formatting.
/**
* The WMS 1.3.0 "CRS" authority. This is defined in the same document than {@link #AUTO2}.
* This citation declares both {@code "CRS"} and {@code "OGC"} identifiers, because we see
* both {@code "CRS:84"} and {@code "OGC:CRS84"} in practice.
*
* @see #WMS
* @see #AUTO
* @see #AUTO2
* @see #CRS
* @see #EPSG
* @category Code space
*/
public static final Citation CRS;
static {
final CitationConstant c = new CitationConstant("Web Map Service CRS", "CRS");
c.setIdentifier("CRS");
c.getIdentifiers().add(new DefaultIdentifier("OGC"));
c.setCitedResponsibleParties(AUTO2.getCitedResponsibleParties());
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL); // See comment in WMS.
c.freeze();
CRS = c;
}
/**
* URN in the OGC namespace. This citation contains the {@code "urn:ogc:def"} and
* {@code "urn:x-ogc:def"} {@linkplain Citation#getIdentifiers identifiers}.
*
* @category Code space
* @since 2.4
*/
public static final Citation URN_OGC;
static {
final CitationConstant c = new CitationConstant("URN in OGC namespace", "URN_OGC");
c.setIdentifier("urn:ogc:def");
c.getIdentifiers().add(new DefaultIdentifier("urn:x-ogc:def"));
c.setCitedResponsibleParties(singleton(DefaultResponsibleParty.OGC));
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL);
c.freeze();
URN_OGC = c;
}
/**
* URL in the OGC namespace. This citation contains the
* {@code "http://www.opengis.net"} {@linkplain Citation#getIdentifiers identifiers}.
*
* @category Code space
* @since 2.4
*/
public static final Citation HTTP_OGC;
static {
final CitationConstant c = new CitationConstant("URL in OGC namespace", "HTTP_OGC");
c.setIdentifier("http://www.opengis.net");
c.setCitedResponsibleParties(singleton(DefaultResponsibleParty.OGC));
c.setPresentationForm(PresentationForm.DOCUMENT_DIGITAL);
c.freeze();
HTTP_OGC = c;
}
/**
* Unknown authority, vendor or specification.
*
* @since 3.05
*/
public static final Citation UNKNOWN;
static {
final CitationConstant c = new CitationConstant(Vocabulary.formatInternational(Vocabulary.Keys.UNKNOWN), "UNKNOWN");
c.freeze();
UNKNOWN = c;
}
///////////////////////////////////////////////////////////////////////
//////// ////////
//////// End of constants declarations ////////
//////// ////////
///////////////////////////////////////////////////////////////////////
/**
* List of citations declared in this class.
*/
private static final Citation[] AUTHORITIES = {
OGC, OPEN_GIS, ESRI, ORACLE, POSTGIS, GEOTOOLKIT, GEOTOOLS, WMS, NETCDF, GEOTIFF, JAI,
EPSG, AUTO, AUTO2, CRS, URN_OGC, HTTP_OGC, UNKNOWN
};
/**
* Returns a citation of the given name. The method makes the following choice:
*
*
* - If the given title is {@code null} or empty (ignoring spaces), then this method
* returns {@code null}.
* - Otherwise if the given name matches a {@linkplain Citation#getTitle title} or an
* {@linkplain Citation#getAlternateTitles alternate titles} of one of the pre-defined
* constants ({@link #EPSG}, {@link #GEOTIFF}, etc.), then that constant
* is returned.
* - Otherwise, a new citation is created with the specified name as the title.
*
*
* @param title The citation title (or alternate title), or {@code null}.
* @return A citation using the specified name, or {@code null} if the given title is null
* or empty.
*/
public static Citation fromName(String title) {
if (title == null || ((title = title.trim()).isEmpty())) {
return null;
}
for (int i=0; i
* If (and only if) the citations do not contains any identifier, then this method
* fallback on titles comparison using the {@link #titleMatches(Citation,Citation)
* titleMatches} method. This fallback exists for compatibility with client codes using
* citation {@linkplain Citation#getTitle titles} without identifiers.
*
* @param c1 The first citation to compare.
* @param c2 the second citation to compare.
* @return {@code true} if at least one identifier, title or alternate title matches.
*/
public static boolean identifierMatches(final Citation c1, final Citation c2) {
ArgumentChecks.ensureNonNull("c1", c1);
ArgumentChecks.ensureNonNull("c2", c2);
return org.geotoolkit.internal.Citations.identifierMatches(c1, c2);
}
/**
* Returns {@code true} if any {@linkplain Citation#getIdentifiers identifiers} in the given
* citation matches the given string. The comparison is case-insensitive and ignores leading
* and trailing spaces. If (and only if) the citation do not contains any identifier,
* then this method fallback on titles comparison using the {@link #titleMatches(Citation,
* String) titleMatches} method. This fallback exists for compatibility with client codes using
* citation {@linkplain Citation#getTitle titles} without identifiers.
*
* @param citation The citation to check for.
* @param identifier The identifier to compare.
* @return {@code true} if the title or alternate title matches the given string.
*/
public static boolean identifierMatches(final Citation citation, final String identifier) {
ArgumentChecks.ensureNonNull("citation", citation);
ArgumentChecks.ensureNonNull("identifier", identifier);
return org.geotoolkit.internal.Citations.identifierMatches(citation, identifier);
}
/**
* Returns the shortest identifier for the specified citation, or the title if there is
* no identifier. This method is useful for extracting the namespace from an authority,
* for example {@code "EPSG"}.
*
* @param citation The citation for which to get the identifier, or {@code null}.
* @return The shortest identifier of the given citation, or {@code null} if the
* given citation was null.
*
* @since 2.4
*/
public static String getIdentifier(final Citation citation) {
return org.geotoolkit.internal.Citations.getIdentifier(citation);
}
}