|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
A metadata template for a Feature of arbitrary complexity.
Notes:
FeatureAPI.
This interface answers the question: How do we represent features within GeoTools? Of course, the most general answer would be: features can be any Java object. However, this is also the least useful solution because it means that users of features have essentially no way to find out about the meaning of features other than using Java introspection/reflection. This is too cumbersome and is insufficient for the goal of creating a simple framework for manipulating and accessing generic geographic data. The opposite approach might be to define a very constrained set of possible attributes (that, for example, mirrored Java primitives and OGC simple geometries) and only allow features of this type.
This interface takes a different approach: it defines a minimal ontology for representing a
feature and serves as a consistent framework for defining more constrained (and, therefore, often
more meaningful) feature types. A FeatureType represents features as an object
that contains zero or more attribute objects, one of which will generally be a geometry, but no
geometry and multiple geometries are allowed, according to implementation. Note that instances of
implementations of this class are henceforth referred to as schemas.
With oneexceptions, the type of an attribute is considered to be its cannonical definition by the
FeatureType. For example, an attribute type might be a javax.sound.midi.Sequence
object, which contains a float public field called PPQ. The fact that this
attribute exists is not known by the FeatureType itself. If a caller asks this
FeatureType for all of its attributes, the
FeatureType will tell
the caller that it has an attribute of type javax.sound.midi.Sequence, but not
that this attribute has a sub-attribute (field) called PPQ. It is the responsibility of the
callers to understand the objects it is asking for and manipulate them appropriately.
The exceptions is for:
FeatureType is a
org.geotools.datasource.Feature type. FeatureType
implementations.
It is the responsibility of the implementing class to ensure that the FeatureType
is always in a valid state. This means that each attribute tuple must be fully initialized and
valid. The minimum valid FeatureType is one with nulls for namespace, type, and
attributes; this is clearly a trivial case, since it is so constrained that it would not allow
for any feature construction. There are a few conventions of which implementers of this interface
must be aware in order to successfully manage a FeatureType:
FeatureTypeFactoryFeature because they may change over the life of
the feature, while the schema may not. In cases where there are more than one geometries it is up
to the implementor to determine which is the default geometry. getDefaultGeometry
may return null if there are no geometries in the FeatureType, but if there is one
or more geometry then the method must return one of them, null is never an
acceptable return value.FeatureType to understand and correctly implement XPath pointers. Note that the
Feature object does not understand XPath at all and relies on implementors of this
interface to interpret XPath references. Fortunately, XPath is quite simple and has a clearly
written specification .Consequence: Since FeatureType is immutable, and CoordianteSequence is specified by the GeometryFactory of the DefaultGeometryAttribute this implys that we have a per Query SchemaType.
It strikes me that this is a bad separation of concerns the "schema" should be exactly the same, it is just the GeometryFactory that controls construction that is in the wrong spot. It should be a hint, not attached to GeomtryAttributeType.
Feature,
FeatureTypeFactory,
NestedAttributeType,
DefaultFeatureType| Method Summary | |
Feature |
create(java.lang.Object[] attributes)
Deprecated. This method will be remove in 2.2, please use FeatureFactory obtained from FactoryFinder |
Feature |
create(java.lang.Object[] attributes,
java.lang.String featureID)
Deprecated. This method will be remove in 2.2, please use FeatureFactory obtained from FactoryFinder |
Feature |
duplicate(Feature feature)
Create a duplicate of the provided feature, must delegate to an appropriate FeatureFactory create method. |
boolean |
equals(java.lang.Object arg0)
FeatureType check based on namespace, typeName, attributes and ancestors. |
int |
find(AttributeType type)
Find the position of a given AttributeType. |
int |
find(java.lang.String attName)
Find the position of an AttributeType which matches the given String. |
FeatureType[] |
getAncestors()
Obtain an array of this FeatureType's direct ancestors. |
int |
getAttributeCount()
The number of attribues defined by this schema. |
AttributeType |
getAttributeType(int position)
Gets the schema attributeType at the specified index. |
AttributeType |
getAttributeType(java.lang.String xPath)
Gets the attributeType at this xPath, if the specified attributeType does not exist then null is returned.
|
AttributeType[] |
getAttributeTypes()
AttributeTypes for this FeatureType, all attributes defined by this FeatureType and its super types define schema for feature instances. |
GeometryAttributeType |
getDefaultGeometry()
Gets the default geometry AttributeType. |
java.net.URI |
getNamespace()
Gets the global schema namespace. |
java.lang.String |
getTypeName()
Gets the type name for this schema. |
boolean |
hasAttributeType(java.lang.String xPath)
Deprecated. It seems this method is ill concieved, use getAttributeType( xpath ) != null as a replacement |
int |
hashCode()
Hascode based on namespace, typeName, attributes and ancestors. |
boolean |
isAbstract()
Is this FeatureType an abstract type? |
boolean |
isDescendedFrom(FeatureType type)
A convenience method for calling
FeatureType f1;
FeatureType f2;
f1.isDescendedFrom(f2.getNamespace(), f2.getName());
Question: this method duplicates the information provided by getAncestors().
|
boolean |
isDescendedFrom(java.net.URI nsURI,
java.lang.String typeName)
Test to determine whether this FeatureType is descended from the given FeatureType. |
| Method Detail |
public java.net.URI getNamespace()
This is often used to record the schema prefix (not the URI) required when writing out this Feature using GML. The supporting application will need to be able to start the GMLWriter off with the correct URI information so everything makes sense.
The Registry interface provided by the data module provides an example of how to store associate FeatureType and namespace information. Please note that you may not have duplicate typeNames in the same Namespace.
public java.lang.String getTypeName()
In GML this must be the element name of the Feature.
public boolean isDescendedFrom(java.net.URI nsURI,
java.lang.String typeName)
nsURI - The namespace URI to use.typeName - The typeName.
public boolean isDescendedFrom(FeatureType type)
FeatureType f1;
FeatureType f2;
f1.isDescendedFrom(f2.getNamespace(), f2.getName());
Question: this method duplicates the information provided by getAncestors().
type - The type to compare to.
public boolean isAbstract()
When true is returned instances of this Feature cannot be created, instead a child FeatureType must use this FeatureType as its ancestor.
public FeatureType[] getAncestors()
Example Code:
public FeatureType getAncestors()}
return new FeatureType[]{ getSuper(), };
}
public GeometryAttributeType getDefaultGeometry()
If the FeatureType has more one geometry it is up to the implementor to determine which geometry is the default. If working with multiple geometries it is best to get the attributeTypes and iterate through them, checking for instances of GeometryAttribtueType.
This should just be used a convenience method when it is known that the features do not have multiple geometries.
public int getAttributeCount()
This method to allows access to the complete schema as defined by this FeatureType and its ancestors.
public AttributeType getAttributeType(java.lang.String xPath)
null is returned.
Question: it is unclear how this interacts with the complete schema defined by this FeatureType and its ancestors (in which a given xpath may refer to several AttributeTypes as restrictions are applied.
Perhaps this method should be restricted to a FlatFeatureType? Or should have the option of returning an array of matching AttributeType in order of inheiritence?
xPath - XPath pointer to attribute type.
public int find(AttributeType type)
Match is based on attribute type name, the resulting index may be used with getAttributeType( index ).
type - The type to search for.
public int find(java.lang.String attName)
This index may be used with getAttributeType( index ), the search space is the entire schema defined by this FeatureType and its ancestors.
attName - the name to look for
public AttributeType getAttributeType(int position)
The index is specified with respect to the entire Schema (as defined by this FeatureType and it's ancestors).
public AttributeType[] getAttributeTypes()
The provided array of AttributeTypes should be considered as adding to (or overriding) the the AttribtueTypes defined by this FeatureTypes ancestors.
Note Well: Client code should not consider the index provided by the find( attName ) method as a valid index into the returned array.
public boolean hasAttributeType(java.lang.String xPath)
Question: the comment says we are removing this, but it is not depricated? And how the heck can the number of occurances out of a boolean.
xPath - XPath pointer to attribute type.
public Feature duplicate(Feature feature)
throws IllegalAttributeException
The implementation is assumed to make use of AttributeType duplicate as required for a deep copy.
//@deprecated This method will be removed in 2.2, please use FeatureFactory obtained from FactoryFinder
feature -
IllegalAttributeException
public Feature create(java.lang.Object[] attributes)
throws IllegalAttributeException
Creates a new feature, with a generated unique featureID. This is less than ideal, as a FeatureID should be persistant over time, generally created by a datasource. This method is more for testing that doesn't need featureID.
attributes - the array of attribute values
IllegalAttributeException - if the FeatureType does not validate the attributes.
public Feature create(java.lang.Object[] attributes,
java.lang.String featureID)
throws IllegalAttributeException
Creates a new feature, with the proper featureID.
attributes - the array of attribute values.featureID - the feature ID.
IllegalAttributeException - if the FeatureType does not validate the attributes.public boolean equals(java.lang.Object arg0)
Conceptually FeatureType equality is supped to indicate an exact match based AttributeType and Ancestors. The geotools models includes additional information of namespace and typename.
As far as the geotools data model is concerned any FeatureType implementation should be able to be subsituted for another. (An actually application may provided an implementation that provdes tracking of metadata such as creation history, or support for additional interfaces).
Required implementation:
Questions:
Q: You may wonder why namespace and typeName are not enought?
A: Geotools often returns a "limitied" schema in response to a query where only a subset
of the attributes are requested.
Q: Doesn't that still indicate the same schema?
A: Yes it kind of should, a GML application (such as GeoServer) has to actually follow the
application schema and include attributes required by the schema (but not request by the query).
This library is more lax in its treatment, and expects you to uses isDecendedFrom as required.
public int hashCode()
Hascode is always a matched set with an equals implementation, please see the javadocs for equals for a detailed discussion.
Object.hashCode()
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||