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.coordinate;
033
034 import java.util.List;
035 import org.opengis.geometry.DirectPosition;
036 import org.opengis.referencing.crs.CoordinateReferenceSystem;
037 import org.opengis.annotation.UML;
038 import org.opengis.annotation.Extension;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * A sequence of points.
046 * <p>
047 * The {@code PointArray} interface outlines a means of efficiently storing large numbers of usually
048 * homogeneous {@linkplain Position positions}; i.e. all having the same
049 * {@linkplain CoordinateReferenceSystem coordinate reference system}. While a point array
050 * conceptually contains {@linkplain Position positions}, it provides convenience methods for
051 * fetching directly the {@linkplain DirectPosition direct positions} instead.
052 * <p>
053 * A simple implementation of {@code PointArray} will generally be no more efficient than a simple
054 * array of {@link Position}s. More efficient implementations may store coordinates in a more
055 * compact form (e.g. in a single {@code float[]} array) and creates {@link Position} objects on the
056 * fly when needed.
057 * <p>
058 * If a particular {@code PointArray} implementation supports efficiently random access through any
059 * {@code get} or {@code set} method, it shall announce this capability by implementing the
060 * {@link java.util.RandomAccess} interface. Otherwise, users should read the positions through the
061 * {@link #iterator() iterator()} instead.
062 *
063 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
064 * @author Martin Desruisseaux (IRD)
065 * @since GeoAPI 1.0
066 *
067 * @see Position
068 * @see PointGrid
069 */
070 @UML(identifier="GM_PointArray", specification=ISO_19107)
071 public interface PointArray extends List<Position> {
072 /**
073 * Returns the length (the number of elements) of this array. This is equivalent to
074 * <code>{@linkplain #positions positions}().{@linkplain List#size size}()</code>.
075 *
076 * @deprecated Please use {@link #size()}
077 *
078 * @return The array length.
079 *
080 * @see List#size
081 * @see PointGrid#width
082 */
083 @Extension
084 @Deprecated
085 int length();
086
087 /**
088 * Returns the dimensionality of the coordinates in this array. It should be equals to the
089 * dimensionality of the {@linkplain #getCoordinateReferenceSystem() coordinate reference system}
090 * for these coordinates.
091 * <p>
092 * This method is the same as:
093 *
094 * <blockquote><pre>
095 * return getCoordinateReferenceSystem().getCoordinateSystem().getDimension();
096 * </pre></blockquote>
097 *
098 * @return the dimensionality of this array.
099 * @see DirectPosition#getDimension
100 */
101 @Extension
102 int getDimension();
103
104 /**
105 * Returns the Coordinate Reference System in which the coordinates are given. May be
106 * {@code null} if this particular {@code PointArray} is included in a larger object with such a
107 * reference to a coordinate reference system}. In this case, the cordinate reference system is
108 * implicitly assumed to take on the value of the containing object's coordinate reference
109 * system.
110 *
111 * @return The coordinate reference system, or {@code null}.
112 * @see DirectPosition#getCoordinateReferenceSystem
113 */
114 @Extension
115 CoordinateReferenceSystem getCoordinateReferenceSystem();
116
117 /**
118 * Gets a copy of the {@linkplain DirectPosition direct position} at the particular location in
119 * this {@code PointArray}. If the {@code dest} argument is non-null, that object will be
120 * populated with the value from the array. In all cases, the position in insulated from changes
121 * in the {@code PointArray}, and vice-versa. Consequently, the same {@code DirectPosition}
122 * object can be reused for fetching many points from this array. Example:
123 *
124 * <blockquote><pre>
125 * DirectPosition position = null;
126 * final int length = array.length();
127 * for (int i=0; i<length; i++) {
128 * position = array.getDirectPosition(i, position);
129 * // Do some processing...
130 * }
131 * </pre></blockquote>
132 *
133 * @param index The location in the array, from 0 inclusive to the array
134 * {@linkplain #length length} exclusive.
135 * @param dest An optionnaly pre-allocated direct position.
136 * @return The {@code dest} argument, or a new object if {@code dest} was null.
137 * @throws IndexOutOfBoundsException if the index is out of bounds.
138 */
139 @Extension
140 DirectPosition getDirectPosition(int index, DirectPosition dest) throws IndexOutOfBoundsException;
141
142 /**
143 * Sets the point at the given index. The point coordinates will be copied, i.e. changes to the
144 * given {@code position} after this method call will not be reflected into this point array.
145 * Consequently, the same {@code DirectPosition} object can be reused for setting many points in
146 * this array.
147 *
148 * @param index The location in the array, from 0 inclusive to the array
149 * {@linkplain #length length} exclusive.
150 * @param position The point to set at the given location in this array.
151 * @throws IndexOutOfBoundsException if the index is out of bounds.
152 * @throws UnsupportedOperationException if this array is immutable.
153 *
154 * @see List#set
155 */
156 @Extension
157 void setDirectPosition(int index, DirectPosition position)
158 throws IndexOutOfBoundsException, UnsupportedOperationException;
159
160 /**
161 * Returns a view of the points in this array as a list of {@linkplain Position positions}. The
162 * list is backed by this {@code PointArray}, so changes to the point array are reflected in
163 * the list, and vice-versa.
164 * <p>
165 * Note that random access may be costly in some implementations. If the returned list doesn't
166 * implement the {@link java.util.RandomAccess} interface, then consider avoiding the
167 * {@link List#get(int)} method. Favor the {@linkplain List#iterator list iterator} instead.
168 *
169 * @deprecated use <b>this</b>
170 * @return The list of positions in this array.
171 */
172 @Deprecated
173 @UML(identifier="column", obligation=MANDATORY, specification=ISO_19107)
174 List<Position> positions();
175 }