001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 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.cs;
033
034 import javax.measure.unit.Unit;
035 import org.opengis.referencing.AuthorityFactory;
036 import org.opengis.referencing.NoSuchAuthorityCodeException;
037 import org.opengis.util.FactoryException;
038 import org.opengis.annotation.UML;
039
040 import static org.opengis.annotation.Specification.*;
041
042
043 /**
044 * Creates {@linkplain CoordinateSystem coordinate systems} using authority codes. External authorities
045 * are used to manage definitions of objects used in this interface. The definitions of these objects are
046 * referenced using code strings. A commonly used authority is <A HREF="http://www.epsg.org">EPSG</A>,
047 * which is also used in the <A HREF="http://www.remotesensing.org/geotiff/geotiff.html">GeoTIFF</A>
048 * standard.
049 *
050 * @author Martin Desruisseaux (IRD)
051 * @version 3.0
052 * @since 1.0
053 *
054 * @departure historic
055 * Added for consistency with CRS and datum factories. This CS factory was not defined in the
056 * OGC specification because OGC 01-009 was created before ISO 19111 and had no equivalent of
057 * the ISO <cite>Coordinate System</cite> types.
058 *
059 * @see org.opengis.referencing.crs.CRSAuthorityFactory
060 * @see org.opengis.referencing.datum.DatumAuthorityFactory
061 */
062 public interface CSAuthorityFactory extends AuthorityFactory {
063 /**
064 * Returns an arbitrary {@linkplain CoordinateSystem coordinate system} from a code.
065 * If the coordinate system type is know at compile time, it is recommended to invoke
066 * the most precise method instead of this one (for example
067 * <code> {@linkplain #createCartesianCS createCartesianCS}(code) </code>
068 * instead of <code> createCoordinateSystem(code) </code> if the caller
069 * know he is asking for a {@linkplain CartesianCS cartesian coordinate system}).
070 *
071 * @param code Value allocated by authority.
072 * @return The coordinate system for the given code.
073 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
074 * @throws FactoryException if the object creation failed for some other reason.
075 */
076 CoordinateSystem createCoordinateSystem(String code)
077 throws NoSuchAuthorityCodeException, FactoryException;
078
079 /**
080 * Creates a cartesian coordinate system from a code.
081 *
082 * @param code Value allocated by authority.
083 * @return The coordinate system for the given code.
084 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
085 * @throws FactoryException if the object creation failed for some other reason.
086 */
087 CartesianCS createCartesianCS(String code)
088 throws NoSuchAuthorityCodeException, FactoryException;
089
090 /**
091 * Creates a polar coordinate system from a code.
092 *
093 * @param code Value allocated by authority.
094 * @return The coordinate system for the given code.
095 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
096 * @throws FactoryException if the object creation failed for some other reason.
097 */
098 PolarCS createPolarCS(String code)
099 throws NoSuchAuthorityCodeException, FactoryException;
100
101 /**
102 * Creates a cylindrical coordinate system from a code.
103 *
104 * @param code Value allocated by authority.
105 * @return The coordinate system for the given code.
106 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
107 * @throws FactoryException if the object creation failed for some other reason.
108 */
109 CylindricalCS createCylindricalCS(String code)
110 throws NoSuchAuthorityCodeException, FactoryException;
111
112 /**
113 * Creates a spherical coordinate system from a code.
114 *
115 * @param code Value allocated by authority.
116 * @return The coordinate system for the given code.
117 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
118 * @throws FactoryException if the object creation failed for some other reason.
119 */
120 SphericalCS createSphericalCS(String code)
121 throws NoSuchAuthorityCodeException, FactoryException;
122
123 /**
124 * Creates an ellipsoidal coordinate system from a code.
125 *
126 * @param code Value allocated by authority.
127 * @return The coordinate system for the given code.
128 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
129 * @throws FactoryException if the object creation failed for some other reason.
130 */
131 EllipsoidalCS createEllipsoidalCS(String code)
132 throws NoSuchAuthorityCodeException, FactoryException;
133
134 /**
135 * Creates a vertical coordinate system from a code.
136 *
137 * @param code Value allocated by authority.
138 * @return The coordinate system for the given code.
139 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
140 * @throws FactoryException if the object creation failed for some other reason.
141 */
142 VerticalCS createVerticalCS(String code)
143 throws NoSuchAuthorityCodeException, FactoryException;
144
145 /**
146 * Creates a temporal coordinate system from a code.
147 *
148 * @param code Value allocated by authority.
149 * @return The coordinate system for the given code.
150 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
151 * @throws FactoryException if the object creation failed for some other reason.
152 */
153 TimeCS createTimeCS(String code)
154 throws NoSuchAuthorityCodeException, FactoryException;
155
156 /**
157 * Returns a {@linkplain CoordinateSystemAxis coordinate system axis} from a code.
158 *
159 * @param code Value allocated by authority.
160 * @return The axis for the given code.
161 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
162 * @throws FactoryException if the object creation failed for some other reason.
163 */
164 CoordinateSystemAxis createCoordinateSystemAxis(String code)
165 throws NoSuchAuthorityCodeException, FactoryException;
166
167 /**
168 * Returns an {@linkplain Unit unit} from a code.
169 *
170 * @param code Value allocated by authority.
171 * @return The unit for the given code.
172 * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
173 * @throws FactoryException if the object creation failed for some other reason.
174 */
175 @UML(identifier="CS_CoordinateSystemAuthorityFactory.createLinearUnit, createAngularUnit", specification=OGC_01009)
176 Unit<?> createUnit(String code)
177 throws NoSuchAuthorityCodeException, FactoryException;
178 }