org.geotools.feature.collection
Class SubFeatureCollection

java.lang.Object
  org.geotools.feature.collection.AbstractResourceCollection
      org.geotools.feature.collection.SubFeatureCollection

All Implemented Interfaces:

java.util.Collection, Feature, FeatureCollection, FeatureResults, ResourceCollection

Direct Known Subclasses:

SubFeatureList

public class SubFeatureCollection

extends AbstractResourceCollection

implements FeatureCollection

Used as a reasonable default implementation for subCollection.

Note: to implementors, this is not optimal, please do your own thing - your users will thank you.

Author:

Jody Garnett, Refractions Research, Inc.

Nested Class Summary

Nested classes inherited from class org.geotools.feature.Feature

Feature.NULL

Field Summary

protected FeatureCollection	collection Origional Collection
protected Filter	filter Filter
protected FeatureState	state

Fields inherited from class org.geotools.feature.collection.AbstractResourceCollection

open

Constructor Summary

SubFeatureCollection(FeatureCollection collection)

SubFeatureCollection(FeatureCollection collection, Filter subfilter)

Method Summary

void	accepts(FeatureVisitor visitor, ProgressListener progress) Accepts a visitor, which then visits each feature in the collection.
void	addListener(CollectionListener listener) Adds a listener for collection events.
void	close(FeatureIterator close) Clean up any resources assocaited with this iterator in a manner similar to JDO collections.
void	closeIterator(java.util.Iterator iterator) Please override to cleanup after your own iterators, and any used resources.
FeatureCollection	collection() Convert this set of results to a FeatureCollection.
protected Filter	createFilter() Override to implement subsetting
FeatureIterator	features() Obtain a FeatureIterator of the Features within this collection.
protected Filter	filter()
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() Returns the bounding box of this FeatureResults.
int	getCount() Returns the number of Features in this FeatureResults.
com.vividsolutions.jts.geom.Geometry	getDefaultGeometry() Gets the default geometry for this feature.
FeatureType	getFeatureType() Gets a reference to the type of this feature collection.
java.lang.String	getID() Gets the unique feature ID for this feature.
int	getNumberOfAttributes() Get the number of attributes this feature has.
FeatureCollection	getParent() Gets the feature collection this feature is stored in.
FeatureType	getSchema() The schema for the child features of this collection.
boolean	isEmpty()
java.util.Iterator	openIterator() Open a resource based Iterator, we will call close( iterator ).
void	purge() Close any outstanding resources released by this resources.
FeatureReader	reader() Provides access to the Features, please note that FeatureReader is a blocking api.
void	removeListener(CollectionListener listener) Removes a listener for collection events.
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 g) 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.
int	size() Returns the number of elements in this collection.
FeatureList	sort(SortBy order) collection.subCollection( myFilter ).sort( {"foo","bar"} ); collection.subCollection( myFilter ).sort( "bar" ).sort("foo")
FeatureCollection	subCollection(Filter filter) FeatureCollection "view" indicated by provided filter.

Methods inherited from class org.geotools.feature.collection.AbstractResourceCollection

add, addAll, clear, close, contains, containsAll, iterator, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.geotools.feature.FeatureCollection

close

Methods inherited from interface org.geotools.data.collection.ResourceCollection

iterator

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, remove, removeAll, retainAll, toArray, toArray

Field Detail

filter

protected Filter filter

Filter

collection

protected FeatureCollection collection

Origional Collection

state

protected FeatureState state

Constructor Detail

SubFeatureCollection

public SubFeatureCollection(FeatureCollection collection)

SubFeatureCollection

public SubFeatureCollection(FeatureCollection collection,
                            Filter subfilter)

Method Detail

filter

protected Filter filter()

createFilter

protected Filter createFilter()

Override to implement subsetting

getFeatureType

public FeatureType getFeatureType()

Description copied from interface: FeatureCollection

Gets a reference to the type of this feature collection.

There are several limitations on the use of FeatureType with respect to a FeatureCollection.

GML 3.x: all FeatureCollections decend from gml:AbstractFeatureCollectionType:

• featureMember 0..* allows _Feature or xlink:ref
• featureMembers 0..1 contents treated as _Feature

The contents defined in this manner is returned the collection iterator() method.

GML 3.x: gml:AbstractFeatureCollectionType decends from gml:BoundedFeatureType:

• metaDataProperty 0..*
• description 0..1
• name 0..*
• boundedBy 1..1 (required)
• location 0..1

The value of the boundedBy attribute should be derived from the contents of the collection.

Implementation Notes

There is a difference between getFeatureType() and getSchema(), getSchema is named for historical reasons and reprensets the LCD FeatureType that best represents the contents of this collection.

• The degenerate case returns the "_Feature" FeatureType, where the onlything known is that the contents are Features.
• For a collection backed by a shapefiles (or database tables) the FeatureType returned by getSchema() will complete describe each and every child in the collection.
• For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it is retrived from the collection

Specified by:

getFeatureType in interface FeatureCollection

Returns:

A reference to this collections type

features

public FeatureIterator features()

Description copied from interface: FeatureCollection

Obtain a FeatureIterator of the Features within this collection.

The implementation of Collection must adhere to the rules of fail-fast concurrent modification. In addition (to allow for resource backed collections, the close( Iterator ) method must be called.

This is almost equivalent to:

• a Type-Safe call to: getAttribute(getFeatureType().getAttributeType(0).getName()).iterator();.
• A Java 5:Iterator<Feature>

Example (safe) use:

 FeatureIterator iterator=collection.features();
 try {
     while( iterator.hasNext()  ){
          Feature feature = iterator.next();
          System.out.println( feature.getID() );
     }
 }
 finally {
     collection.close( iterator );
 }
 

GML Note: The contents of this iterator are considered to be defined by featureMember tags (and/or the single allowed FeatureMembers tag). Please see getFeatureType for more details.

Specified by:

features in interface FeatureCollection

Returns:

A FeatureIterator.

closeIterator

public void closeIterator(java.util.Iterator iterator)

Description copied from class: AbstractResourceCollection

Please override to cleanup after your own iterators, and any used resources.

As an example if the iterator was working off a File then the inputstream should be closed.

Subclass must call super.close( close ) to allow the list of open iterators to be adjusted.

Specified by:

closeIterator in class AbstractResourceCollection

Parameters:

iterator - Iterator, will not be null

close

public void close(FeatureIterator close)

Description copied from interface: FeatureCollection

Clean up any resources assocaited with this iterator in a manner similar to JDO collections.

You must be sure to allow null values, this is because in a try/finally block client code may not be sure if they have actualy succeed in assign a value to an iterator they wish to ensure is closed. By permiting null as an api we prevent a null check in lots of finally statements.

Note: Because of FeatureReader using an interator internally, there is only one implementation of this method that makes any sense:

 public void close( FeatureIterator iterator) {
     if( iterator != null ) iterator.close();
 }
 

Specified by:

close in interface FeatureCollection

getID

public java.lang.String getID()

Description copied from interface: Feature

Gets the unique feature ID for this feature.

Specified by:

getID in interface Feature

Returns:

Unique identifier for this feature.

getBounds

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

Description copied from interface: FeatureResults

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;  
 }
 
 

Specified by:

getBounds in interface FeatureResults

Returns:

Bounding box of this FeatureResults, or an empty Envelope

getDefaultGeometry

public com.vividsolutions.jts.geom.Geometry getDefaultGeometry()

Description copied from interface: Feature

Gets the default geometry for this feature.

This method will return null if no DefaultGeometry has been defined by the schema.

Specified by:

getDefaultGeometry in interface Feature

Returns:

Default geometry for this feature, or null

setDefaultGeometry

public void setDefaultGeometry(com.vividsolutions.jts.geom.Geometry g)
                        throws IllegalAttributeException

Description copied from interface: Feature

Sets the default geometry for this feature.

Specified by:

setDefaultGeometry in interface Feature

Parameters:

g - The geometry to set.

Throws:

IllegalAttributeException - If the AttributeType is not a geometry, or is invalid for some other reason.

addListener

public void addListener(CollectionListener listener)
                 throws java.lang.NullPointerException

Description copied from interface: FeatureCollection

Adds a listener for collection events.

When this collection is backed by live data the event notification will follow the guidelines outlined by FeatureListner.

Specified by:

addListener in interface FeatureCollection

Parameters:

listener - The listener to add

Throws:

java.lang.NullPointerException - If the listener is null.

removeListener

public void removeListener(CollectionListener listener)
                    throws java.lang.NullPointerException

Description copied from interface: FeatureCollection

Removes a listener for collection events.

Specified by:

removeListener in interface FeatureCollection

Parameters:

listener - The listener to remove

Throws:

java.lang.NullPointerException - If the listener is null.

getParent

public FeatureCollection getParent()

Description copied from interface: Feature

Gets the feature collection this feature is stored in.

Specified by:

getParent in interface Feature

Returns:

The collection that is the parent of this feature.

setParent

public void setParent(FeatureCollection collection)

Description copied from interface: Feature

Sets the parent collection this feature is stored in, if it is not already set. If it is set then this method does nothing.

Specified by:

setParent in interface Feature

Parameters:

collection - the collection to be set as parent.

getAttributes

public java.lang.Object[] getAttributes(java.lang.Object[] attributes)

Description copied from interface: Feature

Copy all the attributes of this Feature into the given array. If the argument array is null, a new one will be created. Gets all attributes from this feature, returned as a complex object array. This array comes with no metadata, so to interpret this collection the caller class should ask for the schema as well. This array may have multiple entries for each AttributeType depending on the AttributeType's multiplicity.

Specified by:

getAttributes in interface Feature

Parameters:

attributes - An array to copy attributes into. May be null.

Returns:

The array passed in, or a new one if null.

getAttribute

public java.lang.Object getAttribute(java.lang.String xPath)

Description copied from interface: Feature

Gets an attribute for this feature at the location specified by xPath. Due to the complex nature of xpath, a List of all valid values will be returned when an attribute is requested. These values can range from complete Feature Collections to single primative attribute values. When a particular instance of the Attribute is requested, then the Object will be returned. Simply put, in the general case we are assuming the existance of multiplicity, so specify which instance you want or you get them all. Example of getting a list: ./road returns the List of road attribute instances Example of getting an Object: ./road[0] returns the first road

Specified by:

getAttribute in interface Feature

Parameters:

xPath - XPath representation of attribute location.

Returns:

A List of copies of the requested attribute, null if the requested xpath is not found, or NULL_ATTRIBUTE.

getAttribute

public java.lang.Object getAttribute(int index)

Description copied from interface: Feature

Gets an attribute by the given zero-based index. This index is based on the values within the Feature as opposed to the AttributeType declaration. To get the values for the 5th attributeType, use the schema to determine the xPath and class the getAttribute(xPath) method.

Specified by:

getAttribute in interface Feature

Parameters:

index - The requested index. Must be 0 <= idx < getNumberOfAttributes().

Returns:

A copy of the requested attribute, or NULL_ATTRIBUTE.

See Also:

Feature.getAttribute(String)

setAttribute

public void setAttribute(int position,
                         java.lang.Object val)
                  throws IllegalAttributeException,
                         java.lang.ArrayIndexOutOfBoundsException

Description copied from interface: Feature

Sets an attribute by the given zero-based index. This index is based on the values within the Feature as opposed to the AttributeType declaration. To get the values for the 5th attributeType, use the schema to determine the xPath and class the setAttribute(xPath,val) method.

Specified by:

setAttribute in interface Feature

Parameters:

position - The requested index. Must be 0 <= idx < getNumberOfAttributes()

val - An object representing the attribute being set

Throws:

java.lang.ArrayIndexOutOfBoundsException - if an invalid position is given

IllegalAttributeException - if the passed in val does not validate against the AttributeType at that position.

See Also:

Feature.setAttribute(String, Object)

getNumberOfAttributes

public int getNumberOfAttributes()

Description copied from interface: Feature

Get the number of attributes this feature has. This is NOT simply a convenience method for calling getFeatureType().getNumberOfAttributes(). This is the same as calling getAttributes(null).length. This represents the number of actual attribute values in the feature, and may differ from the number of AttributeTypes defined in the FeatureType based on the multiplicity of the AttributeTypes.

Specified by:

getNumberOfAttributes in interface Feature

Returns:

The total number of attributes this Feature contains.

setAttribute

public void setAttribute(java.lang.String xPath,
                         java.lang.Object attribute)
                  throws IllegalAttributeException

Description copied from interface: Feature

Sets a single attribute for this feature, passed as a complex object. If the attribute does not exist or the object does not conform to the internal schema, an exception is thrown. Checking this is, of course, left to the feature to do internally. Well behaved features should always fully check the passed attributes against thire schema before adding them. NOTE: The xPath may contain instance information about multiplicity, for example: ./road[3] which is the third road attribute in this feature.

Specified by:

setAttribute in interface Feature

Parameters:

xPath - XPath representation of attribute location.

attribute - Feature attribute to set.

Throws:

IllegalAttributeException - If the attribute is illegal for the path specified.

subCollection

public FeatureCollection subCollection(Filter filter)

Description copied from interface: FeatureCollection

FeatureCollection "view" indicated by provided filter.

The contents of the returned FeatureCollection are determined by applying the provider Fitler to the entire contents of this FeatureCollection. The result is "live" and modifications will be shared.

This method is used cut down on the number of filter based methods required for a useful FeatureCollection construct. The FeatureCollections returned really should be considered as a temporary "view" used to control the range of a removeAll, or modify opperation.

Example Use:

 collection.subCollection( filter ).clear();
 

The above recommended use is agreement with the Collections API precident of List.subList( start, end ).

The results of subCollection:

• are to be considered unordered
• may be an ordered FeatureList if requested when sortBy is indicated

Specified by:

subCollection in interface FeatureCollection

Parameters:

filter -

Returns:

FeatureCollection identified as subset.

See Also:

FeatureList

size

public int size()

Description copied from class: AbstractResourceCollection

Returns the number of elements in this collection.

Specified by:

size in interface java.util.Collection

Specified by:

size in class AbstractResourceCollection

Returns:

Number of items, or Interger.MAX_VALUE

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Collection

Overrides:

isEmpty in class AbstractResourceCollection

Returns:

true if this collection contains no elements.

openIterator

public java.util.Iterator openIterator()

Description copied from class: AbstractResourceCollection

Open a resource based Iterator, we will call close( iterator ).

Please subclass to provide your own iterator for the the ResourceCollection, note iterator() is implemented to call open() and track the results in for later purge().

Specified by:

openIterator in class AbstractResourceCollection

Returns:

Iterator based on resource use

getSchema

public FeatureType getSchema()

Description copied from interface: FeatureCollection

The schema for the child features of this collection.

There is a difference between getFeatureType() and getSchema()represents the LCD FeatureType that best represents the contents of this collection.

• The degenerate case returns the "_Feature" FeatureType, where the onlything known is that the contents are Features.
• For a collection backed by a shapefiles (or database tables) the FeatureType returned by getSchema() will complete describe each and every child in the collection.
• For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it is retrived from the collection

The method getSchema() is named for compatability with the geotools 2.0 API. In the Geotools 2.2 time frame we should be able to replace this method with a careful check of getFeatureType() and its attributes.

Specified by:

getSchema in interface FeatureCollection

Returns:

FeatureType describing the "common" schema to all child features of this collection

accepts

public void accepts(FeatureVisitor visitor,
                    ProgressListener progress)
             throws java.io.IOException

Accepts a visitor, which then visits each feature in the collection.

Specified by:

accepts in interface FeatureCollection

Parameters:

visitor -

Throws:

java.io.IOException

reader

public FeatureReader reader()
                     throws java.io.IOException

Description copied from interface: FeatureResults

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

Specified by:

reader in interface FeatureResults

Returns:

A FeatureReader streaming over the FeatureResults

Throws:

java.io.IOException - DOCUMENT ME!

getCount

public int getCount()
             throws java.io.IOException

Description copied from interface: FeatureResults

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;  
 }
 
 

Specified by:

getCount in interface FeatureResults

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

Description copied from interface: FeatureResults

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;  
 }
 

Specified by:

collection in interface FeatureResults

Returns:

DOCUMENT ME!

Throws:

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

sort

public FeatureList sort(SortBy order)

Description copied from interface: FeatureCollection

collection.subCollection( myFilter ).sort( {"foo","bar"} ); collection.subCollection( myFilter ).sort( "bar" ).sort("foo")

Specified by:

sort in interface FeatureCollection

Parameters:

order -

Returns:

purge

public void purge()

Description copied from interface: ResourceCollection

Close any outstanding resources released by this resources.

This method should be used with great caution, it is however available to allow the use of the ResourceCollection with algorthims that are unaware of the need to close iterators after use.

Example of using a normal Collections utility method:

 Collections.sort( collection );
 collection.purge(); 
 

Specified by:

purge in interface ResourceCollection

Overrides:

purge in class AbstractResourceCollection