org.opengis.feature

Interface Feature

All Known Subinterfaces:

FeatureCollection

public interface Feature

Represents a feature of arbitrary complexity. The FeatureType and Feature interfaces also work together to give implementers a framework for constraining and enforcing constraints (respectively) on allowed feature types.

Notes for Feature Clients:
Clients should always use feature accessor methods (getAttribute(java.lang.String) and setAttribute(java.lang.String, java.lang.Object)) to modify the state of internal attribute objects. It is possible that some feature implementations will allow object state changes by clients outside of the class, but this is strongly discouraged. In general, feature implementations will make defensive copies of objects passed to clients and it is therefore not guaranteed that client state changes that take place outside of the feature will be reflected in the internal state of the feature object. For this reason, clients should always use the set methods to change feature attribute object states.

Notes for Feature Implementers:
It is the responsibility of the implementing class to ensure that the Feature attributes stay synchronized with its FeatureType definition. Features should never get out of synch with their declared schemas and should never alter their schemas. There are four conventions of which implementers of this interface must be aware in order to successfully manage a Feature:

• FeatureType Reference
  Features must always hold a single (immutable: see FeatureType) schema reference and this reference should not be altered after a feature has been created. To ensure this, is is recommended that features take a valid reference to an existing immutable schema in its constructor and declare that reference final.

• Default Geometry
  Each feature must have a default geometry, but this primary geometry may be null. This means that a feature may contain no geometries, but it must always have a method for accessing a geometry object (even if it is null). It also means that a feature with multiple geometries must pick one as its default geometry. Note that the designation of the default geometry is stored as part of the FeatureType and is therefore immmutable.

• Attributes
  All features contain zero or more attributes, which can have one or more occurrences inside the feature. Attributes may be any valid Java object. If attributes are instances of Feature, they are handled specially by the Feature methods, in that their attributes may be accessed directly by their containing feature. All other object variables and methods must be accessed through the objects themselves. It is up to implementers of Feature to make sure that each attribute value conforms to its internal schema. A feature should never reach a state where its attributes (or sub-attributes) do not conform to their FeatureType definitions.

• Constructors
  Constructors should take arguments with enough information to create a valid representation of the feature. They should also always include a valid schema that can be used to check the proposed attributes. This is necessary to ensure that the feature is always in a valid state, relative to its schema.

• hashCode() and equals(Object)
  Determining equality and equivalence for Feature instances is of utmost importance. This must be done in a consistent manner, as many implementations will rely on these relations. See Object for details.

Since:

GeoAPI 2.0

Method Summary

Modifier and Type	Method and Description
java.lang.Object	getAttribute(int index) Returns the value of the indexed attribute of this Feature.
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the named attribute of this Feature.
Envelope	getBounds() Returns the extent of the geometries of this feature.
FeatureType	getFeatureType() Returns the description of this feature's type.
java.lang.String	getID() Returns a String that uniquely identifies this Feature instance with this Java virtual machine (and perhaps uniquely in a broader scope as well).
FeatureCollection	getParent() Returns the collection in which we are contained.
void	setAttribute(int index, java.lang.Object value) Sets the value of the given attribute.
void	setAttribute(java.lang.String name, java.lang.Object value) Sets the value of the named attribute.

Method Detail

getFeatureType

FeatureType getFeatureType()

Returns the description of this feature's type.

getAttribute

java.lang.Object getAttribute(java.lang.String name)
                       throws java.lang.IllegalArgumentException

Returns the value of the named attribute of this Feature. If the maximum cardinality of this attribute is one, then this method returns the value of the attribute. Otherwise, if the maximum cardinality of this attribute is greater than one, then this method will return an instance of Collection.

Parameters:

name - The name of the feature attribute to retrieve.

Throws:

java.lang.IllegalArgumentException - If an attribute of the given name does not exist in this feature's type.

getBounds

Envelope getBounds()

Returns the extent of the geometries of this feature. Can return null if the extent is not known, not easy to calculate, or this feature has no geometry.

getAttribute

java.lang.Object getAttribute(int index)
                       throws java.lang.IndexOutOfBoundsException

Returns the value of the indexed attribute of this Feature. If the maximum cardinality of this attribute is one, then this method returns the value of the attribute. Otherwise, if the maximum cardinality of this attribute is greater than one, then this method will return an instance of Collection.

Parameters:

index - The index of the feature attribute to retrieve. This index is the same as the index of the corresponding FeatureAttributeDescriptor in the list returned by FeatureType.getAttributeDescriptors().

Throws:

java.lang.IndexOutOfBoundsException - If the index is negative or greater than the number of possible attributes minus one.

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.Object value)
           throws java.lang.IllegalArgumentException,
                  java.lang.ClassCastException

Sets the value of the named attribute. The value can either be a single object, if the maximum cardinality of the given attribute is one, or the value can be an instance of Collection if the attribute's maximum cardinality is greater than one.

Parameters:

name - The name of the attribute whose value to set.

value - The new value of the given attribute.

Throws:

java.lang.IllegalArgumentException - If value is a collection (other than a singleton) and it's a single-valued attribute, or if the given name does not match any of the attributes of this feature.

java.lang.ClassCastException - If the attribute type is a type other than Object in the FeatureType and an incorrect type is passed in.

setAttribute

void setAttribute(int index,
                  java.lang.Object value)
           throws java.lang.IndexOutOfBoundsException,
                  java.lang.IllegalArgumentException,
                  java.lang.ClassCastException

Sets the value of the given attribute. The value can either be a single object, if the maximum cardinality of the given attribute is one, or the value can be an instance of Collection if the attribute's maximum cardinality is greater than one.

Parameters:

index - Zero based index of the attribute to set.

value - The new value of the given attribute.

Throws:

java.lang.IndexOutOfBoundsException - if the index is negative or greater than the number of attributes of this feature minute one.

java.lang.IllegalArgumentException - If value is a collection (other than a singleton) and it's a single-valued attribute.

java.lang.ClassCastException - If the attribute type is a type other than Object in the FeatureType and an incorrect type is passed in.

getID

java.lang.String getID()

Returns a String that uniquely identifies this Feature instance with this Java virtual machine (and perhaps uniquely in a broader scope as well). This value is not necessarily one of the attributes of this feature. Some features may implement this method by concatenating this feature's type name with the String values of all of the primary key attributes. (This is only a suggestion, however, and a given Feature implementation may choose to compute the ID in whatever way makes sense.)

getParent

FeatureCollection getParent()

Returns the collection in which we are contained.