org.opengis.referencing.IdentifiedObject 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.
The newest version!
/*
 *    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.Obligation.*;
import static org.opengis.annotation.Specification.*;

import java.util.Collection;
import java.util.Set;
import org.opengis.annotation.Extension;
import org.opengis.annotation.UML;
import org.opengis.util.GenericName;
import org.opengis.util.InternationalString;

/**
 * Supplementary identification and remarks information for a CRS or CRS-related object. When {@link
 * org.opengis.referencing.crs.CRSAuthorityFactory} is used to create an object, the {@linkplain
 * ReferenceIdentifier#getAuthority authority} and {@linkplain ReferenceIdentifier#getCode authority
 * code} values should be set to the authority name of the factory object, and the authority code
 * supplied by the client, respectively. The other values may or may not be set. If the authority is
 * EPSG, the implementer may consider using the corresponding metadata values in the EPSG tables.
 *
 * @departure ISO 19111 defines also an {@code IdentifiedObjectBase} interface. The later is omitted
 *     in GeoAPI because the split between {@code IdentifiedObject} and {@code IdentifiedObjectBase}
 *     in OGC/ISO specification was mostly a workaround for introducing {@code IdentifiedObject} in
 *     ISO 19111 without changing the {@code ReferenceSystem} definition in ISO 19115.
 * @version Abstract
 *     specification 2.0
 * @author Martin Desruisseaux (IRD)
 * @since GeoAPI 2.0
 */
@UML(identifier = "IO_IdentifiedObject", specification = ISO_19111)
public interface IdentifiedObject {
    /**
     * Key for the {@value} property to be given to the {@linkplain ObjectFactory
     * object factory} createFoo(…) methods. This is used for setting the value
     * to be returned by {@link #getName}.
     *
     * @see #getName
     */
    String NAME_KEY = "name";

    /**
     * Key for the {@value} property to be given to the {@linkplain ObjectFactory
     * object factory} createFoo(…) methods. This is used for setting the value
     * to be returned by {@link #getAlias}.
     *
     * @see #getAlias
     */
    String ALIAS_KEY = "alias";

    /**
     * Key for the {@value} property to be given to the {@linkplain ObjectFactory
     * object factory} createFoo(…) methods. This is used for setting the value
     * to be returned by {@link #getIdentifiers}.
     *
     * @see #getIdentifiers
     */
    String IDENTIFIERS_KEY = "identifiers";

    /**
     * Key for the {@value} property to be given to the {@linkplain ObjectFactory
     * object factory} createFoo(…) methods. This is used for setting the value
     * to be returned by {@link #getRemarks}.
     *
     * @see #getRemarks
     */
    String REMARKS_KEY = "remarks";

    /**
     * The primary name by which this object is identified.
     *
     * @return The primary name.
     */
    @UML(identifier = "name", obligation = MANDATORY, specification = ISO_19111)
    ReferenceIdentifier getName();

    /**
     * An alternative name by which this object is identified.
     *
     * @return The aliases, or an empty collection if there is none.
     */
    @UML(identifier = "alias", obligation = OPTIONAL, specification = ISO_19111)
    Collection getAlias();

    /**
     * An identifier which references elsewhere the object's defining information. Alternatively an
     * identifier by which this object can be referenced.
     *
     * @return This object identifiers, or an empty set if there is none.
     */
    @UML(identifier = "identifier", obligation = OPTIONAL, specification = ISO_19111)
    Set getIdentifiers();

    /**
     * Comments on or information about this object, including data source information.
     *
     * @return The remarks, or {@code null} if none.
     */
    @UML(identifier = "remarks", obligation = OPTIONAL, specification = ISO_19111)
    InternationalString getRemarks();

    /**
     * Returns a Well Known Text (WKT) for this
     * object. This operation may fails if an object is too complex for the WKT format capability
     * (for example an {@linkplain org.opengis.referencing.crs.EngineeringCRS engineering CRS} with
     * different unit for each axis).
     *
     * @return The Well Know Text for this object.
     * @throws UnsupportedOperationException If this object can't be formatted as WKT.
     */
    @Extension
    String toWKT() throws UnsupportedOperationException;
}