001/* 002 * GeoAPI - Java interfaces for OGC/ISO standards 003 * Copyright © 2004-2024 Open Geospatial Consortium, Inc. 004 * http://www.geoapi.org 005 * 006 * Licensed under the Apache License, Version 2.0 (the "License"); 007 * you may not use this file except in compliance with the License. 008 * You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.opengis.referencing.cs; 019 020import java.util.Map; 021import javax.measure.Unit; 022import org.opengis.referencing.ObjectFactory; 023import org.opengis.util.FactoryException; 024import org.opengis.util.UnimplementedServiceException; 025 026 027/** 028 * Builds up complex {@linkplain CoordinateSystem coordinate systems} from simpler objects or values. 029 * {@code CSFactory} allows applications to make {@linkplain CoordinateSystem coordinate systems} that 030 * cannot be created by a {@link CSAuthorityFactory}. 031 * This factory is very flexible, whereas the authority factory is easier to use. 032 * So {@link CSAuthorityFactory} can be used to make "standard" coordinate systems, 033 * and {@code CSFactory} can be used to make "special" coordinate systems. 034 * 035 * <h2>Default methods</h2> 036 * All {@code create(…)} methods in this interface are optional. 037 * If a method is not overridden by the implementer, 038 * the default is to throw an {@link UnimplementedServiceException} 039 * with a message saying that the type or service is not supported. 040 * 041 * @author Martin Desruisseaux (IRD, Geomatys) 042 * @author Johann Sorel (Geomatys) 043 * @version 3.1 044 * @since 1.0 045 * 046 * @see org.opengis.referencing.crs.CRSFactory 047 * @see org.opengis.referencing.datum.DatumFactory 048 */ 049public interface CSFactory extends ObjectFactory { 050 /** 051 * Creates a coordinate system axis from an abbreviation and a unit. 052 * 053 * @param properties name and other properties to give to the new object. 054 * Available properties are {@linkplain ObjectFactory listed there}. 055 * @param abbreviation the coordinate axis abbreviation. 056 * @param direction the axis direction. 057 * @param unit the coordinate axis unit. 058 * @return the axis for the given properties. 059 * @throws FactoryException if the object creation failed. 060 */ 061 default CoordinateSystemAxis createCoordinateSystemAxis(Map<String,?> properties, 062 String abbreviation, 063 AxisDirection direction, 064 Unit<?> unit) throws FactoryException 065 { 066 throw new UnimplementedServiceException(this, CoordinateSystemAxis.class); 067 } 068 069 /** 070 * Creates a two dimensional Cartesian coordinate system from the given pair of axes. 071 * 072 * @param properties name and other properties to give to the new object. 073 * Available properties are {@linkplain ObjectFactory listed there}. 074 * @param axis0 the first axis. 075 * @param axis1 the second axis. 076 * @return the coordinate system for the given properties and axes. 077 * @throws FactoryException if the object creation failed. 078 */ 079 default CartesianCS createCartesianCS(Map<String,?> properties, 080 CoordinateSystemAxis axis0, 081 CoordinateSystemAxis axis1) throws FactoryException 082 { 083 throw new UnimplementedServiceException(this, CartesianCS.class, "2D"); 084 } 085 086 /** 087 * Creates a three dimensional Cartesian coordinate system from the given set of axes. 088 * 089 * @param properties name and other properties to give to the new object. 090 * Available properties are {@linkplain ObjectFactory listed there}. 091 * @param axis0 the first axis. 092 * @param axis1 the second axis. 093 * @param axis2 the third axis. 094 * @return the coordinate system for the given properties and axes. 095 * @throws FactoryException if the object creation failed. 096 */ 097 default CartesianCS createCartesianCS(Map<String,?> properties, 098 CoordinateSystemAxis axis0, 099 CoordinateSystemAxis axis1, 100 CoordinateSystemAxis axis2) throws FactoryException 101 { 102 throw new UnimplementedServiceException(this, CartesianCS.class, "3D"); 103 } 104 105 /** 106 * Creates a two dimensional affine coordinate system from the given pair of axes. 107 * 108 * @param properties name and other properties to give to the new object. 109 * Available properties are {@linkplain ObjectFactory listed there}. 110 * @param axis0 the first axis. 111 * @param axis1 the second axis. 112 * @return the coordinate system for the given properties and axes. 113 * @throws FactoryException if the object creation failed. 114 */ 115 default AffineCS createAffineCS(Map<String,?> properties, 116 CoordinateSystemAxis axis0, 117 CoordinateSystemAxis axis1) throws FactoryException 118 { 119 throw new UnimplementedServiceException(this, AffineCS.class, "2D"); 120 } 121 122 /** 123 * Creates a three dimensional affine coordinate system from the given set of axes. 124 * 125 * @param properties name and other properties to give to the new object. 126 * Available properties are {@linkplain ObjectFactory listed there}. 127 * @param axis0 the first axis. 128 * @param axis1 the second axis. 129 * @param axis2 the third axis. 130 * @return the coordinate system for the given properties and axes. 131 * @throws FactoryException if the object creation failed. 132 */ 133 default AffineCS createAffineCS(Map<String,?> properties, 134 CoordinateSystemAxis axis0, 135 CoordinateSystemAxis axis1, 136 CoordinateSystemAxis axis2) throws FactoryException 137 { 138 throw new UnimplementedServiceException(this, AffineCS.class, "3D"); 139 } 140 141 /** 142 * Creates a polar coordinate system from the given pair of axes. 143 * 144 * @param properties name and other properties to give to the new object. 145 * Available properties are {@linkplain ObjectFactory listed there}. 146 * @param axis0 the first axis. 147 * @param axis1 the second axis. 148 * @return the coordinate system for the given properties and axes. 149 * @throws FactoryException if the object creation failed. 150 */ 151 default PolarCS createPolarCS(Map<String,?> properties, 152 CoordinateSystemAxis axis0, 153 CoordinateSystemAxis axis1) throws FactoryException 154 { 155 throw new UnimplementedServiceException(this, PolarCS.class); 156 } 157 158 /** 159 * Creates a cylindrical coordinate system from the given set of axes. 160 * 161 * @param properties name and other properties to give to the new object. 162 * Available properties are {@linkplain ObjectFactory listed there}. 163 * @param axis0 the first axis. 164 * @param axis1 the second axis. 165 * @param axis2 the third axis. 166 * @return the coordinate system for the given properties and axes. 167 * @throws FactoryException if the object creation failed. 168 */ 169 default CylindricalCS createCylindricalCS(Map<String,?> properties, 170 CoordinateSystemAxis axis0, 171 CoordinateSystemAxis axis1, 172 CoordinateSystemAxis axis2) throws FactoryException 173 { 174 throw new UnimplementedServiceException(this, CylindricalCS.class); 175 } 176 177 /** 178 * Creates a spherical coordinate system without radius. 179 * The two axes shall use angular units. 180 * 181 * @param properties name and other properties to give to the new object. 182 * Available properties are {@linkplain ObjectFactory listed there}. 183 * @param axis0 the first axis. 184 * @param axis1 the second axis. 185 * @return the coordinate system for the given properties and axes. 186 * @throws FactoryException if the object creation failed. 187 * 188 * @since 3.1 189 */ 190 default SphericalCS createSphericalCS(Map<String,?> properties, 191 CoordinateSystemAxis axis0, 192 CoordinateSystemAxis axis1) throws FactoryException 193 { 194 throw new UnimplementedServiceException(this, SphericalCS.class, "2D"); 195 } 196 197 /** 198 * Creates a spherical coordinate system from the given set of axes. 199 * Two axes shall use angular units and one axis shall use linear units. 200 * 201 * @param properties name and other properties to give to the new object. 202 * Available properties are {@linkplain ObjectFactory listed there}. 203 * @param axis0 the first axis. 204 * @param axis1 the second axis. 205 * @param axis2 the third axis. 206 * @return the coordinate system for the given properties and axes. 207 * @throws FactoryException if the object creation failed. 208 */ 209 default SphericalCS createSphericalCS(Map<String,?> properties, 210 CoordinateSystemAxis axis0, 211 CoordinateSystemAxis axis1, 212 CoordinateSystemAxis axis2) throws FactoryException 213 { 214 throw new UnimplementedServiceException(this, SphericalCS.class, "3D"); 215 } 216 217 /** 218 * Creates an ellipsoidal coordinate system without ellipsoidal height. 219 * 220 * @param properties name and other properties to give to the new object. 221 * Available properties are {@linkplain ObjectFactory listed there}. 222 * @param axis0 the first axis. 223 * @param axis1 the second axis. 224 * @return the coordinate system for the given properties and axes. 225 * @throws FactoryException if the object creation failed. 226 */ 227 default EllipsoidalCS createEllipsoidalCS(Map<String,?> properties, 228 CoordinateSystemAxis axis0, 229 CoordinateSystemAxis axis1) throws FactoryException 230 { 231 throw new UnimplementedServiceException(this, EllipsoidalCS.class, "2D"); 232 } 233 234 /** 235 * Creates an ellipsoidal coordinate system with ellipsoidal height. 236 * 237 * @param properties name and other properties to give to the new object. 238 * Available properties are {@linkplain ObjectFactory listed there}. 239 * @param axis0 the first axis. 240 * @param axis1 the second axis. 241 * @param axis2 the third axis. 242 * @return the coordinate system for the given properties and axes. 243 * @throws FactoryException if the object creation failed. 244 */ 245 default EllipsoidalCS createEllipsoidalCS(Map<String,?> properties, 246 CoordinateSystemAxis axis0, 247 CoordinateSystemAxis axis1, 248 CoordinateSystemAxis axis2) throws FactoryException 249 { 250 throw new UnimplementedServiceException(this, EllipsoidalCS.class, "3D"); 251 } 252 253 /** 254 * Creates a vertical coordinate system. 255 * 256 * @param properties name and other properties to give to the new object. 257 * Available properties are {@linkplain ObjectFactory listed there}. 258 * @param axis the axis. 259 * @return the coordinate system for the given properties and axes. 260 * @throws FactoryException if the object creation failed. 261 */ 262 default VerticalCS createVerticalCS(Map<String,?> properties, 263 CoordinateSystemAxis axis) throws FactoryException 264 { 265 throw new UnimplementedServiceException(this, VerticalCS.class); 266 } 267 268 /** 269 * Creates a time coordinate system. 270 * 271 * @param properties name and other properties to give to the new object. 272 * Available properties are {@linkplain ObjectFactory listed there}. 273 * @param axis the axis. 274 * @return the coordinate system for the given properties and axes. 275 * @throws FactoryException if the object creation failed. 276 */ 277 default TimeCS createTimeCS(Map<String,?> properties, 278 CoordinateSystemAxis axis) throws FactoryException 279 { 280 throw new UnimplementedServiceException(this, TimeCS.class); 281 } 282 283 /** 284 * Creates a parametric coordinate system. 285 * 286 * @param properties name and other properties to give to the new object. 287 * Available properties are {@linkplain ObjectFactory listed there}. 288 * @param axis the axis. 289 * @return the coordinate system for the given properties and axes. 290 * @throws FactoryException if the object creation failed. 291 * 292 * @since 3.1 293 */ 294 default ParametricCS createParametricCS(Map<String,?> properties, 295 CoordinateSystemAxis axis) throws FactoryException 296 { 297 throw new UnimplementedServiceException(this, ParametricCS.class); 298 } 299 300 /** 301 * Creates a linear coordinate system. 302 * 303 * @param properties name and other properties to give to the new object. 304 * Available properties are {@linkplain ObjectFactory listed there}. 305 * @param axis the axis. 306 * @return the coordinate system for the given properties and axes. 307 * @throws FactoryException if the object creation failed. 308 */ 309 default LinearCS createLinearCS(Map<String,?> properties, 310 CoordinateSystemAxis axis) throws FactoryException 311 { 312 throw new UnimplementedServiceException(this, LinearCS.class); 313 } 314 315 /** 316 * Creates a two-dimensional user defined coordinate system. 317 * 318 * @param properties name and other properties to give to the new object. 319 * Available properties are {@linkplain ObjectFactory listed there}. 320 * @param axis0 the first axis. 321 * @param axis1 the second axis. 322 * @return the coordinate system for the given properties and axes. 323 * @throws FactoryException if the object creation failed. 324 * 325 * @deprecated User-defined <abbr>CS</abbr> needs their own constructor 326 * for instantiating their specialized type. 327 */ 328 @Deprecated(since="3.1") 329 default UserDefinedCS createUserDefinedCS(Map<String,?> properties, 330 CoordinateSystemAxis axis0, 331 CoordinateSystemAxis axis1) throws FactoryException 332 { 333 throw new UnimplementedServiceException(this, UserDefinedCS.class, "2D"); 334 } 335 336 /** 337 * Creates a three-dimensional user defined coordinate system. 338 * 339 * @param properties name and other properties to give to the new object. 340 * Available properties are {@linkplain ObjectFactory listed there}. 341 * @param axis0 the first axis. 342 * @param axis1 the second axis. 343 * @param axis2 the third axis. 344 * @return the coordinate system for the given properties and axes. 345 * @throws FactoryException if the object creation failed. 346 * 347 * @deprecated User-defined <abbr>CS</abbr> needs their own constructor 348 * for instantiating their specialized type. 349 */ 350 @Deprecated(since="3.1") 351 default UserDefinedCS createUserDefinedCS(Map<String,?> properties, 352 CoordinateSystemAxis axis0, 353 CoordinateSystemAxis axis1, 354 CoordinateSystemAxis axis2) throws FactoryException 355 { 356 throw new UnimplementedServiceException(this, UserDefinedCS.class, "3D"); 357 } 358}