|
package org.geotools.feature.collection
Helper classes for implementing FeatureCollections. Please note that this is
mostly of interest to DataStore implementors who can use these classes
as a starting point for their providing their own content (backed by a
resultset or disk file etc.).
Meaning of FeatureCollections
FeatureCollections can be grouped into the following categories:
- FeatureCollection - providing access to a set of Features, both bounds and
count are supported (although you are warned that both may be O(N))
- RandomFeatureAccess - provides access to Feature by ID
- FeatureList - provides access to sorted set of Features
You can use the instanceof operator to check before casting although
the API will be explicit where appropriate. Please note that the API may be
explicit in Javadocs due to the limitations of Java 1.4.
- Explicit: FeatureCollection.sort( SortBy ) returns a FeatureList
- Explict: FeatureCollection.filter( Filter ) returns a FeatureCollection
- Implicit: FeatureList.filter( Filter ) returns a FeatureCollection, impled
that this instance also is an instnaceof FeatureList
Where possible we have placed this kind of thing into the GeoAPI
FeatureCollection interface where Java5 can make these ideas exact.
Use of SortBy and Filter
You can explicitly obtain a FeatureList by using a sort( SortBy ) on an
FeatureCollection. You can also obtain a "sub" feature collection by using
a filter( Filter ). In both these cases the resulting construct is considered
a "view" onto the origional FeatureCollection (which in the case of a
DataStore will represent contents located externally).
FeatureList list = featureCollection.filter( filter ).sort( sort );
In addition to working directly with a "view" you can often use this
technique to stage an opperation such as addAll or remove.
collection.addAll( list.filter( filter ) );
list.filter( filter ).remove();
Seperation Of Concerns
By using the sub collection opperations such as sort and filter you can
carefully define set of data you wish to query against. This seperation of
concerns can be maintained by ensuring the use of Expression when accessing
content, and not acceing content directly.
This seperation of concerns is manditory for geotools library code, and
is strongly recommended for client code.
Choosing a FeatureCollection Implementation for Client Code
The most basic FeatureCollection available in this package is the one that
store information completly in memory. This is designed to be used by end
users and is available for construction via a FeatureFactory (or
SimpleFeatureFactory as required).
A common request involves using a MemoryFeatureCollection to cache
information for display. You are warned that this approach will often fail
in real GIS useage where the quantity of information can not be limited
by memory.
Implementing a FeatureCollection Implementation as a Data Provider
As a Data provideder you are expected to extend the AbstractFeatureCollection
classes provided here to make the most performant implementation of feature
access you can.
You are responsible for providing the following:
- All FeatureCollection Implementation: required to represent all content on
accessed with Transaction.AUTO_COMMIT, bounds and count information provided
by metadata. This implementation is mostly used to defined sub collections
via filter and sort methods.
- "Sub"FeatureCollection Implementation: produced in response to a filter or sort method
should be either lazy, or backed by a result set obtained by the first
opperation. A cache may be emplyed for information such as bounds and
count.
- FeatureList Implementation: if for file or feature result can be sorted (either via an
initial SQL request or via consulting an attribute index file) you can "out"
this capability to your end users by use of a FeatureList.
- Getting Spatial with your Collections: many spatial file formats can make
use of a spatial index (or SFSQL class) to provide an optimized experience.
If possible please engage this early and often as we are spatial library,
on a related note GeometryAttribute and Feature both support the settings
of bounds, if this information is available please make use of it to prevent
the running an expensive bounds calculation in software.
Although not recommended as general practice some implementations will be forced
to "burn memory" by making use of the FeatureCollection Implementations
intented for client code for manipulations such as sorting. If this applies to
use please try to set yourself up to be lazy - it may be that the user will
perform additional sub collection calls.
A word about Simple Features
The SimpleFeature interface is by no means required, it only represents
a set of additional methods that can be defined safely when the content
is a flat ordered list of atomic types with no multiplicity as dictated
exactly in agreement with their type definition.
What does this mean for a FeatureCollection? For a SimpleFeatureCollection
no attributes are supported at the SimpleFeatureCollectionType level, and the
content members are restricted to a belonging single SimpleFeatureType.
References
The following links will be of interest:
@author Jody Garnett, Refractions Research
@since GeoTools 2.2.
|