org.geotools.data
Interface FeatureResults

All Known Subinterfaces:

FeatureCollection, FeatureDocument, FeatureList, IndexedFeatureCollection, RandomFeatureAccess

All Known Implementing Classes:

AbstractFeatureCollection, AbstractFeatureCollection, AbstractFeatureList, DataFeatureCollection, DefaultFeatureCollection, IndexedFeatureResults, MemoryFeatureCollection, ReprojectFeatureResults, SubFeatureCollection, SubFeatureList, WFSFeatureSource.WFSFeatureResults

public interface FeatureResults

Highlevel API for Features from a specific Query.

The can opperate as as a kind of Prepaired Query. It is a Query that knows enough information to be rerun. We may wish to rename this class as QueryResults.

Differences from FeatureCollection:

• This API opperates as a source of FeatureReaders (rather than a source of iterators)
• As a Prepaired Query thise class allows other "results" to be asked against the same query. getBounds() is the most logical example, but we may be able to think of others. In Candidate "results" should all be reproduceable by streaming over the generated FeatureReader.

Ideas:

• Chris had the idea of a collection() method that would construct a FeatureCollection (by iterating through the FeartureReader once). This would be a nice transition piece to allow us to test against existing renderers. (we could add the method in deprecated form until the Renderers adapt to the new API).
• Ian had the idea of asynchronous error handling as provided by a High-Level version of FeatureReader. This class might be the place for such work? Something similar to jdbc getWarnings()?
• The idea of forcing a CoordinateSystem is also looking for a home, this may be the place for such work (although I recomend proving a a "hint" in the Query interface).

Version:

$Id: FeatureResults.java 17702 2006-01-23 00:08:55Z desruisseaux $

Author:

Jody Garnett, Ray Gallagher, Rob Hranac, TOPP, Chris Holmes, TOPP

Method Summary

FeatureCollection	collection() Deprecated. please consider explicitly constructing a feaure collection
com.vividsolutions.jts.geom.Envelope	getBounds() Returns the bounding box of this FeatureResults.
int	getCount() Deprecated. Please use FeatureCollection.size() instead
FeatureType	getSchema() Returns the FeatureType of the contents of this collection.
FeatureReader	reader() Deprecated. please use FeatureCollections.features() to obtain a FeatureIterator

Method Detail

getSchema

public FeatureType getSchema()
                      throws java.io.IOException

Returns the FeatureType of the contents of this collection.

Please note that for a collection with a mixed contents the FeatureType may be degenerate (ie very generic). For many applications (like shapefiles or tables) the FeatureType can safely be used to describe all the Features in the result set.

Returns:

A FeatureType that describes the contents of this collection.

Throws:

java.io.IOException - if their is a problem getting the FeatureType.

reader

public FeatureReader reader()
                     throws java.io.IOException

Deprecated. please use FeatureCollections.features() to obtain a FeatureIterator

Provides access to the Features, please note that FeatureReader is a blocking api.

Returns:

A FeatureReader streaming over the FeatureResults

Throws:

java.io.IOException - DOCUMENT ME!

getBounds

public com.vividsolutions.jts.geom.Envelope getBounds()

Returns the bounding box of this FeatureResults.

This opperation may be expensive. Consider FeatureSource.getBounds( Query ) as an alternative.

This method is logically the same as:

 
 public Envelope getBounds() throws IOException {
     Envelope newBBox = new Envelope();
     Envelope internal;
     Feature feature;
 
     for (FeatureReader r = reader(); r.hasNext();) {
         feature = r.next();
         internal = feature.getDefaultGeometry().getEnvelopeInternal();
         newBBox.expandToInclude(internal);
     }
     return newBBox;  
 }
 
 

Returns:

Bounding box of this FeatureResults, or an empty Envelope

getCount

public int getCount()
             throws java.io.IOException

Deprecated. Please use FeatureCollection.size() instead

Returns the number of Features in this FeatureResults.

This opperation may be expensive. Consider FeatureSource.getCount( Query ) as an alternative.

This method is logically the same as:

 
 public int getCount() throws IOException {
     int count = 0;
     for (FeatureReader r = reader(); r.hasNext(); count++) {
         r.next();
     }
     return count;  
 }
 
 

Returns:

The number of Features in this FeatureResults.

Throws:

java.io.IOException - If there are problems getting the count

collection

public FeatureCollection collection()
                             throws java.io.IOException

Deprecated. please consider explicitly constructing a feaure collection

Convert this set of results to a FeatureCollection.

This method is logically the same as:

 public FeatureCollection collection() throws IOException {
     FeatureCollection collection = FeatureCollections.newCollection()
     for (FeatureReader r = reader(); r.hasNext();) {
         collection.add( r.next() );
     }
     return collection;  
 }
 

Returns:

DOCUMENT ME!

Throws:

java.io.IOException - If any problems occur aquiring Features