org.geotools.data.store
Class DataFeatureCollection

java.lang.Object
  org.geotools.data.store.DataFeatureCollection

All Implemented Interfaces:

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

Direct Known Subclasses:

DefaultFeatureResults, ForceCoordinateSystemFeatureResults, ReprojectFeatureResults

public abstract class DataFeatureCollection

extends java.lang.Object

implements FeatureCollection

A starting point for implementing FeatureCollection's backed by real data.

The API you are required to implement is *identical* the the barebones FeatureResults interface:

• getSchema()
• reader()
• getBounds()
• getCount()
• collection()

  This class will implement the 'extra' methods required by FeatureCollection for you (in simple terms based on the FeatureResults API). Anything that is often customized is available to you as a constructor parameters.

  Enjoy.

  Since:

  2.1.RC0

  Author:

  jgarnett

  Nested Class Summary

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

  Feature.NULL

  Constructor Summary

  protected	DataFeatureCollection() Collection based on a generic collection
  protected	DataFeatureCollection(java.lang.String id) Collection based on a generic collection
  protected	DataFeatureCollection(java.lang.String id, FeatureType featureType) Subclass must think about what consitructors it needs.

  Method Summary

  void	accepts(FeatureVisitor visitor, ProgressListener progress) Accepts a visitor, which then visits each feature in the collection.
  boolean	add(java.lang.Object arg0)
  boolean	addAll(java.util.Collection arg0) Optimized implementation of addAll that recognizes the use of collections obtained with subCollection( filter ).
  void	addListener(CollectionListener listener) Adds a listener for collection events.
  void	clear()
  void	close(FeatureIterator iterator) 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.
  protected void	closeIterator(java.util.Iterator close)
  abstract FeatureCollection	collection() Convert this set of results to a FeatureCollection.
  boolean	contains(java.lang.Object o)
  boolean	containsAll(java.util.Collection arg0)
  FeatureIterator	features() FeatureIterator is entirely based on iterator().
  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) Not really interested yet ..
  java.lang.Object[]	getAttributes(java.lang.Object[] attributes) Copy all the attributes of this Feature into the given array.
  abstract com.vividsolutions.jts.geom.Envelope	getBounds() Returns the bounding box of this FeatureResults.
  abstract 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() FeatureType of this FeatureCollection.
  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.
  abstract FeatureType	getSchema() The schema for the child features of this collection.
  boolean	isEmpty() Default implementation based on creating an reader, testing hasNext, and closing.
  java.util.Iterator	iterator() Iterator may (or may) not support modification.
  protected java.util.Iterator	openIteartor() Returns a FeatureWriterIterator, or FeatureReaderIterator over content.
  void	purge() Close any outstanding resources released by this resources.
  abstract FeatureReader	reader() Provides access to the Features, please note that FeatureReader is a blocking api.
  boolean	remove(java.lang.Object arg0)
  boolean	removeAll(java.util.Collection arg0)
  void	removeListener(CollectionListener listener) Removes a listener for collection events.
  boolean	retainAll(java.util.Collection arg0)
  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() Default implementation based on getCount() - this may be expensive
  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 FeatureSource.
  java.lang.Object[]	toArray()
  java.lang.Object[]	toArray(java.lang.Object[] arg0)
  protected FeatureWriter	writer() Subclass may provide an implementation of this method to indicate that read/write support is provided.

  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

  DataFeatureCollection

  protected DataFeatureCollection()

  Collection based on a generic collection

  DataFeatureCollection

  protected DataFeatureCollection(java.lang.String id)

  Collection based on a generic collection

  DataFeatureCollection

  protected DataFeatureCollection(java.lang.String id,
                                  FeatureType featureType)

  Subclass must think about what consitructors it needs.

  Method Detail

  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)

  getSchema

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

  reader

  public abstract 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!

  getBounds

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

  getCount

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

  writer

  protected FeatureWriter writer()
                          throws java.io.IOException

  Subclass may provide an implementation of this method to indicate that read/write support is provided.

  All operations that attempt to modify the "data" will use this method, allowing them to throw an "UnsupportedOperationException" in the same manner as Collections.unmodifiableCollection(Collection c)

  Throws:

  java.lang.UnsupportedOperationException - To indicate that write support is not avaiable

  java.io.IOException

  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

  features

  public FeatureIterator features()

  FeatureIterator is entirely based on iterator().

  So when we implement FeatureCollection.iterator() this will work out of the box.

  Specified by:

  features in interface FeatureCollection

  Returns:

  A FeatureIterator.

  iterator

  public final java.util.Iterator iterator()

  Iterator may (or may) not support modification.

  Specified by:

  iterator in interface ResourceCollection

  Returns:

  Iterator

  openIteartor

  protected java.util.Iterator openIteartor()

  Returns a FeatureWriterIterator, or FeatureReaderIterator over content.

  If you have a way to tell that you are readonly please subclass with a less hardcore check - this implementations catches a UnsupportedOpperationsException from wrtier()!

  Returns:

  Iterator, should be closed closeIterator

  close

  public void close(FeatureIterator iterator)

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

  closeIterator

  protected void closeIterator(java.util.Iterator close)

  size

  public int size()

  Default implementation based on getCount() - this may be expensive

  Specified by:

  size in interface java.util.Collection

  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

  isEmpty

  public boolean isEmpty()

  Default implementation based on creating an reader, testing hasNext, and closing.

  For once the Collections API does not give us an escape route, we *have* to check the data.

  Specified by:

  isEmpty in interface java.util.Collection

  contains

  public boolean contains(java.lang.Object o)

  Specified by:

  contains in interface java.util.Collection

  toArray

  public java.lang.Object[] toArray()

  Specified by:

  toArray in interface java.util.Collection

  toArray

  public java.lang.Object[] toArray(java.lang.Object[] arg0)

  Specified by:

  toArray in interface java.util.Collection

  add

  public boolean add(java.lang.Object arg0)

  Specified by:

  add in interface java.util.Collection

  remove

  public boolean remove(java.lang.Object arg0)

  Specified by:

  remove in interface java.util.Collection

  containsAll

  public boolean containsAll(java.util.Collection arg0)

  Specified by:

  containsAll in interface java.util.Collection

  addAll

  public boolean addAll(java.util.Collection arg0)

  Optimized implementation of addAll that recognizes the use of collections obtained with subCollection( filter ).

  This method is constructed by either:

  • Filter OR
  • Removing an extact match of Filter AND

  Specified by:

  addAll in interface java.util.Collection

  removeAll

  public boolean removeAll(java.util.Collection arg0)

  Specified by:

  removeAll in interface java.util.Collection

  retainAll

  public boolean retainAll(java.util.Collection arg0)

  Specified by:

  retainAll in interface java.util.Collection

  clear

  public void clear()

  Specified by:

  clear in interface java.util.Collection

  getFeatureType

  public FeatureType getFeatureType()

  FeatureType of this FeatureCollection.

  Unless a FeatureType was provided during consturction (or this method is overriden) a FeatureType will be generated based on getSchmea according to the following assumptions:

  • FeatureType is gml:AbstractFeatureCollectionType
  • first attribute is getSchema.typeName
  • the attribute FeatureType the same as returned by getSchema()

  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)

  Not really interested yet ..

  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.

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

  The subCollection is constructed by using an AND Filter. For the converse of this opperation please see collection.addAll( Collection ), it has been optimized to be aware of these filter based SubCollections.

  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