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:

- Simple Features for SQL

@author Jody Garnett, Refractions Research @since GeoTools 2.2.