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.geometry.primitive;
033
034 import org.opengis.geometry.DirectPosition;
035 import org.opengis.geometry.coordinate.Position;
036 import org.opengis.geometry.UnmodifiableGeometryException;
037 import org.opengis.annotation.Association;
038 import org.opengis.annotation.UML;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * Basic data type for a geometric object consisting of one and only one point.
046 * In most cases, the state of a {@code Point} is fully determined by its
047 * position attribute. The only exception to this is if the {@code Point}
048 * has been subclassed to provide additional non-geometric information such as
049 * symbology.
050 *
051 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
052 * @author Martin Desruisseaux (IRD)
053 * @since GeoAPI 1.0
054 *
055 * @see PrimitiveFactory#createPoint
056 *
057 * @todo Some associations are commented out for now.
058 */
059 @UML(identifier="GM_Point", specification=ISO_19107)
060 public interface Point extends Primitive, Position {
061 /**
062 * Returns the direct position of this point. {@code Point} is the only subclass
063 * of {@linkplain Primitive primitive} that cannot use {@linkplain Position positions}
064 * to represent its defining geometry. A {@linkplain Position position} is either a
065 * {@linkplain DirectPosition direct position} or a reference to a {@code Point}
066 * (from which a {@linkplain DirectPosition direct position} may be obtained). By not
067 * allowing {@code Point} to use this technique, infinitely recursive references
068 * are prevented.
069 *
070 * @return The direct position.
071 */
072 @UML(identifier="position", obligation=MANDATORY, specification=ISO_19107)
073 DirectPosition getDirectPosition();
074
075 /**
076 * Sets the direct position of this point. {@code Point} is the only subclass
077 * of {@linkplain Primitive primitive} that cannot use {@linkplain Position positions}
078 * to represent its defining geometry. A {@linkplain Position position} is either a
079 * {@linkplain DirectPosition direct position} or a reference to a {@code Point}
080 * (from which a {@linkplain DirectPosition direct position} may be obtained). By not
081 * allowing {@code Point} to use this technique, infinitely recursive references
082 * are prevented.
083 *
084 * @param position The direct position.
085 * @throws UnmodifiableGeometryException if this geometry is not modifiable.
086 *
087 * @since GeoAPI 2.2
088 */
089 @UML(identifier="position", obligation=MANDATORY, specification=ISO_19107)
090 void setDirectPosition(DirectPosition position) throws UnmodifiableGeometryException;
091
092 /**
093 * @deprecated Renamed as {@link #setDirectPosition} for consistency with {@link #getDirectPosition}.
094 *
095 * @param position The direct position.
096 * @throws UnmodifiableGeometryException if this geometry is not modifiable.
097 */
098 @Deprecated
099 @UML(identifier="position", obligation=MANDATORY, specification=ISO_19107)
100 void setPosition(DirectPosition position) throws UnmodifiableGeometryException;
101
102 /**
103 * Returns always {@code null}, since point has no boundary.
104 *
105 * @return Always {@code null}.
106 */
107 @UML(identifier="boundary", obligation=MANDATORY, specification=ISO_19107)
108 PrimitiveBoundary getBoundary();
109
110 /**
111 * Returns the bearing, as a unit vector, of the tangent (at this {@code Point}) to
112 * the curve between this {@code Point} and a passed {@linkplain Position position}.
113 * The choice of the curve type for defining the bearing is dependent on the
114 * {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}
115 * in which this {@code Point} is defined.
116 * For example, in the Mercator projection, the curve is the rhumb line.
117 * In 3D, geocentric coordinate system, the curve may be the geodesic joining the two
118 * points along the surface of the geoid or ellipsoid in use. Implementations that support
119 * this function shall specify the nature of the curve to be used.
120 *
121 * @param toPoint the destination point.
122 * @return The tangent to the curve between this point and the passed position.
123 */
124 @UML(identifier="bearing", obligation=MANDATORY, specification=ISO_19107)
125 Bearing getBearing(Position toPoint);
126
127 /**
128 * Returns always {@code null}, since points have no proxy.
129 *
130 * @issue http://jira.codehaus.org/browse/GEO-63
131 */
132 @Association("Oriented")
133 @UML(identifier="proxy", obligation=FORBIDDEN, specification=ISO_19107)
134 OrientablePrimitive[] getProxy();
135
136 // public org.opengis.geometry.complex.GM_CompositePoint composite[];
137 }