001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.referencing;
033
034 import org.opengis.metadata.extent.Extent;
035 import org.opengis.util.InternationalString;
036 import org.opengis.annotation.UML;
037
038 import static org.opengis.annotation.Obligation.*;
039 import static org.opengis.annotation.Specification.*;
040
041
042 /**
043 * Description of a spatial and temporal reference system used by a dataset.
044 *
045 * @departure historic
046 * This interface was initially derived from an ISO 19111 specification published in 2003. Later
047 * revisions (in 2005) rely on an interface defined in ISO 19115 instead. The annotations were
048 * updated accordingly, but this interface is still defined in the referencing package instead
049 * of the metadata package for this historical reason.
050 *
051 * @author Martin Desruisseaux (IRD)
052 * @version 3.0
053 * @since 1.0
054 *
055 * @see org.opengis.referencing.crs.CoordinateReferenceSystem
056 *
057 * @navassoc 1 - - Extent
058 */
059 @UML(identifier="RS_ReferenceSystem", specification=ISO_19115)
060 public interface ReferenceSystem extends IdentifiedObject {
061 /**
062 * Key for the <code>{@value}</code> property to be given to the
063 * {@linkplain ObjectFactory object factory} <code>createFoo(…)</code> methods.
064 * This is used for setting the value to be returned by {@link #getDomainOfValidity()}.
065 *
066 * @see #getDomainOfValidity()
067 *
068 * @since 2.1
069 */
070 String DOMAIN_OF_VALIDITY_KEY = "domainOfValidity";
071
072 /**
073 * Key for the <code>{@value}</code> property to be given to the
074 * {@linkplain ObjectFactory object factory} <code>createFoo(…)</code> methods.
075 * This is used for setting the value to be returned by {@link #getScope()}.
076 *
077 * @see #getScope()
078 */
079 String SCOPE_KEY = "scope";
080
081 /**
082 * Area or region or timeframe in which this (coordinate) reference system is valid.
083 *
084 * @return The reference system valid domain, or {@code null} if not available.
085 *
086 * @departure historic
087 * This method has been kept conformant with the specification published in 2003.
088 * Later revisions changed the multiplicity, so the return type should now be a
089 * collection. The singleton has been preserved in GeoAPI for historical reasons,
090 * and also because the <code>Extent</code> attributes already allow collections.
091 *
092 * @since 2.1
093 */
094 @UML(identifier="domainOfValidity", obligation=OPTIONAL, specification=ISO_19111)
095 Extent getDomainOfValidity();
096
097 /**
098 * Description of domain of usage, or limitations of usage, for which this
099 * Reference System object is valid.
100 *
101 * @return The domain of usage, or {@code null} if none.
102 *
103 * @departure historic
104 * This method has been kept conformant with the specification published in 2003.
105 * A later revision moved this attribute to subclasses, but GeoAPI keeps this method
106 * here for historical reasons. The obligation is still optional, as opposed to ISO 19111:2007
107 * which makes this attribute mandatory while mandating the text "<cite>not known</cite>" if
108 * the scope is unknown. In addition, the return value of this method is still a singleton as in
109 * the 2003 version, as opposed to the 2007 version which mandates a collection. The proposed
110 * change is still under review.
111 */
112 @UML(identifier="SC_CRS.scope", obligation=OPTIONAL, specification=ISO_19111)
113 InternationalString getScope();
114 }