org.geotools.feature.collection
Class AbstractResourceCollection

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

All Implemented Interfaces:

java.util.Collection, ResourceCollection

Direct Known Subclasses:

AbstractFeatureCollection, AbstractFeatureCollection, AbstractResourceList, SubFeatureCollection

public abstract class AbstractResourceCollection

extends java.lang.Object

implements ResourceCollection

Collection supporting close( Iterator ).

This implementation is a port of java.util.Collection with support for the use of close( Iterator ). This will allow subclasses that make use of resources during iterator() to be uses safely.

Subclasses are reminded that they should construct their Iterator to return system resources once content has been exhuasted. While this class is safe, and we remind users, not all libraries that accept collections can be hacked.

How to Collectionify Resource Access

We need to do the same things as for use of AbstractCollection - namely:

• Read-Only: provide implementations for size and openIterator ( w/ hasNext() and next().) and finally closeIteartor( iterator )

• Modifiable collection Do all of the above and supply add( Object ) let that Iterator do remove()

And of course subclass, we are after all feelign abstract today :-)

Why not play with iterator()? Because we are keeping track of them for later purge()...

Author:

Jody Garnett, Refractions Research, Inc.

Field Summary

protected java.util.Set

open Set of open resource iterators

Constructor Summary

protected

AbstractResourceCollection()

Method Summary

boolean	add(java.lang.Object o) Implement to support modification.
boolean	addAll(java.util.Collection c) Adds all of the elements in the specified collection to this collection (optional operation).
void	clear() Removes all of the elements from this collection (optional operation).
void	close(java.util.Iterator close) Clean up after any resources assocaited with this iteartor in a manner similar to JDO collections.
protected abstract void	closeIterator(java.util.Iterator close) Please override to cleanup after your own iterators, and any used resources.
boolean	contains(java.lang.Object o) Returns true if this collection contains the specified element.
boolean	containsAll(java.util.Collection c) Returns true if this collection contains all of the elements in the specified collection.
boolean	isEmpty()
java.util.Iterator	iterator() Please implement!
protected abstract java.util.Iterator	openIterator() Open a resource based Iterator, we will call close( iterator ).
void	purge() Close any outstanding resources released by this resources.
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 c) Removes from this collection all of its elements that are contained in the specified collection (optional operation).
boolean	retainAll(java.util.Collection c) Retains only the elements in this collection that are contained in the specified collection (optional operation).
abstract int	size() Returns the number of elements in this collection.
java.lang.Object[]	toArray() Array of all the elements.
java.lang.Object[]	toArray(java.lang.Object[] a)
java.lang.String	toString() Returns a string representation of this collection.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

equals, hashCode

Field Detail

open

protected final java.util.Set open

Set of open resource iterators

Constructor Detail

AbstractResourceCollection

protected AbstractResourceCollection()

Method Detail

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Collection

Returns:

true if this collection contains no elements.

contains

public boolean contains(java.lang.Object o)

Returns true if this collection contains the specified element. .

This implementation iterates over the elements in the collection, checking each element in turn for equality with the specified element.

Specified by:

contains in interface java.util.Collection

Parameters:

o - object to be checked for containment in this collection.

Returns:

true if this collection contains the specified element.

toArray

public java.lang.Object[] toArray()

Array of all the elements.

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)

Specified by:

toArray in interface java.util.Collection

add

public boolean add(java.lang.Object o)

Implement to support modification.

Specified by:

add in interface java.util.Collection

Parameters:

o - element whose presence in this collection is to be ensured.

Returns:

true if the collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if the add method is not supported by this collection.

java.lang.NullPointerException - if this collection does not permit null elements, and the specified element is null.

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this collection.

java.lang.IllegalArgumentException - if some aspect of this element prevents it from being added to 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).

Specified by:

remove in interface java.util.Collection

Parameters:

o - element to be removed from this collection, if present.

Returns:

true if the collection contained the specified element.

Throws:

java.lang.UnsupportedOperationException - if the remove method is not supported by this collection.

containsAll

public boolean containsAll(java.util.Collection c)

Returns true if this collection contains all of the elements in the specified collection.

Specified by:

containsAll in interface java.util.Collection

Parameters:

c - collection to be checked for containment in this collection.

Returns:

true if this collection contains all of the elements in the specified collection.

Throws:

java.lang.NullPointerException - if the specified collection is null.

See Also:

contains(Object)

addAll

public boolean addAll(java.util.Collection c)

Adds all of the elements in the specified collection to this collection (optional operation).

Specified by:

addAll in interface java.util.Collection

Parameters:

c - collection whose elements are to be added to this collection.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if this collection does not support the addAll method.

java.lang.NullPointerException - if the specified collection is null.

See Also:

add(Object)

removeAll

public boolean removeAll(java.util.Collection c)

Removes from this collection all of its elements that are contained in the specified collection (optional operation).

Specified by:

removeAll in interface java.util.Collection

Parameters:

c - elements to be removed from this collection.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if the removeAll method is not supported by this collection.

java.lang.NullPointerException - if the specified collection is null.

See Also:

remove(Object), contains(Object)

retainAll

public boolean retainAll(java.util.Collection c)

Retains only the elements in this collection that are contained in the specified collection (optional operation).

Specified by:

retainAll in interface java.util.Collection

Parameters:

c - elements to be retained in this collection.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if the retainAll method is not supported by this Collection.

java.lang.NullPointerException - if the specified collection is null.

See Also:

remove(Object), contains(Object)

clear

public void clear()

Removes all of the elements from this collection (optional operation).

Specified by:

clear in interface java.util.Collection

Throws:

java.lang.UnsupportedOperationException - if the clear method is not supported by this collection.

toString

public java.lang.String toString()

Returns a string representation of this collection.

Returns:

a string representation of this collection.

iterator

public final java.util.Iterator iterator()

Please implement!

Note: If you return a ResourceIterator, the default implemntation of close( Iterator ) will know what to do.

Specified by:

iterator in interface ResourceCollection

Returns:

size

public abstract int size()

Returns the number of elements in this collection.

Specified by:

size in interface java.util.Collection

Returns:

Number of items, or Interger.MAX_VALUE

close

public final void close(java.util.Iterator close)

Clean up after any resources assocaited with this iteartor 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 ResourceCollection

Parameters:

close -

openIterator

protected abstract java.util.Iterator openIterator()

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().

Returns:

Iterator based on resource use

closeIterator

protected abstract void closeIterator(java.util.Iterator close)

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.

Parameters:

close - Iterator, will not be null

purge

public void purge()

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