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.type.AttributeDescriptor;
037 import org.opengis.feature.type.AttributeType;
038 import org.opengis.feature.type.FeatureType;
039 import org.opengis.feature.type.Name;
040
041 /**
042 * The type of a SimpleFeature.
043 * <p>
044 * The definition of a "simple feature" can be summed up as the following:
045 * <ul>
046 * <li>made up of only non-complex attributes, no associations
047 * <li>attributes are of multiplicity 1
048 * <li>attributes are ordered
049 * <li>attribute names are unqualified (namespaceURI == null)
050 * </ul>
051 * </p>
052 * <p>
053 * <h3>Attribute Indexing</h3>
054 * The attributes which compose a simple feature type are ordered. For this
055 * reason attributes are available via a simple index. Given the following type
056 * definition:
057 *
058 * <pre>
059 * <complexType name="mySimpleType"/>
060 * <sequence>
061 * <element name="foo" type="xs:string"/>
062 * <element name="bar" type="xs:integer"/>
063 * </sequence>
064 * </complexType>
065 * </pre>
066 *
067 * <br>
068 * The attribute descriptor are addressable via index:
069 *
070 * <pre>
071 * SimpleFeatureType type = ...;
072 *
073 * AttributeDescriptor foo = type.getAttribute( 0 );
074 * AttributeDescriptor bar-= type.getAttribute( 1 );
075 * </pre>
076 *
077 * <p>
078 * <h3>Attribute Multiplicity</h3>
079 * With simple feature types, the multiplicity of attributes is always assumed
080 * to be 1, ie, <code>getMinOccurs() == 1</code> and
081 * <code>getMaxOccurs() == 1</code>. A consequence of this is that attributes
082 * from a simple feature always line up 1 to 1 with the descriptors from the
083 * type:
084 *
085 * <pre>
086 * SimpleFeature feature = ...;
087 * SimpleFeatureType type = feature.getType();
088 *
089 * type.getAttribute( 0 ).getDescriptor() == type.getAttribute( 0 );
090 * type.getAttribute( 1 ).getDescriptor() == type.getAttribute( 1 );
091 * </pre>
092 *
093 * </p>
094 *
095 * <p>
096 * <h3>Attribute Naming</h3>
097 * The names of attributes in a simple feature type are never namespace
098 * qualified. For this reason there is no difference between accessing an
099 * attribute with {@link #getDescriptor(String)} and {@link #getDescriptor(Name)}.
100 * </p>
101 *
102 * @author Jody Garnett, Refractions Research
103 * @author Justin Deoliveira, The Open Planning Project
104 */
105 public interface SimpleFeatureType extends FeatureType {
106
107 /**
108 * The local name for this FeatureType.
109 *
110 * Specifically this method returns <code>getName().getLocalPart().</code>
111 * @return The local name for this FeatureType.
112 */
113 String getTypeName();
114
115 /**
116 * The list of attribute descriptors which make up the feature type.
117 * <p>
118 * This method is a convenience for:
119 *
120 * <pre>
121 * return (List<AttributeDescriptor>) getProperties();
122 * </pre>
123 *
124 * </p>
125 *
126 * @return The ordered list of attribute descriptors.
127 */
128 List<AttributeDescriptor> getAttributeDescriptors();
129
130 /**
131 * Returns the attribute descriptor which matches the specified name.
132 * <p>
133 * This method is convenience for:
134 *
135 * <pre>
136 * return (AttributeDescriptor) getProperty(name);
137 * </pre>
138 *
139 * </p>
140 * <p>
141 * This method returns <code>null</code> if no such attribute exists.
142 * </p>
143 *
144 * @param name
145 * The name of the descriptor to return.
146 *
147 * @return The attribute descriptor matching the specified name, or
148 * <code>null</code> if no such attribute exists.
149 */
150 AttributeDescriptor getDescriptor(String name);
151
152 /**
153 * Returns the attribute descriptor which matches the specified name.
154 * <p>
155 * This method is convenience for:
156 *
157 * <pre>
158 * return (AttributeDescriptor) getProperty(name);
159 * </pre>
160 *
161 * </p>
162 * <p>
163 * This method returns <code>null</code> if no such attribute exists.
164 * </p>
165 *
166 * @param name
167 * The name of the descriptor to return.
168 *
169 * @return The attribute descriptor matching the specified name, or
170 * <code>null</code> if no such attribute exists.
171 */
172 AttributeDescriptor getDescriptor(Name name);
173
174 /**
175 * Returns the attribute descriptor at the specified index.
176 * <p>
177 * This method is convenience for:
178 *
179 * <pre>
180 * return (AttributeDescriptor) ((List) getProperties()).get(index);
181 * </pre>
182 *
183 * </p>
184 *
185 * @param name
186 * The name of the descriptor to return.
187 *
188 * @return The attribute descriptor at the specified index.
189 *
190 * @throws IndexOutOfBoundsException
191 * When the index is out of bounds.
192 */
193 AttributeDescriptor getDescriptor(int index)
194 throws IndexOutOfBoundsException;
195
196 /**
197 * Returns the number of attributes composing the feature type
198 * <p>
199 * This method is convenience for <code>getAttributes().size()</code>.
200 * </p>
201 * @return The number of attributes.
202 */
203 int getAttributeCount();
204
205 /**
206 * Returns the types of all the attributes which make up the feature.
207 * <p>
208 * This method is convenience for:
209 *
210 * <pre>
211 * List types = new ArrayList();
212 * for (Property p : getProperties()) {
213 * types.add(p.getType());
214 * }
215 * return types;
216 * </pre>
217 *
218 * </p>
219 *
220 * @return The list of attribute types.
221 */
222 List<AttributeType> getTypes();
223
224 /**
225 * Returns the type of the attribute which matches the specified name.
226 * <p>
227 * This method is convenience for:
228 *
229 * <pre>
230 * return (AttributeType) getProperty(name).getType();
231 * </pre>
232 *
233 * </p>
234 * <p>
235 * If there is no such attribute which matches <tt>name</tt>,
236 * <code>null</code> is returned.
237 * </p>
238 *
239 * @param name
240 * The name of the attribute whose type to return.
241 *
242 * @return The attribute type matching the specified name, or
243 * <code>null</code>.
244 */
245 AttributeType getType(String name);
246
247 /**
248 * Returns the type of the attribute which matches the specified name.
249 * <p>
250 * This method is convenience for:
251 *
252 * <pre>
253 * return (AttributeType) getProperty(name).getType();
254 * </pre>
255 *
256 * </p>
257 * <p>
258 * If there is no such attribute which matches <tt>name</tt>,
259 * <code>null</code> is returned.
260 * </p>
261 *
262 * @param name
263 * The name of the attribute whose type to return.
264 *
265 * @return The attribute type matching the specified name, or
266 * <code>null</code>.
267 */
268 AttributeType getType(Name name);
269
270 /**
271 * Returns the type of the attribute at the specified index.
272 * <p>
273 * This method is convenience for:
274 *
275 * <pre>
276 * return (AttributeType)((List)getProperties()).get(index)).getType();
277 * </pre>
278 *
279 * </p>
280 *
281 * @param index
282 * The index of the attribute whose type to return.
283 *
284 * @return The attribute type at the specified index.
285 *
286 * @throws IndexOutOfBoundsException
287 * When the index is out of bounds.
288 */
289 AttributeType getType(int index) throws IndexOutOfBoundsException;
290
291 /**
292 * Returns the index of the attribute which matches the specified name.
293 * <p>
294 * -1 is returned in the instance there is no attribute matching the
295 * specified name.
296 * </p>
297 *
298 * @param name
299 * The name of the attribute whose index to return.
300 *
301 * @return index of named attribute, or -1 if not found.
302 */
303 int indexOf(String name);
304
305 /**
306 * Returns the index of the attribute which matches the specified name.
307 * <p>
308 * -1 is returned in the instance there is no attribute matching the
309 * specified name.
310 * </p>
311 *
312 * @param name
313 * The name of the attribute whose index to return.
314 *
315 * @return index of named attribute, or -1 if not found.
316 */
317 int indexOf(Name name);
318 }