001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-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.feature.simple;
033
034 import java.util.List;
035
036 import org.opengis.feature.ComplexAttribute;
037 import org.opengis.feature.Feature;
038 import org.opengis.feature.type.Name;
039
040 /**
041 * An instance of {@link SimpleFeature} composed of fixed list values in a known order.
042 * <p>
043 * The definition of a "simple feature" can be summed up as the following:
044 * <ul>
045 * <li>made up of only non-complex attributes, no associations
046 * <li>attributes are of multiplicity 1
047 * <li>attributes are ordered
048 * <li>attribute names are unqualified (namespaceURI == null)
049 * </ul>
050 * </p>
051 * <p>
052 * <h3>Attribute Access</h3>
053 * The order and multiplicity restrictions on simple feature make attribute
054 * values accessible via an index. For example consider the following shapefile
055 * entry:
056 * <pre>
057 * | GEOMETRY | INT | STRING |
058 * |POINT(0 0)| 0 | "zero" |
059 * </pre>
060 * Accessing attributes via index would look like:
061 * <pre>
062 * SimpleFeature feature = ...;
063 *
064 * Geometry g = (Geometry) feature.getAttribute( 0 );
065 * Integer i = (Integer) feature.getAttribute( 1 );
066 * String s = (String) feature.getAttribute( 2 );
067 * </pre>
068 * One could also access by name:
069 * <pre>
070 * SimpleFeature feature = ...;
071 *
072 * Geometry g = (Geometry) feature.getAttribute( "GEOMETRY" );
073 * Integer i = (Integer) feature.getAttribute( "INT" );
074 * String s = (String) feature.getAttribute( "STRING" );
075 * </pre>
076 * </p>
077 * <p>
078 * <b>Note:</b> Attribute access via getAttribute() methods returns attribute
079 * values, and not the attributes themselves. For access to the actual attributes
080 * {@link ComplexAttribute#getProperty(String)} can be used.
081 * </p>
082 *
083 * @see SimpleFeatureType
084 *
085 * @author Jody Garnett (Refractions Research)
086 * @author Justin Deoliveira (The Open Planning Project)
087 */
088 public interface SimpleFeature extends Feature {
089 /**
090 * Unique Identifier for the SimpleFeature
091 * <p>
092 * This value is non-null and should be the same as getIdentifier().toString().
093 * Please note that an ID may be provided
094 * </p>
095 *
096 * @return A unique identifier for the attribute, or <code>null</code> if
097 * the attribute is non-identifiable.
098 */
099 String getID();
100
101 /**
102 * Override and type narrow to SimpleFeatureType.
103 */
104 SimpleFeatureType getType();
105
106 /**
107 * The type of the feature.
108 * <p>
109 * This method is a synonym for {@link #getType()}.
110 * </p>
111 * @see #getType()
112 */
113 SimpleFeatureType getFeatureType();
114
115 /**
116 * Returns a list of the values of the attributes contained by the feature.
117 * <br>
118 * <p>
119 * This method is a convenience for:
120 * <pre>
121 * List values = new ArrayList();
122 * for ( Property p : getProperties(); ) {
123 * values.add( p.getValue() );
124 * }
125 *
126 * return values;
127 * </pre>
128 * </p>
129 *
130 * @return List of attribute values for the feature.
131 */
132 List<Object> getAttributes();
133
134 /**
135 * Sets the values of the attributes contained by the feature.
136 * <p>
137 * The <tt>values</tt> must be in the order of the attributes defined by the
138 * feature type.
139 * </p>
140 * <p>
141 * This method is a convenience for:
142 * <pre>
143 * int i = 0;
144 * for ( Property p : getProperties() ) {
145 * p.setValue( values.get( i++ ) );
146 * }
147 * </pre>
148 * </p>
149 * @param values The attribute values to set.
150 */
151 void setAttributes( List<Object> values );
152
153 /**
154 * Sets the values of the attributes contained by the feature.
155 * <p>
156 * The <tt>values</tt> must be in the order of the attributes defined by the
157 * feature type.
158 * </p>
159 * <p>
160 * This method is a convenience for:
161 * <pre>
162 * for ( Property p : getProperties() ) {
163 * p.setValue( values[i] );
164 * }
165 * </pre>
166 * </p>
167 * @param values The attribute values to set.
168 */
169 void setAttributes( Object[] values );
170
171 /**
172 * Gets an attribute value by name.
173 * <p>
174 * This method is a convenience for:
175 * <pre>
176 * Property p = getProperty( name );
177 * return p.getValue();
178 * </pre>
179 * </p>
180 * @param name The name of the attribute whose value to retrieve.
181 *
182 * @return The attribute value, or <code>null</code> if no such attribute
183 * exists with the specified name.
184 */
185 Object getAttribute( String name );
186
187 /**
188 * Sets an attribute value by name.
189 * <p>
190 * This method is a convenience for:
191 * <pre>
192 * Property p = getProperty( name );
193 * p.setValue(value);
194 * </pre>
195 * </p>
196 * @param name The name of the attribute whose value to set.
197 * @param value The new value of the attribute.
198 */
199 void setAttribute( String name, Object value );
200
201 /**
202 * Gets an attribute value by name.
203 * <p>
204 * This method is a convenience for:
205 * <pre>
206 * Property p = getProperty( name );
207 * return p.getValue();
208 * </pre>
209 * </p>
210 * <p>
211 * Since attribute names in simple features do not have a namespace uri
212 * this method is equivalent to calling <code>getAttribute(name.getLocalPart())</code>.
213 * </p>
214 * @param name The name of the attribute whose value to retrieve.
215 *
216 * @return The attribute value, or <code>null</code> if no such attribute
217 * exists with the specified name.
218 */
219 Object getAttribute( Name name );
220
221 /**
222 * Sets an attribute value by name.
223 * <p>
224 * This method is a convenience for:
225 * <pre>
226 * Property p = getProperty( name );
227 * p.setValue(value);
228 * </pre>
229 * </p>
230 * <p>
231 * Since attribute names in simple features do not have a namespace uri
232 * this method is equivalent to calling <code>setAttribute(name.getLocalPart(), value)</code>.
233 * </p>
234 * @param name The name of the attribute whose value to set.
235 * @param value The new value of the attribute.
236 */
237 void setAttribute( Name name, Object value );
238
239 /**
240 * Gets an attribute value by index.
241 * <p>
242 * This method is a convenience for:
243 * <pre>
244 * Property p = ((List)getProperties()).get( i ) ;
245 * return p.getValue();
246 * </pre>
247 * </p>
248 * @param index The index of the attribute whose value to get.
249 *
250 * @return The attribute value at the specified index.
251 * @throws IndexOutOfBoundsException If the specified index is out of bounds.
252 */
253 Object getAttribute( int index ) throws IndexOutOfBoundsException;
254
255 /**
256 * Sets an attribute value by index.
257 * <p>
258 * This method is a convenience for:
259 * <pre>
260 * Property p = ((List)getProperties()).get( i ) ;
261 * p.setValue(value);
262 * </pre>
263 * </p>
264 * @param index The index of the attribute whose value to set.
265 * @param value The new value of the attribute.
266 *
267 * @throws IndexOutOfBoundsException If the specified index is out of bounds.
268 */
269 void setAttribute( int index, Object value ) throws IndexOutOfBoundsException;
270
271 /**
272 * The number of attributes the feature is composed of.
273 * <p>
274 * This is a convenience for:
275 * <pre>
276 * return getAttributes().size();
277 * </pre>
278 * </p>
279 * @return Number of attributes of the feature.
280 */
281 int getAttributeCount();
282
283 /**
284 * Returns the value of the default geometry of the feature.
285 * <p>
286 * This method is convenience for:
287 * <pre>
288 * return getDefaultGeometry().getValue();
289 * </pre>
290 * </p>
291 * @return The default geometry, or <code>null</code> if no default geometry
292 * attribute exists.
293 *
294 */
295 Object getDefaultGeometry();
296
297 /**
298 * Sets the value of the default geometry for the feature.
299 * <p>
300 * This method is convenience for:
301 * <pre>
302 * getDefaultGeometry().setValue(geometry);
303 * </pre>
304 * </p>
305 * @param geometry The new default geometry value.
306 */
307 void setDefaultGeometry(Object geometry);
308 }