org.opengis.feature
Interface FeatureCollection

All Superinterfaces:

Collection<Feature>, Feature, Iterable<Feature>

@XmlElement(value="FeatureCollection")
public interface FeatureCollection
extends Collection<Feature>, Feature

Represents a collection of features. Implementations and client code should adhere to the rules set forth by Collection. That is, some methods are optional to implement, and may throw an UnsupportedOperationException.

Since:

GeoAPI 2.0

See Also:

Collection

Method Summary

boolean	add(Feature o) Adds the given feature to this collection.
boolean	addAll(Collection<Feature> c) Adds all of the features contained in the given collection to this collection.
void	addFeatureListener(FeatureListener fl) Adds a listener whose methods will be called whenever a new feature is added or removed from this collection.
void	clear() Removes all of the features contained in this collection.
void	close() If some sort of connection was opened to a backing store to support this collection, then closes this connection.
boolean	contains(Feature o) Checks if the given feature is a member of this collection.
boolean	containsAll(Collection<Feature> c) Checks if every feature in the given collection is also a member of this feature collection.
LockRequest	getLockRequest() Returns the request indicating the duration for the lockAll(java.util.Collection) method.
Transaction	getTransaction() Retrieves the current transaction on this feature collection or null if there is no current transaction.
boolean	isEmpty() Returns true if this collection contains no Features.
FeatureIterator	iterator() Returns an iterator that enumerates all of the features in this collection.
LockResponse	lock() Lock this collection of features.
LockResponse	lockAll(Collection<Feature> c) Lock indicated features.
boolean	remove(Feature o) Removes the given feature from this collection.
boolean	removeAll(Collection<Feature> c) Removes the given features from this collection.
void	removeFeatureListener(FeatureListener fl) Removes a listener that was previously added with addFeatureListener(org.opengis.feature.FeatureListener).
boolean	retainAll(Collection<Feature> c) Removes any features from this collection that are not present in the given collection.
void	setLockRequest(LockRequest lock) Indicates the duration, and any additional information for any subsequent lock operations.
void	setTransaction(Transaction t) Begins a new transaction on this collection.
int	size() Returns the size of the collection, if known.
FeatureCollection	subCollection(Filter filter) Returns a collection whose contents are the subset of features in this collection that pass the given filter.
Object[]	toArray() Creates a Feature array and populates it.
Feature[]	toArray(Feature[] buffer) Populates the given array with the features in this collection.

Methods inherited from interface Collection

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

Methods inherited from interface Feature

getAttribute, getAttribute, getBounds, getFeatureType, getID, getParent, setAttribute, setAttribute

Method Detail

iterator

FeatureIterator iterator()
                         throws BackingStoreException

Returns an iterator that enumerates all of the features in this collection. The object returned from this method is always of type FeatureIterator.

Specified by:

iterator in interface Collection<Feature>

Specified by:

iterator in interface Iterable<Feature>

Throws:

BackingStoreException - If an error occurs while fetching the features.

toArray

Object[] toArray()
                 throws BackingStoreException,
                        OutOfMemoryError

Creates a Feature array and populates it.

Specified by:

toArray in interface Collection<Feature>

Throws:

BackingStoreException - If an error occurs while fetching the features.

OutOfMemoryError - if the feature collection is too large to fit into memory.

toArray

Feature[] toArray(Feature[] buffer)
                  throws BackingStoreException,
                         OutOfMemoryError

Populates the given array with the features in this collection. If the passed array is null or is not sufficiently large to contain all of the features in this collection, a new Feature array will be created and returned.

Throws:

BackingStoreException - If an error occurs while fetching the features.

OutOfMemoryError - if the feature collection is too large to fit into memory.

isEmpty

boolean isEmpty()
                throws BackingStoreException

Returns true if this collection contains no Features.

Specified by:

isEmpty in interface Collection<Feature>

Throws:

BackingStoreException - If an error occurs while checking for features.

size

@XmlElement(value="numberOfFeatures")
int size()
         throws BackingStoreException

Returns the size of the collection, if known. It may return -1 if the size is not known or would be too costly to compute (such as when the features are streaming from a remote source).

Specified by:

size in interface Collection<Feature>

Throws:

BackingStoreException - If an error occurs while checking for features.

contains

boolean contains(Feature o)
                 throws BackingStoreException

Checks if the given feature is a member of this collection.

Throws:

BackingStoreException - If an error occurs while searching the feature.

containsAll

boolean containsAll(Collection<Feature> c)
                    throws BackingStoreException

Checks if every feature in the given collection is also a member of this feature collection.

Throws:

BackingStoreException - If an error occurs while searching the features.

add

boolean add(Feature o)
            throws UnsupportedOperationException,
                   BackingStoreException

Adds the given feature to this collection. If this collection is backed by a persistent store of some kind, then the given feature should immediately be written to that persistent store. If you want to add multiple features to this collection, note that it may be considerably more efficient to call the addAll(java.util.Collection) method. The addition of features takes place within the context of the current transaction on this feature collection.

Specified by:

add in interface Collection<Feature>

Throws:

UnsupportedOperationException - if the addition of new features is not supported.

BackingStoreException - If an error occurs while adding the feature.

addAll

boolean addAll(Collection<Feature> c)
               throws UnsupportedOperationException,
                      BackingStoreException

Adds all of the features contained in the given collection to this collection. If this collection is backed by a persistent store of some kind, then the added features should immediately be written to that persistent store. The addition of features takes place within the context of the current transaction on this feature collection.

Throws:

UnsupportedOperationException - if the addition of new features is not supported.

BackingStoreException - If an error occurs while adding the features.

clear

void clear()
           throws UnsupportedOperationException,
                  BackingStoreException

Removes all of the features contained in this collection. If this collection is backed by a persistent store of some kind, then this method should cause all of the features from this collection to be removed from that persistent store. This operation takes place within the context of the current transaction on this feature collection.

Specified by:

clear in interface Collection<Feature>

Throws:

UnsupportedOperationException - if the removal of features is not supported.

BackingStoreException - If an error occurs while removing the features.

remove

boolean remove(Feature o)
               throws UnsupportedOperationException,
                      BackingStoreException

Removes the given feature from this collection. If this collection is backed by a persistent store of some kind, then this method should cause the given feature to be removed from the persistent store. This operation takes place within the context of the current transaction on this feature collection.

Throws:

UnsupportedOperationException - if the removal of features is not supported.

BackingStoreException - If an error occurs while removing the feature.

removeAll

boolean removeAll(Collection<Feature> c)
                  throws UnsupportedOperationException,
                         BackingStoreException

Removes the given features from this collection. If this collection is backed by a persistent store of some kind, then this method should cause all of the given features to be removed from the persistent store. This operation takes place within the context of the current transaction on this feature collection.

Throws:

UnsupportedOperationException - if the removal of features is not supported.

BackingStoreException - If an error occurs while removing the features.

retainAll

boolean retainAll(Collection<Feature> c)
                  throws UnsupportedOperationException,
                         BackingStoreException

Removes any features from this collection that are not present in the given collection. If this collection is backed by a persistent store of some kind, then this method should cause the removed features to be removed from the persistent store as well. This operation takes place within the context of the current transaction on this feature collection.

Throws:

UnsupportedOperationException - if the removal of features is not supported.

BackingStoreException - If an error occurs while removing the features.

subCollection

FeatureCollection subCollection(Filter filter)
                                throws BackingStoreException

Returns a collection whose contents are the subset of features in this collection that pass the given filter. This is semantically equivalent to going back to the FeatureStore that created this collection and AND-ing the filter that produced this collection with the given filter.

Compare this method to List.subList(int,int) from the Java Collections framework.

Throws:

BackingStoreException - If an error occurs while fetching the features.

close

void close()
           throws IOException

If some sort of connection was opened to a backing store to support this collection, then closes this connection. Users of this API should always call this method before releasing the references to this object so that resources get cleaned up in a timely fashion. Those who implement this interface are also encouraged to implement the finalize() method just in case the user forgets to call close so that perhaps things might get cleaned up.

After invoking this method, all references to the feature listener objects will be cleared and no further events will be fired.

Throws:

IOException

setTransaction

void setTransaction(Transaction t)

Begins a new transaction on this collection. Any calls that may modify this collection or any features within it are done within the context of the given transaction.

Implementors of this method should attach some state to the given transaction by calling Transaction.putState(java.lang.Object, org.opengis.feature.Transaction.State), passing in a key that identifies this type of collection and a value that is a data store-specific implementation of the Transaction.State interface. When the transaction is complete, either commit() or rollback() will be called on the state object that was attached.

getTransaction

Transaction getTransaction()

Retrieves the current transaction on this feature collection or null if there is no current transaction.

setLockRequest

void setLockRequest(LockRequest lock)

Indicates the duration, and any additional information for any subsequent lock operations.

Implementations may provide some TRANSACTION_LOCK constant to request that the lock only endure for the duration of the current transaction.

lockAll

LockResponse lockAll(Collection<Feature> c)

Lock indicated features. To unlock, or operate on these features, one needs to perform a transaction with the authorization token provided by LockResponse.

Workflows:

• LockRequest + AUTO_COMMIT returns a LockResponse indicating the success of the operation and authorization tokens aquired.
• TRANSACTION_LOCK + Transaction returns TRANSACTION_LOCKRESPONSE indicating a short term lock is held that will expire at the next commit or rollback. Use this workflow to reserve content before starting edits.
• LockRequest + Transaction returns PENDING. Check the result of commit to discover the success of any lock methods made during the transaction.

For a discussion of these workflows please read the package javadocs.

Returns:

Lock response for AUTO_COMMIT, TRANSACTION_LOCK for a short term lock, or PENDING when used in a transaction.

lock

LockResponse lock()

Lock this collection of features. To unlock, or operate on these features, one needs to perform a transaction with the authorization token provided by LockResponse.

Workflows:

• LockRequest + AUTO_COMMIT returns a LockResponse indicating the success of the operation and authorization tokens aquired.
• TRANSACTION_LOCK + Transaction returns TRANSACTION_LOCKRESPONSE indicating a short term lock is held that will expire at the next commit or rollback. Use this workflow to reserve content before starting edits.
• LockRequest + Transaction returns PENDING. Check the result of commit to discover the success of any lock methods made during the transaction.

For a discussion of these workflows please read the package javadocs.

Returns:

Lock response for AUTO_COMMIT, TRANSACTION_LOCK for a short term lock, or PENDING when used in a transaction.

getLockRequest

LockRequest getLockRequest()

Returns the request indicating the duration for the lockAll(java.util.Collection) method.

addFeatureListener

void addFeatureListener(FeatureListener fl)

Adds a listener whose methods will be called whenever a new feature is added or removed from this collection. Since FeatureCollection objects may be the result of a query, the methods of the FeatureListener may be invoked when a feature's attributes have been updated in such a way that its values now pass the filter (or no longer pass the filter).

removeFeatureListener

void removeFeatureListener(FeatureListener fl)

Removes a listener that was previously added with addFeatureListener(org.opengis.feature.FeatureListener).