|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
SimpleFeature
.
public interface Feature
Represents a feature of arbitrary complexity.
This interface answers the question: How do we store feature attributes? (The answer to the more useful question, How do we access feature attribute, is contained in the Expression class.
Warning: We are revising the Feature Model to be more complete in the next round of GeoTools. If you do any data access in your classes please try and make use of Expression to access your information, if you do this you will not be affected by the change (beyond a few search and replace operations).
The most generic approach would be to pass all feature attributes as objects and use Java variable and method references to access them. However, this is also the most useless approach because it establishes no unified methods for getting attribute information (since it is totally Object dependent), without elaborate reflection/introspection, which is inconvenient to use. Unlike itsFeatureType
counterpart, this interface does not attempt to
serve as a typing framework. Rather, multiple implementations of this
interface should generally be for performance reasons.
This interface serves two important purposes. Most obviously, it gives
users of features a unified, consistent framework for accessing and
manipulating feature data. Perhaps more importantly, the
FeatureType
and Feature
interfaces also work
together to give implementers a framework for constraining and enforcing
constraints (respectively) on allowed feature types. As such, this
interface is as general as possible in terms of the types of objects to
which it provides access. Keep in mind that creating new features is
relatively difficult and should only be done to optimize performance for
highly constrained schema types. For the vast majority of schemas, the
generic feature implementation will work fine.
Notes for Feature Clients:
Clients should always use feature accessor methods (getAttribute and
setAttribute) 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
) schema reference and this reference should not be
altered after a feature has been created. To ensure this, is is strongly
recommended that features take a valid reference to an existing immutable
schema in its constructor and declare that reference final.
FeatureType
and is therefore immmutable.
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. There are three
ways to implement this. The first is to simply make features immutable;
however, given the ubiquity and required flexibility of features, this is
likely not possible. The second (and second easiest), is to make all
feature attributes immutable. For most cases, this is probably the best way
to handle this issue. The third way, is to never give out a reference that
would allow a client to change an attribute object's class (most obviously,
an array reference). Generally speaking, features should attempt to
minimize external object references by attempting to clone incoming
attributes before adding them and outgoing attributes before sending them.
For features with non-cloneable attributes, of course, this is not
possible, so this is left to the discretion of the implementor.
FeatureType
,
DefaultFeature
modules/library/legacy (gt-legacy.jar)
Nested Class Summary | |
---|---|
static class |
Feature.NULL
Deprecated. Not straight forward, this is a "null" object to represent the value null for a given attribute which is nullable. |
Method Summary | |
---|---|
Object |
getAttribute(int index)
Deprecated. Gets an attribute by the given zero-based index. |
Object |
getAttribute(String xPath)
Deprecated. Gets an attribute for this feature at the location specified by xPath. |
Object[] |
getAttributes(Object[] attributes)
Deprecated. Copy all the attributes of this Feature into the given array. |
ReferencedEnvelope |
getBounds()
Deprecated. Get the total bounds of this feature which is calculated by doing a union of the bounds of each geometry this feature is associated with. |
Geometry |
getDefaultGeometry()
Deprecated. Gets the default geometry for this feature. |
FeatureType |
getFeatureType()
Deprecated. Gets a reference to the schema for this feature. |
String |
getID()
Deprecated. Gets the unique feature ID for this feature. |
int |
getNumberOfAttributes()
Deprecated. Get the number of attributes this feature has. |
void |
setAttribute(int position,
Object val)
Deprecated. Sets an attribute by the given zero-based index. |
void |
setAttribute(String xPath,
Object attribute)
Deprecated. Sets a single attribute for this feature, passed as a complex object. |
void |
setDefaultGeometry(Geometry geometry)
Deprecated. Sets the default geometry for this feature. |
Methods inherited from interface SimpleFeature |
---|
getAttribute, getAttributeCount, getAttributes, getType, setAttribute, setAttributes, setAttributes, setDefaultGeometry |
Methods inherited from interface Feature |
---|
getDefaultGeometryProperty, getIdentifier, setDefaultGeometryProperty |
Methods inherited from interface ComplexAttribute |
---|
getProperties, getProperties, getProperties, getProperty, getProperty, getValue, setValue, validate |
Methods inherited from interface Attribute |
---|
getDescriptor |
Methods inherited from interface Property |
---|
getName, getUserData, isNillable, setValue |
Method Detail |
---|
FeatureType getFeatureType()
getFeatureType
in interface SimpleFeature
String getID()
getID
in interface SimpleFeature
Object[] getAttributes(Object[] attributes)
attributes
- An array to copy attributes into. May be null.
Object getAttribute(String xPath)
getAttribute
in interface SimpleFeature
xPath
- XPath representation of attribute location.
Object getAttribute(int index)
getAttribute
in interface SimpleFeature
index
- The requested index. Must be 0 <= idx <
getNumberOfAttributes().
getAttribute(String)
void setAttribute(int position, Object val)
setAttribute
in interface SimpleFeature
position
- The requested index. Must be 0 <= idx <
getNumberOfAttributes()val
- An object representing the attribute being set
IllegalAttributeException
- if the passed in val does not validate
against the AttributeType at that position.
ArrayIndexOutOfBoundsException
- if an invalid position is givensetAttribute(String, Object)
int getNumberOfAttributes()
void setAttribute(String xPath, Object attribute) throws IllegalAttributeException
setAttribute
in interface SimpleFeature
xPath
- XPath representation of attribute location.attribute
- Feature attribute to set.
IllegalAttributeException
- If the attribute is illegal for the
path specified.Geometry getDefaultGeometry()
This method will return null
if no DefaultGeometry has been
defined by the schema.
getDefaultGeometry
in interface SimpleFeature
null
void setDefaultGeometry(Geometry geometry) throws IllegalAttributeException
geometry
- The geometry to set.
IllegalAttributeException
- If the AttributeType is not a
geometry, or is invalid for some other reason.ReferencedEnvelope getBounds()
This method will return an empty Envelope if the feature contains no geometry information.
getBounds
in interface Feature
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |