org.geotools.feature
Interface SimpleFeature

All Superinterfaces:

Feature

All Known Implementing Classes:

DefaultFeature

public interface SimpleFeature

extends Feature

A simple feature is one that does not have any nested attributes, and that has no multiplicity for each attribute. In non xml speak this means that the attributes returned are guaranteed to be the Objects you would expect - not Lists as is the case when Features are non-simple. This is thus a constraining extension - it essentially allows you to make a few more assumptions about the nature of the Feature you are getting back.

The notion of a Simple Feature is drawn from the OGC's Simple Features for SQL specification - where a simple feature represents a single row in a database table. This extends beyond databases though, to flat files, for example. A database does not necessarily only return simple features - indeed by relying on foreign keys much more complex structures can be created. But at the time of the creation of this class all GeoTools datastores return Simple Features - they just were not explicitly called that. Making explicit that they are Simple should hopefully encourage more complex Features to be returned.

The assumptions one can make with Simple Features are as follows:

• If getAttribute(int) is called then it will always return an actual object, instead of a List, as is common in the parent Feature class. That is to say a Simple Feature will never have more than one attribute in any of its positions, so the interface just assumes that you want the actual object, instead of a List containing just the object.
• If setAttribute(int, Object) is called then a similar assumption is made about the object being set - it need be a List, will default to setting the attribute itself.
• getAttribute(String) and Feature.setAttribute(String, Object) implicitly append a [0], as that's the behavior implementors expect - to name an attribute and get it back.

To figure out if a Feature is a SimpleFeature one may call instanceof. For a number of Features returned from a DataStore it will save much energy if instanceof is called on the FeatureType, to check if it is a SimpleFeatureType. And in the future we should have FeatureCollections that know their types.

Since:

2.1

Version:

$Id: SimpleFeature.java 17701 2006-01-23 00:00:51Z desruisseaux $

Author:

David Zwiers, Refractions, Chris Holmes, TOPP

Task:

REVISIT: I am not sure that I like getAttribute returning the object straight away. It might be better to have a getFirstAttribute() method in Feature.java, and move people to get used to calling that, or else to expect a List (which in a SimpleFeature would always only contain one Object). This would seem to make the api a bit cleaner in my mind.

Nested Class Summary

Nested classes inherited from class org.geotools.feature.Feature

Feature.NULL

Method Summary

java.lang.Object	getAttribute(int index) Gets an attribute by the given zero-based index.
java.lang.Object	getAttribute(java.lang.String xPath) This is the same as the parent declaration, except that when the instance is not specified for the xPath, [0] will be added as there is only ever one Attribute value for an AttributeType
FeatureType	getFeatureType() Gets a reference to the schema for this feature.
void	setAttribute(int position, java.lang.Object val) Sets an attribute by the given zero-based index.
void	setAttributes(java.lang.Object[] attributes) Sets all attributes for this feature, passed as a complex object array.

Methods inherited from interface org.geotools.feature.Feature

getAttributes, getBounds, getDefaultGeometry, getID, getNumberOfAttributes, getParent, setAttribute, setDefaultGeometry, setParent

Method Detail

getFeatureType

public FeatureType getFeatureType()

Gets a reference to the schema for this feature. This method should always return DefaultFeatureType Object. This will be explicitly posible in Java 1.5 (dz)

Specified by:

getFeatureType in interface Feature

Returns:

A reference to this simple feature's schema.

setAttributes

public void setAttributes(java.lang.Object[] attributes)
                   throws IllegalAttributeException

Sets all attributes for this feature, passed as a complex object array. Note that this array must conform to the internal schema for this feature, or it will throw an exception. Checking this is, of course, left to the feature to do internally. Well behaved features should always fully check the passed attributes against thier schema before adding them. Since this is a SimpleFeature, the number of attributes will be exactly the same as the number of attribute types. Attribute values will be paired with attribute types based on array indexes.

Parameters:

attributes - All feature attributes.

Throws:

IllegalAttributeException - Passed attributes do not match schema.

getAttribute

public java.lang.Object getAttribute(java.lang.String xPath)

This is the same as the parent declaration, except that when the instance is not specified for the xPath, [0] will be added as there is only ever one Attribute value for an AttributeType

Specified by:

getAttribute in interface Feature

Parameters:

xPath - XPath representation of attribute location.

Returns:

A copy of the requested attribute, null if the requested xpath is not found, or NULL_ATTRIBUTE.

See Also:

Feature.getAttribute(String)

getAttribute

public java.lang.Object getAttribute(int index)

Gets an attribute by the given zero-based index. Unlike the parent interface, this index is guaranteed to match the index of AttributeType in the FeatureType.

Specified by:

getAttribute in interface Feature

Parameters:

index - The requested index. Must be 0 <= idx < getNumberOfAttributes().

Returns:

A copy of the requested attribute, or NULL_ATTRIBUTE.

See Also:

Feature.getAttribute(String)

setAttribute

public void setAttribute(int position,
                         java.lang.Object val)
                  throws IllegalAttributeException,
                         java.lang.ArrayIndexOutOfBoundsException

Sets an attribute by the given zero-based index. Unlike the parent interface, this index is guaranteed to match the index of AttributeType in the FeatureType.

Specified by:

setAttribute in interface Feature

Parameters:

position - The requested index. Must be 0 <= idx < getNumberOfAttributes()

val - An object representing the attribute being set

Throws:

IllegalAttributeException - if the passed in val does not validate against the AttributeType at that position.

java.lang.ArrayIndexOutOfBoundsException - if an invalid position is given

See Also:

Feature.setAttribute(String, Object)