org.opengis.referencing.AuthorityFactory Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of gt-opengis Show documentation
Standard interfaces implemented throughout the library.
There is a newer version: 24.2-oss84-1
/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2011, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2003-2005, Open Geospatial Consortium Inc.
 *
 *    All Rights Reserved. http://www.opengis.org/legal/
 */
package org.opengis.referencing;

import static org.opengis.annotation.Specification.*;

import java.util.Set;
import org.opengis.annotation.Extension;
import org.opengis.annotation.UML;
import org.opengis.metadata.citation.Citation;
import org.opengis.util.InternationalString;

/**
 * Base interface for all authority factories. An authority is an organization that
 * maintains definitions of authority codes. An authority code is a compact string
 * defined by an authority to reference a particular spatial reference object. For example the European Petroleum Survey Group (EPSG) maintains a database of
 * coordinate systems, and other spatial referencing objects, where each object has a code number
 * ID. For example, the EPSG code for a WGS84 Lat/Lon coordinate system is '4326'.
 *
 * @version Implementation specification 1.0
 * @author Martin Desruisseaux (IRD)
 * @since GeoAPI 1.0
 */
@UML(identifier = "CS_CoordinateSystemAuthorityFactory", specification = OGC_01009)
public interface AuthorityFactory extends Factory {
    /**
     * Returns the organization or party responsible for definition and maintenance of the database.
     *
     * @return The organization reponsible for definition of the database.
     */
    @UML(identifier = "getAuthority", specification = OGC_01009)
    Citation getAuthority();

    /**
     * Returns the set of authority codes of the given type. The {@code type} argument specify the
     * base class. For example if this factory is an instance of {@link
     * org.opengis.referencing.crs.CRSAuthorityFactory}, then:
     *
     * 
     *   {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem}.class 
     *        asks for all authority codes accepted by one of {@link
     *       org.opengis.referencing.crs.CRSAuthorityFactory#createGeographicCRS
     *       createGeographicCRS}, {@link
     *       org.opengis.referencing.crs.CRSAuthorityFactory#createProjectedCRS createProjectedCRS},
     *       {@link org.opengis.referencing.crs.CRSAuthorityFactory#createVerticalCRS
     *       createVerticalCRS}, {@link
     *       org.opengis.referencing.crs.CRSAuthorityFactory#createTemporalCRS createTemporalCRS}
     *       and their friends.
     *   
{@linkplain org.opengis.referencing.crs.ProjectedCRS}.class 
     *       asks only for authority codes accepted by {@link
     *       org.opengis.referencing.crs.CRSAuthorityFactory#createProjectedCRS createProjectedCRS}.
     * 
     *
     * @param type The spatial reference objects type.
     * @return The set of authority codes for spatial reference objects of the given type. If this
     *     factory doesn't contains any object of the given type, then this method returns an
     *     {@linkplain java.util.Collections#EMPTY_SET empty set}.
     * @throws FactoryException if access to the underlying database failed.
     */
    @Extension
    Set getAuthorityCodes(Class type) throws FactoryException;

    /**
     * Gets a description of the object corresponding to a code.
     *
     * @param code Value allocated by authority.
     * @return A description of the object, or {@code null} if the object corresponding to the
     *     specified {@code code} has no description.
     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
     * @throws FactoryException if the query failed for some other reason.
     */
    @UML(identifier = "descriptionText", specification = OGC_01009)
    InternationalString getDescriptionText(String code)
            throws NoSuchAuthorityCodeException, FactoryException;

    /**
     * Returns an arbitrary object from a code. The returned object will typically be an instance of
     * {@link org.opengis.referencing.datum.Datum}, {@link
     * org.opengis.referencing.cs.CoordinateSystem}, {@link org.opengis.referencing.ReferenceSystem}
     * or {@link org.opengis.referencing.operation.CoordinateOperation}. If the type of the object
     * is know at compile time, it is recommended to invoke the most precise method instead of this
     * one (for example 
     *  {@linkplain org.opengis.referencing.crs.CRSAuthorityFactory#createCoordinateReferenceSystem
     * createCoordinateReferenceSystem}(code)  instead of 
     *  createObject(code)  if the caller know he is asking for a {@linkplain
     * org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}).
     *
     * @param code Value allocated by authority.
     * @return The object for the given code.
     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
     * @throws FactoryException if the object creation failed for some other reason.
     * @see org.opengis.referencing.datum.DatumAuthorityFactory#createDatum
     * @see org.opengis.referencing.crs.CRSAuthorityFactory#createCoordinateReferenceSystem
     */
    @Extension
    IdentifiedObject createObject(String code)
            throws NoSuchAuthorityCodeException, FactoryException;
}