|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Represents a feature of arbitrary complexity. This interface answers the
question: How do we access feature attributes? 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
its FeatureType
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
Nested Class Summary | |
static class |
Feature.NULL
Not straight forward, this is a "null" object to represent the value null for a given attribute which is nullable. |
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)
Gets an attribute for this feature at the location specified by xPath. |
java.lang.Object[] |
getAttributes(java.lang.Object[] attributes)
Copy all the attributes of this Feature into the given array. |
com.vividsolutions.jts.geom.Envelope |
getBounds()
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. |
com.vividsolutions.jts.geom.Geometry |
getDefaultGeometry()
Gets the default geometry for this feature. |
FeatureType |
getFeatureType()
Gets a reference to the schema for this feature. |
java.lang.String |
getID()
Gets the unique feature ID for this feature. |
int |
getNumberOfAttributes()
Get the number of attributes this feature has. |
FeatureCollection |
getParent()
Deprecated. Please don't use, a Feature can be in more then one collection |
void |
setAttribute(int position,
java.lang.Object val)
Sets an attribute by the given zero-based index. |
void |
setAttribute(java.lang.String xPath,
java.lang.Object attribute)
Sets a single attribute for this feature, passed as a complex object. |
void |
setDefaultGeometry(com.vividsolutions.jts.geom.Geometry geometry)
Sets the default geometry for this feature. |
void |
setParent(FeatureCollection collection)
Sets the parent collection this feature is stored in, if it is not already set. |
Method Detail |
public FeatureCollection getParent()
public void setParent(FeatureCollection collection)
collection
- the collection to be set as parent.public FeatureType getFeatureType()
public java.lang.String getID()
public java.lang.Object[] getAttributes(java.lang.Object[] attributes)
attributes
- An array to copy attributes into. May be null.
public java.lang.Object getAttribute(java.lang.String xPath)
xPath
- XPath representation of attribute location.
public java.lang.Object getAttribute(int index)
index
- The requested index. Must be 0 <= idx <
getNumberOfAttributes().
getAttribute(String)
public void setAttribute(int position, java.lang.Object val) throws IllegalAttributeException, java.lang.ArrayIndexOutOfBoundsException
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.
java.lang.ArrayIndexOutOfBoundsException
- if an invalid position is givensetAttribute(String, Object)
public int getNumberOfAttributes()
public void setAttribute(java.lang.String xPath, java.lang.Object attribute) throws IllegalAttributeException
xPath
- XPath representation of attribute location.attribute
- Feature attribute to set.
IllegalAttributeException
- If the attribute is illegal for the
path specified.public com.vividsolutions.jts.geom.Geometry getDefaultGeometry()
This method will return null
if no DefaultGeometry has been
defined by the schema.
null
public void setDefaultGeometry(com.vividsolutions.jts.geom.Geometry geometry) throws IllegalAttributeException
geometry
- The geometry to set.
IllegalAttributeException
- If the AttributeType is not a
geometry, or is invalid for some other reason.public com.vividsolutions.jts.geom.Envelope getBounds()
This method will return an empty Envelope if the feature contains no geometry information.
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |