org.geotools.feature
Interface FeatureCollection

All Superinterfaces:
java.util.Collection, Feature, FeatureResults
All Known Subinterfaces:
FeatureDocument, FeatureList, IndexedFeatureCollection
All Known Implementing Classes:
AbstractFeatureCollection

public interface FeatureCollection
extends java.util.Collection, FeatureResults, Feature

Represents a collection of features.

Implementations (and client code) should adhere to the rules set forth by java.util.Collection. That is, some methods are optional to implement, and may throw an UnsupportedOperationException.

FeatureCollection house rules:

In programmer speak a FeatureCollection is a "Bag" with an index based ID.

Life Cycle of Iterator

We have also adopted an additional constraint on the use of iterator. You must call FeatureCollection.close( iterator ) to allow FeatureCollection to clean up any operating system resources used to acces information.

Example (safe) use:


 Iterator iterator = collection.iterator();
 try {
     for( Iterator i=collection.iterator(); i.hasNext();){
          Feature feature = (Feature) i.hasNext();
          System.out.println( feature.getID() );
     }
 }
 finally {
     collection.close( iterator );
 }
 

Implementation Note: Although many resource backed collections will choose to release resources at to close when the iterator has reached the end of its contents

Version:
$Id: FeatureCollection.java,v 1.12 2003/07/30 21:31:41 jmacgill Exp $
Author:
Ian Turton, CCG, Rob Hranac, VFNY, Ian Schneider, USDA-ARS
See Also:
Collection

Nested Class Summary
 
Nested classes inherited from class org.geotools.feature.Feature
Feature.NULL
 
Method Summary
 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 close(java.util.Iterator close)
          Clean up after any resources assocaited with this itterator in a manner similar to JDO collections.
 FeatureIterator features()
          Obtain a FeatureIterator of the Features within this collection.
 FeatureType getFeatureType()
          Gets a reference to the schema for this feature.
 FeatureType getSchema()
          The schema for the child features of this collection.
 java.util.Iterator iterator()
          Returns an iterator over the contents of this collection.
 void removeListener(CollectionListener listener)
          Removes a listener for collection events.
 
Methods inherited from interface java.util.Collection
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface org.geotools.data.FeatureResults
collection, getBounds, getCount, reader
 
Methods inherited from interface org.geotools.feature.Feature
getAttribute, getAttribute, getAttributes, getBounds, getDefaultGeometry, getID, getNumberOfAttributes, getParent, setAttribute, setAttribute, setDefaultGeometry, setParent
 

Method Detail

features

public FeatureIterator features()
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:

Example (safe) use:

 Iterator iterator = collection.iterator();
 try {
     for( FeatureIterator i=collection.features(); i.hasNext();){
          Feature feature = i.hasNext();
          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.

Returns:
A FeatureIterator.

iterator

public java.util.Iterator iterator()
Returns an iterator over the contents of this collection.

Collection is not guarneteed to be ordered in any manner.

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.

Example (safe) use:

 Iterator iterator = collection.iterator();
 try {
     for( Iterator i=collection.iterator(); i.hasNext();){
          Feature feature = (Feature) i.hasNext();
          System.out.println( feature.getID() );
     }
 }
 finally {
     collection.close( iterator );
 }
 

Specified by:
iterator in interface java.util.Collection
See Also:
features()

close

public void close(FeatureIterator close)
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();
 }
 


close

public void close(java.util.Iterator close)
Clean up after any resources assocaited with this itterator in a manner similar to JDO collections.

Example (safe) use:

 Iterator iterator = collection.iterator();
 try {
     for( Iterator i=collection.iterator(); i.hasNext();){
          Feature feature = (Feature) i.hasNext();
          System.out.println( feature.getID() );
     }
 }
 finally {
     collection.close( iterator );
 }
 

Parameters:
close -

addListener

public void addListener(CollectionListener listener)
                 throws java.lang.NullPointerException
Adds a listener for collection events.

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

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
Removes a listener for collection events.

Parameters:
listener - The listener to remove
Throws:
java.lang.NullPointerException - If the listener is null.

getFeatureType

public FeatureType getFeatureType()
Gets a reference to the schema for this feature.

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

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

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

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

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.

Specified by:
getFeatureType in interface Feature
Returns:
A reference to this feature's schema

getSchema

public FeatureType getSchema()
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 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 FeatureResults
Returns:
FeatureType describing the "common" schema to all child features of this collection


Copyright © GeoTools. All Rights Reserved.