/*$************************************************************************************************
**
** $Id: FeatureCollection.java 831 2006-05-01 00:27:23Z Desruisseaux $
**
** $URL: http://svn.code.sf.net/p/geoapi/code/branches/2.0.x/geoapi/src/main/java/org/opengis/feature/FeatureCollection.java $
**
** Copyright (C) 2005 Open GIS Consortium, Inc.
** All Rights Reserved. http://www.opengis.org/legal/
**
*************************************************************************************************/
package org.opengis.feature;
// J2SE direct dependencies
import java.io.IOException;
import java.util.Collection;
import java.util.Iterator;
// OpenGIS direct dependencies
import org.opengis.filter.Filter;
//import org.opengis.filter.sort.SortBy;
// Annotations
import org.opengis.annotation.Extension;
import org.opengis.annotation.XmlElement;
/**
* Represents a collection of {@linkplain Feature features}. Implementations and client code
* should adhere to the rules set forth by {@link java.util.Collection}. That is, some methods
* are optional to implement, and may throw an {@link UnsupportedOperationException}.
*
* @author Ian Turton (CCG)
* @author Rob Hranac (VFNY)
* @author Ian Schneider (USDA-ARS)
* @since GeoAPI 2.0
*
* @see java.util.Collection
*/
@XmlElement("FeatureCollection")
public interface FeatureCollection extends Collection, Feature {
/**
* Returns an iterator that enumerates all of the features in this
* collection. The object returned from this method is always of type
* {@link FeatureIterator}.
*
* @throws BackingStoreException If an error occurs while fetching the features.
*/
/*{FeatureIterator}*/ Iterator iterator() throws BackingStoreException;
/**
* Creates a {@link Feature} array and populates it.
*
* @throws BackingStoreException If an error occurs while fetching the features.
* @throws OutOfMemoryError if the feature collection is too large to fit into memory.
*/
Object[] toArray() 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.
* @throws OutOfMemoryError if the feature collection is too large to fit into memory.
*/
/*{Feature}*/ Object[] toArray(/*{Feature}*/ Object[] buffer)
throws BackingStoreException, OutOfMemoryError;
/**
* Returns {@code true} if this collection contains no {@link Feature}s.
*
* @throws BackingStoreException If an error occurs while checking for features.
*/
boolean isEmpty() 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).
*
* @throws BackingStoreException If an error occurs while checking for features.
*/
@XmlElement("numberOfFeatures")
int size() throws BackingStoreException;
/**
* Checks if the given feature is a member of this collection.
*
* @throws BackingStoreException If an error occurs while searching the feature.
*/
boolean contains(/*{Feature}*/ Object o) 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.
*/
boolean containsAlls(Collection c) throws 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 {@link #addAll} method. The addition of
* features takes place within the context of the current
* {@linkplain Transaction transaction} on this feature collection.
*
* @throws UnsupportedOperationException if the addition of new features is not supported.
* @throws BackingStoreException If an error occurs while adding the feature.
*/
boolean adds(/*{Feature}*/ Object o) 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 {@linkplain Transaction transaction}
* on this feature collection.
*
* @throws UnsupportedOperationException if the addition of new features is not supported.
* @throws BackingStoreException If an error occurs while adding the features.
*/
boolean addAlls(Collection c) 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 {@linkplain Transaction transaction} on this
* feature collection.
*
* @throws UnsupportedOperationException if the removal of features is not supported.
* @throws BackingStoreException If an error occurs while removing the features.
*/
void clear() 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
* {@linkplain Transaction transaction} on this feature collection.
*
* @throws UnsupportedOperationException if the removal of features is not supported.
* @throws BackingStoreException If an error occurs while removing the feature.
*/
boolean remove(/*{Feature}*/ Object o) 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
* {@linkplain Transaction transaction} on this feature collection.
*
* @throws UnsupportedOperationException if the removal of features is not supported.
* @throws BackingStoreException If an error occurs while removing the features.
*/
boolean removeAlls(Collection 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 {@linkplain Transaction transaction}
* on this feature collection.
*
* @throws UnsupportedOperationException if the removal of features is not supported.
* @throws BackingStoreException If an error occurs while removing the features.
*/
boolean retainAlls(Collection c) throws UnsupportedOperationException, 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 {@link FeatureStore} that created this collection
* and AND-ing the filter that produced this collection with the given filter.
*
* Compare this method to {@link java.util.List#subList(int,int)}
* from the Java Collections framework.
*
* @throws BackingStoreException If an error occurs while fetching the features.
*/
FeatureCollection subCollection(Filter filter) throws BackingStoreException;
/** Returns an ordered feature collection whoes concepts are sorted
* according to the provided order.
*
* You may cascade several sort calls together to acomplish grouping.
* @param order
* @return FeatureList in the indicated order
* @throws BackingStoreException
*/
//FeatureList sort( SortBy order ) throws BackingStoreException;
/**
* 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 {@link Object#finalize 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.
*/
void close() throws IOException;
/**
* 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 {@link Transaction#putState}, passing in a
* key that identifies this type of collection and a value that is a
* data store-specific implementation of the {@link Transaction.State}
* interface. When the transaction is complete, either
* {@link Transaction.State#commit() commit()} or
* {@link Transaction.State#rollback() rollback()}
* will be called on the state object that was attached.
*/
void setTransaction(Transaction t);
/**
* Retrieves the current transaction on this feature collection or null if
* there is no current transaction.
*/
Transaction getTransaction();
/**
* Indicates the duration, and any additional information for any
* subsequent lock operations.
*
* Implementations may provide some {@code TRANSACTION_LOCK} constant to request that the
* lock only endure for the duration of the current {@linkplain Transaction transaction}.
*/
void setLockRequest(LockRequest lock);
/**
* Lock indicated features.
* To unlock, or operate on these features, one needs to perform a
* {@linkplain Transaction transaction} with the authorization token provided
* by {@link LockResponse}.
*
* Workflows:
*
* - {@link LockRequest} + {@link Transaction#AUTO_COMMIT AUTO_COMMIT} returns a
* {@link LockResponse} indicating the success of the operation and authorization
* tokens aquired.
* - {@code TRANSACTION_LOCK} + {@link Transaction} returns {@code 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.
* - {@link LockRequest} + {@link Transaction} returns {@code 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
* {@linkplain org.opengis.feature package javadocs}.
*
* @return Lock response for {@link Transaction#AUTO_COMMIT AUTO_COMMIT},
* {@code TRANSACTION_LOCK} for a short term lock, or {@code PENDING}
* when used in a {@linkplain Transaction transaction}.
*/
LockResponse lockAll(Collection c);
/**
* Lock this collection of features. To unlock, or operate on these features, one needs
* to perform a {@linkplain Transaction transaction} with the authorization token provided
* by {@link LockResponse}.
*
* Workflows:
*
* - {@link LockRequest} + {@link Transaction#AUTO_COMMIT AUTO_COMMIT} returns a
* {@link LockResponse} indicating the success of the operation and authorization
* tokens aquired.
* - {@code TRANSACTION_LOCK} + {@link Transaction} returns {@code 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.
* - {@link LockRequest} + {@link Transaction} returns {@code 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
* {@linkplain org.opengis.feature package javadocs}.
*
* @return Lock response for {@link Transaction#AUTO_COMMIT AUTO_COMMIT},
* {@code TRANSACTION_LOCK} for a short term lock, or {@code PENDING}
* when used in a {@linkplain Transaction transaction}.
*/
LockResponse lock();
/**
* Returns the request indicating the duration for the {@link #lockAll} method.
*/
LockRequest getLockRequest();
/**
* Adds a listener whose methods will be called whenever a new feature is
* added or removed from this collection. Since {@code FeatureCollection} objects
* may be the result of a query, the methods of the {@code 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).
*/
void addFeatureListener(FeatureListener fl);
/**
* Removes a listener that was previously added with {@link #addFeatureListener}.
*/
void removeFeatureListener(FeatureListener fl);
}
Ads help maintain this website.