org.geotools.feature
Class DefaultFeatureCollection

java.lang.Object
  extended byorg.geotools.feature.DefaultFeatureCollection
All Implemented Interfaces:
java.util.Collection, Feature, FeatureCollection, FeatureResults, ResourceCollection
Direct Known Subclasses:
GMLFeatureCollection

public class DefaultFeatureCollection
extends java.lang.Object
implements FeatureCollection

A basic implementation of FeatureCollection which use a TreeMap for its internal storage.

This should be considered a MemoryFeatureCollection.

Version:
$Id: DefaultFeatureCollection.java 17701 2006-01-23 00:00:51Z desruisseaux $
Author:
Ian Schneider

Nested Class Summary
 
Nested classes inherited from class org.geotools.feature.Feature
Feature.NULL
 
Constructor Summary
protected DefaultFeatureCollection(java.lang.String id, FeatureType featureType)
          This constructor is protected to discourage direct usage...
 
Method Summary
 void accepts(FeatureVisitor visitor, ProgressListener progress)
          Accepts a visitor, which then visits each feature in the collection.
protected  boolean add(Feature feature, boolean fire)
           
 boolean add(java.lang.Object o)
          Ensures that this collection contains the specified element (optional operation).
 boolean addAll(java.util.Collection collection)
          Adds all of the elements in the specified collection to this collection (optional operation).
 void addListener(CollectionListener listener)
          Adds a listener for collection events.
 void clear()
          Removes all of the elements from this collection (optional operation).
 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.
 FeatureCollection collection()
          Convert this set of results to a FeatureCollection.
 boolean contains(java.lang.Object o)
          Returns true if this collection contains the specified element.
 boolean containsAll(java.util.Collection collection)
          Test for collection membership.
 FeatureIterator features()
          Gets a FeatureIterator of this feature collection.
 java.util.Set fids()
          Optimization time ... grab the fid set so other can quickly test membership during removeAll/retainAll implementations.
protected  void fireChange(java.util.Collection coll, int type)
           
protected  void fireChange(Feature[] features, int type)
          To let listeners know that something has changed.
protected  void fireChange(Feature feature, int type)
           
 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()
          Gets the bounding box for the features in this feature collection.
 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()
          Returns true if this collection contains no elements.
 java.util.Iterator iterator()
          Returns an iterator over the elements in this collection.
 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.
 boolean remove(java.lang.Object o)
          Removes a single instance of the specified element from this collection, if it is present (optional operation).
 boolean removeAll(java.util.Collection collection)
          Removes all this collection's elements that are also contained in the specified collection (optional operation).
 void removeListener(CollectionListener listener)
          Removes a listener for collection events.
 boolean retainAll(java.util.Collection collection)
          Retains only the elements in this collection that are contained in the specified collection (optional operation).
 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 geometry)
          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)
          Construct a sorted view of this content.
 FeatureList sort(SortBy2 order)
          Allows for "Advanced" sort capabilities specific to the GeoTools platform!
 FeatureCollection subCollection(Filter filter)
          Will return an optimized subCollection based on access to the origional MemoryFeatureCollection.
 java.lang.Object[] toArray()
          Returns an array containing all of the elements in this collection.
 java.lang.Object[] toArray(java.lang.Object[] a)
          Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Constructor Detail

DefaultFeatureCollection

protected DefaultFeatureCollection(java.lang.String id,
                                   FeatureType featureType)
This constructor is protected to discourage direct usage...

Opportunistic reuse is encouraged, but only for the purposes of testing or other specialized uses. Normal creation should occur through org.geotools.core.FeatureCollections.newCollection() allowing applications to customize any generated collections.

Parameters:
id - may be null ... feature id
Method Detail

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

getBounds

public com.vividsolutions.jts.geom.Envelope getBounds()
Gets the bounding box for the features in this feature collection.

Specified by:
getBounds in interface FeatureResults
Returns:
the envelope of the geometries contained by this feature collection.

addListener

public void addListener(CollectionListener listener)
Adds a listener for collection events.

Specified by:
addListener in interface FeatureCollection
Parameters:
listener - The listener to add

removeListener

public void removeListener(CollectionListener listener)
Removes a listener for collection events.

Specified by:
removeListener in interface FeatureCollection
Parameters:
listener - The listener to remove

fireChange

protected void fireChange(Feature[] features,
                          int type)
To let listeners know that something has changed.


fireChange

protected void fireChange(Feature feature,
                          int type)

fireChange

protected void fireChange(java.util.Collection coll,
                          int type)

add

public boolean add(java.lang.Object o)
Ensures that this collection contains the specified element (optional operation). Returns true if this collection changed as a result of the call. (Returns false if this collection does not permit duplicates and already contains the specified element.)

Collections that support this operation may place limitations on what elements may be added to this collection. In particular, some collections will refuse to add null elements, and others will impose restrictions on the type of elements that may be added. Collection classes should clearly specify in their documentation any restrictions on what elements may be added.

If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning false). This preserves the invariant that a collection always contains the specified element after this call returns.

Specified by:
add in interface java.util.Collection
Parameters:
o - element whose presence in this collection is to be ensured.
Returns:
true if this collection changed as a result of the call

add

protected boolean add(Feature feature,
                      boolean fire)

addAll

public boolean addAll(java.util.Collection collection)
Adds all of the elements in the specified collection to this collection (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this collection, and this collection is nonempty.)

Specified by:
addAll in interface java.util.Collection
Parameters:
collection - elements to be inserted into this collection.
Returns:
true if this collection changed as a result of the call
See Also:
add(Object)

clear

public void clear()
Removes all of the elements from this collection (optional operation). This collection will be empty after this method returns unless it throws an exception.

Specified by:
clear in interface java.util.Collection

contains

public boolean contains(java.lang.Object o)
Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e)).

Specified by:
contains in interface java.util.Collection
Parameters:
o - element whose presence in this collection is to be tested.
Returns:
true if this collection contains the specified element

containsAll

public boolean containsAll(java.util.Collection collection)
Test for collection membership.

Specified by:
containsAll in interface java.util.Collection
Parameters:
collection -
Returns:
true if collection is completly covered

isEmpty

public boolean isEmpty()
Returns true if this collection contains no elements.

Specified by:
isEmpty in interface java.util.Collection
Returns:
true if this collection contains no elements

iterator

public java.util.Iterator iterator()
Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned (unless this collection is an instance of some class that provides a guarantee).

Specified by:
iterator in interface ResourceCollection
Returns:
an Iterator over the elements in this collection

features

public FeatureIterator features()
Gets a FeatureIterator of this feature collection. This allows iteration without having to cast.

Specified by:
features in interface FeatureCollection
Returns:
the FeatureIterator for this collection.

remove

public boolean remove(java.lang.Object o)
Removes a single instance of the specified element from this collection, if it is present (optional operation). More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).

Specified by:
remove in interface java.util.Collection
Parameters:
o - element to be removed from this collection, if present.
Returns:
true if this collection changed as a result of the call

removeAll

public boolean removeAll(java.util.Collection collection)
Removes all this collection's elements that are also contained in the specified collection (optional operation). After this call returns, this collection will contain no elements in common with the specified collection.

Specified by:
removeAll in interface java.util.Collection
Parameters:
collection - elements to be removed from this collection.
Returns:
true if this collection changed as a result of the call
See Also:
remove(Object), contains(Object)

retainAll

public boolean retainAll(java.util.Collection collection)
Retains only the elements in this collection that are contained in the specified collection (optional operation). In other words, removes from this collection all of its elements that are not contained in the specified collection.

Specified by:
retainAll in interface java.util.Collection
Parameters:
collection - elements to be retained in this collection.
Returns:
true if this collection changed as a result of the call
See Also:
remove(Object), contains(Object)

size

public int size()
Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:
size in interface java.util.Collection
Returns:
the number of elements in this collection

toArray

public java.lang.Object[] toArray()
Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Specified by:
toArray in interface java.util.Collection
Returns:
an array containing all of the elements in this collection

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)
Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of this collection only if the caller knows that this collection does not contain any null elements.)

If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

Like the toArray method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs

Suppose l is a List known to contain only strings. The following code can be used to dump the list into a newly allocated array of String:

     String[] x = (String[]) v.toArray(new String[0]);
 

Note that toArray(new Object[0]) is identical in function to toArray().

Specified by:
toArray in interface java.util.Collection
Parameters:
a - the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
Returns:
an array containing the elements of this collection

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:

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 FeatureCollection
Returns:
A reference to this collections type

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.

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.

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.

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 geometry)
                        throws IllegalAttributeException
Description copied from interface: Feature
Sets the default geometry for this feature.

Specified by:
setDefaultGeometry in interface Feature
Parameters:
geometry - The geometry to set.
Throws:
IllegalAttributeException - If the AttributeType is not a geometry, or is invalid for some other reason.

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

close

public void close(java.util.Iterator close)
Description copied from interface: FeatureCollection
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 );
 }
 

Specified by:
close in interface FeatureCollection
Parameters:
close -

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

fids

public java.util.Set fids()
Optimization time ... grab the fid set so other can quickly test membership during removeAll/retainAll implementations.

Returns:
Set of fids.

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

subCollection

public FeatureCollection subCollection(Filter filter)
Will return an optimized subCollection based on access to the origional MemoryFeatureCollection.

This method is intended in a manner similar to subList, example use: collection.subCollection( myFilter ).clear()

Specified by:
subCollection in interface FeatureCollection
Parameters:
filter - Filter used to determine sub collection.
Returns:
FeatureCollection identified as subset.
Since:
GeoTools 2.2, Filter 1.1
See Also:
FeatureList

sort

public FeatureList sort(SortBy order)
Construct a sorted view of this content.

Sorts may be combined togther in a stable fashion, in congruence with the Filter 1.1 specification.

This method should also be able to handle GeoTools specific sorting through detecting order as a SortBy2 instance.

Specified by:
sort in interface FeatureCollection
Parameters:
order - Filter 1.1 SortBy
Returns:
FeatureList sorted according to provided order
Since:
GeoTools 2.2, Filter 1.1

sort

public FeatureList sort(SortBy2 order)
Allows for "Advanced" sort capabilities specific to the GeoTools platform!

Advanced in this case really means making use of a generic Expression, rather then being limited to PropertyName.

Parameters:
order - GeoTools SortBy
Returns:
FeatureList sorted according to provided order

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


Copyright © GeoTools. All Rights Reserved.