org.gvsig.fmap.dal.feature
Interface FeatureStore

All Superinterfaces:

ComplexObservable, ComplexWeakReferencingObservable, DataStore, Disposable, DynObject, Metadata, Observable, Persistent, UndoRedoStack, Visitable, WeakReferencingObservable

public interface FeatureStore
extends DataStore, UndoRedoStack

A FeatureStore is a type of store whose data consists on sets of Feature(s). Feature(s) from the same FeatureStore can be of different FeatureType(s) (as in GML format for instance).

FeatureStore allows:

• Obtaining the default FeatureType. A FeatureStore always has one and only one default FeatureType.
• Obtaining the list of FeatureType(s) defined in the FeatureStore.
• Obtaining, filtering and sorting subsets of data (FeatureSet) through FeatureQuery, as well as background loading.
• Obtaining the total Envelope (AKA bounding box or extent) of the store.
• Support for editing FeatureType(s).
• Obtaining information about contained Geometry types.
• Exporting to another store.
• Indexing.
• Selection.
• Locks management.

Field Summary

static String	METADATA_DEFINITION_NAME
static int	MODE_APPEND Indicates that this store is in append mode
static int	MODE_FULLEDIT Indicates that this store is in full edit mode
static int	MODE_QUERY Indicates that this store is in query mode

Fields inherited from interface org.gvsig.fmap.dal.DataStore

FEATURE_METADATA_DEFINITION_NAME, METADATA_CONTAINERNAME, METADATA_CRS, METADATA_ENVELOPE, METADATA_FEATURETYPE, METADATA_PROVIDER, SPATIAL_METADATA_DEFINITION_NAME

Method Summary

boolean	allowWrite() Indicates whether this store allows writing.
void	beginEditingGroup(String description) Initiates an editing group.
void	cancelEditing() Cancels all editing since the last edit().
boolean	canWriteGeometry(int gvSIGgeometryType) Deprecated. Mirar de cambiarlo a metadatos
void	createCache(String name, DynObject parameters) Creates a vectorial cache that is used to save and retrieve data.
FeatureQuery	createFeatureQuery() Returns a new FeatureQuery associated to this store.
FeatureSelection	createFeatureSelection() Creates a FeatureSelection
FeatureIndex	createIndex(FeatureType featureType, String attributeName, String indexName) Creates an index which will be applied to the features of the given type, by using the data of the given attribute.
FeatureIndex	createIndex(FeatureType featureType, String attributeName, String indexName, Observer observer) Creates an index which will be applied to the features of the given type, by using the data of the given attribute.
FeatureIndex	createIndex(String indexTypeName, FeatureType featureType, String attributeName, String indexName) Creates an index which will be applied to the features of the given type, by using the data of the given attribute.
FeatureIndex	createIndex(String indexTypeName, FeatureType featureType, String attributeName, String indexName, Observer observer) Creates an index which will be applied to the features of the given type, by using the data of the given attribute.
EditableFeature	createNewFeature() Creates a new feature using the default feature type and returns it as an EditableFeature
EditableFeature	createNewFeature(boolean defaultValues) Creates a new feature of default FeatureType.
EditableFeature	createNewFeature(FeatureType type, boolean defaultValues) Creates a new feature of the given FeatureType.
EditableFeature	createNewFeature(FeatureType type, Feature defaultValues) Creates a new feature of the given FeatureType and uses the given Feature as default values to initialize it.
void	delete(Feature feature) Deletes a Feature from the store.
void	edit() Enters editing state.
void	edit(int mode) Enters editing state specifying the editing mode.
void	endEditingGroup() Finishes an editing group.
void	export(DataServerExplorer explorer, String provider, NewFeatureStoreParameters params) Exports this store to another store.
void	finishEditing() Exits editing state.
FeatureCache	getCache()
FeatureType	getDefaultFeatureType() Returns this store's default FeatureType.
org.gvsig.fmap.geom.primitive.Envelope	getEnvelope() Returns this store's total envelope (extent).
Feature	getFeatureByReference(FeatureReference reference) Returns the feature given its reference.
Feature	getFeatureByReference(FeatureReference reference, FeatureType featureType) Returns the feature given its reference and feature type.
long	getFeatureCount() Returns featue count of this store.
FeatureSelection	getFeatureSelection() Returns the current FeatureSelection.
FeatureSet	getFeatureSet() Returns all available features in the store.
FeatureSet	getFeatureSet(FeatureQuery featureQuery) Returns a subset of features taking into account the properties and restrictions of the FeatureQuery.
void	getFeatureSet(FeatureQuery featureQuery, Observer observer) Loads a subset of features taking into account the properties and restrictions of the FeatureQuery.
void	getFeatureSet(Observer observer) Loads all available feature in the store.
FeatureType	getFeatureType(String featureTypeId) Returns this store's featureType FeatureType matches with featureTypeId.
List	getFeatureTypes() Returns this store's FeatureType(s).
FeatureIndexes	getIndexes() Returns a FeatureIndexes structure containing all available indexes in the store.
FeatureLocks	getLocks() Returns the set of locked features
DataStoreParameters	getParameters() Returns this store's parameters.
int	getRetrievedFeaturesLimit() If the FeatureStoreProvider.hasRetrievedFeaturesLimit() returns true, it returns the limit of features retrieved from the provider.
org.cresques.cts.IProjection	getSRSDefaultGeometry() Deprecated. use getDefaultFeatureType().getDefaultSRS()
FeatureStoreTransforms	getTransforms() Returns this store transforms
boolean	hasRetrievedFeaturesLimit() Return if the maximum number of features provided by the provider are limited.
void	insert(EditableFeature feature) Inserts a Feature in the store.
boolean	isAppending() Indicates whether this store is in appending state.
boolean	isAppendModeSupported() Indicates whether this store supports append mode.
boolean	isEditing() Indicates whether this store is in editing state.
boolean	isKnownEnvelope() Return if the provider knows the real envelope of a layer.
boolean	isLocksSupported() Indicates whether this store supports locks.
void	setSelection(FeatureSet selection) Sets the selection to the passed FeatureSet
void	update(EditableFeature feature) Updates a Feature in the store with the changes in the EditableFeature.
void	update(EditableFeatureType featureType) Updates a FeatureType in the store with the changes in the EditableFeatureType.
void	validateFeatures(int mode) Applies the validation rules associated to the given mode to the active FeatureSet.

Methods inherited from interface org.gvsig.fmap.dal.DataStore

accept, accept, createQuery, createSelection, getChildren, getDataSet, getDataSet, getDataSet, getDataSet, getExplorer, getFullName, getInterval, getName, getProviderName, getSelection, getTimes, getTimes, refresh, setSelection

Methods inherited from interface org.gvsig.tools.observer.ComplexObservable

beginComplexNotification, disableNotifications, enableNotifications, endComplexNotification

Methods inherited from interface org.gvsig.tools.observer.Observable

addObserver, deleteObserver, deleteObservers

Methods inherited from interface org.gvsig.tools.persistence.Persistent

loadFromState, saveToState

Methods inherited from interface org.gvsig.metadata.Metadata

getMetadataChildren, getMetadataID, getMetadataName

Methods inherited from interface org.gvsig.tools.dynobject.DynObject

clear, delegate, getDynClass, getDynValue, hasDynValue, implement, invokeDynMethod, invokeDynMethod, setDynValue

Methods inherited from interface org.gvsig.tools.dispose.Disposable

dispose

Methods inherited from interface org.gvsig.tools.undo.UndoRedoStack

canRedo, canUndo, getRedoInfos, getUndoInfos, redo, redo, undo, undo

Field Detail

METADATA_DEFINITION_NAME

static final String METADATA_DEFINITION_NAME

See Also:

Constant Field Values

MODE_QUERY

static final int MODE_QUERY

Indicates that this store is in query mode

See Also:

Constant Field Values

MODE_FULLEDIT

static final int MODE_FULLEDIT

Indicates that this store is in full edit mode

See Also:

Constant Field Values

MODE_APPEND

static final int MODE_APPEND

Indicates that this store is in append mode

See Also:

Constant Field Values

Method Detail

allowWrite

boolean allowWrite()

Indicates whether this store allows writing.

Returns:

true if this store can be written, false if not.

getDefaultFeatureType

FeatureType getDefaultFeatureType()
                                  throws DataException

Returns this store's default FeatureType.

Returns:

this store's default FeatureType.

Throws:

DataException

getFeatureType

FeatureType getFeatureType(String featureTypeId)
                           throws DataException

Returns this store's featureType FeatureType matches with featureTypeId.

Parameters:

featureTypeId -

Returns:

this store's default FeatureType.

Throws:

DataException

getFeatureTypes

List getFeatureTypes()
                     throws DataException

Returns this store's FeatureType(s).

Returns:

a list with this store's FeatureType(s).

Throws:

DataException

getParameters

DataStoreParameters getParameters()

Returns this store's parameters.

Specified by:

getParameters in interface DataStore

Returns:

DataStoreParameters containing this store's parameters

canWriteGeometry

boolean canWriteGeometry(int gvSIGgeometryType)
                         throws DataException

Deprecated. Mirar de cambiarlo a metadatos

Throws:

DataException

getEnvelope

org.gvsig.fmap.geom.primitive.Envelope getEnvelope()
                                                   throws DataException

Returns this store's total envelope (extent).

Returns:

this store's total envelope (extent) or null if store not have geometry information

Throws:

DataException

getSRSDefaultGeometry

org.cresques.cts.IProjection getSRSDefaultGeometry()
                                                   throws DataException

Deprecated. use getDefaultFeatureType().getDefaultSRS()

Returns:

Throws:

DataException

export

void export(DataServerExplorer explorer,
            String provider,
            NewFeatureStoreParameters params)
            throws DataException

Exports this store to another store.

Parameters:

explorer - DataServerExplorer target

params - New parameters of this store that will be used on the target explorer

Throws:

DataException

getFeatureSet

FeatureSet getFeatureSet()
                         throws DataException

Returns all available features in the store.

NOTE: if you use this method to get a FeatureSet, you must get sure it is disposed (@see Disposable.dispose()) in any case, even if an error occurs while getting the data. It is recommended to use the accept methods instead, which handle everything for you. Take into account the accept methods may use a fast iterator to get the features.

Returns:

a collection of features

Throws:

ReadException - if there is any error while reading the features

DataException

See Also:

DataStore.accept(org.gvsig.tools.visitor.Visitor)

getFeatureSet

FeatureSet getFeatureSet(FeatureQuery featureQuery)
                         throws DataException

Returns a subset of features taking into account the properties and restrictions of the FeatureQuery.

NOTE: if you use this method to get a FeatureSet, you must get sure it is disposed (@see Disposable.dispose()) in any case, even if an error occurs while getting the data. It is recommended to use the accept methods instead, which handle everything for you. Take into account the accept methods may use a fast iterator to get the features.

Parameters:

featureQuery - defines the characteristics of the features to return

Returns:

a collection of features

Throws:

ReadException - if there is any error while reading the features

DataException

See Also:

DataStore.accept(org.gvsig.tools.visitor.Visitor, org.gvsig.fmap.dal.DataQuery)

getFeatureSet

void getFeatureSet(FeatureQuery featureQuery,
                   Observer observer)
                   throws DataException

Loads a subset of features taking into account the properties and restrictions of the FeatureQuery. Feature loading is performed by calling the Observer, once each loaded Feature.

Parameters:

featureQuery - defines the characteristics of the features to return

observer - to be notified of each loaded Feature

Throws:

DataException - if there is any error while loading the features

getFeatureSet

void getFeatureSet(Observer observer)
                   throws DataException

Loads all available feature in the store. The loading of Features is performed by calling the Observer, once each loaded Feature.

Parameters:

observer - to be notified of each loaded Feature

Throws:

DataException - if there is any error while loading the features

getFeatureByReference

Feature getFeatureByReference(FeatureReference reference)
                              throws DataException

Returns the feature given its reference.

Parameters:

reference - a unique FeatureReference

Returns:

The Feature

Throws:

DataException

getFeatureByReference

Feature getFeatureByReference(FeatureReference reference,
                              FeatureType featureType)
                              throws DataException

Returns the feature given its reference and feature type.

Parameters:

reference - a unique FeatureReference

featureType - FeatureType to which the requested Feature belongs

Returns:

The Feature

Throws:

DataException

edit

void edit()
          throws DataException

Enters editing state.

Throws:

DataException

edit

void edit(int mode)
          throws DataException

Enters editing state specifying the editing mode.

Parameters:

mode -

Throws:

DataException

cancelEditing

void cancelEditing()
                   throws DataException

Cancels all editing since the last edit().

Throws:

DataException

finishEditing

void finishEditing()
                   throws DataException

Exits editing state.

Throws:

DataException

isEditing

boolean isEditing()

Indicates whether this store is in editing state.

Returns:

true if this store is in editing state, false if not.

isAppending

boolean isAppending()

Indicates whether this store is in appending state. In this state the new features are automatically inserted at the end of the FeatureSet.

Returns:

true if this store is in appending state.

update

void update(EditableFeatureType featureType)
            throws DataException

Updates a FeatureType in the store with the changes in the EditableFeatureType.
Any FeatureSet from this store that are used will be invalidated.

Parameters:

featureType - an EditableFeatureType with the changes.

Throws:

DataException

update

void update(EditableFeature feature)
            throws DataException

Updates a Feature in the store with the changes in the EditableFeature.
Any FeatureSet from this store that was still in use will be invalidated. You can override this using FeatureSet.update(EditableFeature).

Parameters:

feature - the feature to be updated

Throws:

DataException

delete

void delete(Feature feature)
            throws DataException

Deletes a Feature from the store.
Any FeatureSet from this store that was still in use will be invalidated. You can override this using Iterator.remove() from FeatureSet.

Parameters:

feature - The feature to be deleted.

Throws:

DataException

insert

void insert(EditableFeature feature)
            throws DataException

Inserts a Feature in the store.
Any FeatureSet from this store that was still in use will be invalidated. You can override this using FeatureSet.insert(EditableFeature).

Parameters:

feature - The feature to be inserted

Throws:

DataException

createNewFeature

EditableFeature createNewFeature()
                                 throws DataException

Creates a new feature using the default feature type and returns it as an EditableFeature

Returns:

a new feature in editable state

Throws:

DataException

createNewFeature

EditableFeature createNewFeature(FeatureType type,
                                 Feature defaultValues)
                                 throws DataException

Creates a new feature of the given FeatureType and uses the given Feature as default values to initialize it.

Parameters:

type - the new feature's feature type

defaultValues - a feature whose values are used as default values for the new feature.

Returns:

the new feature.

Throws:

DataException

createNewFeature

EditableFeature createNewFeature(FeatureType type,
                                 boolean defaultValues)
                                 throws DataException

Creates a new feature of the given FeatureType. The flag defaultValues is used to indicate whether the new feature should be initialized with default values or not.

Parameters:

type - the new feature's feature type

defaultValues - if true the new feature is initialized with each attribute's default value.

Returns:

the new feature

Throws:

DataException

createNewFeature

EditableFeature createNewFeature(boolean defaultValues)
                                 throws DataException

Creates a new feature of default FeatureType. The flag defaultValues is used to indicate whether the new feature should be initialized with default values or not.

Parameters:

defaultValues - if true the new feature is initialized with each attribute's default value.

Returns:

the new feature

Throws:

DataException

validateFeatures

void validateFeatures(int mode)
                      throws DataException

Applies the validation rules associated to the given mode to the active FeatureSet.

Parameters:

mode - can be one of {MODE_QUERY, MODE_FULLEDIT, MODE_APPEND}

Throws:

DataException

isAppendModeSupported

boolean isAppendModeSupported()

Indicates whether this store supports append mode.

Returns:

true if this store supports append mode.

beginEditingGroup

void beginEditingGroup(String description)
                       throws NeedEditingModeException

Initiates an editing group. This is typically used to group series of store editing operations.

Parameters:

description - Description of the editing group.

Throws:

NeedEditingModeException

endEditingGroup

void endEditingGroup()
                     throws NeedEditingModeException

Finishes an editing group.

Throws:

NeedEditingModeException

createIndex

FeatureIndex createIndex(FeatureType featureType,
                         String attributeName,
                         String indexName)
                         throws DataException

Creates an index which will be applied to the features of the given type, by using the data of the given attribute.

Parameters:

featureType - The FeatureType to which the indexed attribute belongs.

attributeName - The name of the attributed to be indexed

indexName - The index name

Returns:

the resulting FeatureIndex

Throws:

FeatureIndexException - if there is an error creating the index

DataException

createIndex

FeatureIndex createIndex(String indexTypeName,
                         FeatureType featureType,
                         String attributeName,
                         String indexName)
                         throws DataException

Creates an index which will be applied to the features of the given type, by using the data of the given attribute.

Parameters:

indexTypeName - the type of the index to be created. That name is related to one of the registered index providers

featureType - The FeatureType to which the indexed attribute belongs.

attributeName - The name of the attributed to be indexed

indexName - The index name

Returns:

the resulting FeatureIndex

Throws:

FeatureIndexException - if there is an error creating the index

DataException

createIndex

FeatureIndex createIndex(FeatureType featureType,
                         String attributeName,
                         String indexName,
                         Observer observer)
                         throws DataException

Creates an index which will be applied to the features of the given type, by using the data of the given attribute. This method will return without waiting for the index to be filled, as that will be performed in background. An optional Observer parameter is provided to be notified ( FeatureStoreNotification.INDEX_FILLING_SUCCESS ) when the index has finished filling with data and is available to be used.

Parameters:

featureType - The FeatureType to which the indexed attribute belongs.

attributeName - The name of the attributed to be indexed

indexName - The index name

observer - to notify to when the created index has finished filling with data and is available to be used. The observer will receive then a FeatureStoreNotification.INDEX_FILLING_SUCCESS notification, with the index object if it has finished successfully, or a FeatureStoreNotification.INDEX_FILLING_ERROR notification with the exception object if there has been any error in the process. Optional.

Returns:

the resulting FeatureIndex

Throws:

FeatureIndexException - if there is an error creating the index

DataException

See Also:

FeatureStoreNotification.INDEX_FILLING_STARTED, FeatureStoreNotification.INDEX_FILLING_SUCCESS, FeatureStoreNotification.INDEX_FILLING_CANCELLED, FeatureStoreNotification.INDEX_FILLING_ERROR

createIndex

FeatureIndex createIndex(String indexTypeName,
                         FeatureType featureType,
                         String attributeName,
                         String indexName,
                         Observer observer)
                         throws DataException

Creates an index which will be applied to the features of the given type, by using the data of the given attribute. This method will return without waiting for the index to be filled, as that will be performed in background. An optional Observer parameter is provided to be notified ( FeatureStoreNotification.INDEX_FILLING_SUCCESS ) when the index has finished filling with data and is available to be used.

Parameters:

indexTypeName - the type of the index to be created. That name is related to one of the registered index providers

featureType - The FeatureType to which the indexed attribute belongs.

attributeName - The name of the attributed to be indexed

indexName - The index name

observer - to notify to when the created index has finished filling with data and is available to be used. The observer will receive then a FeatureStoreNotification.INDEX_FILLING_SUCCESS notification, with the index object if it has finished successfully, or a FeatureStoreNotification.INDEX_FILLING_ERROR notification with the exception object if there has been any error in the process. Optional.

Returns:

the resulting FeatureIndex

Throws:

FeatureIndexException - if there is an error creating the index

DataException

See Also:

FeatureStoreNotification.INDEX_FILLING_STARTED, FeatureStoreNotification.INDEX_FILLING_SUCCESS, FeatureStoreNotification.INDEX_FILLING_CANCELLED, FeatureStoreNotification.INDEX_FILLING_ERROR

getIndexes

FeatureIndexes getIndexes()

Returns a FeatureIndexes structure containing all available indexes in the store.

Returns:

setSelection

void setSelection(FeatureSet selection)
                  throws DataException

Sets the selection to the passed FeatureSet

Parameters:

selection - A FeatureSet with the requested selection

Throws:

DataException

createFeatureSelection

FeatureSelection createFeatureSelection()
                                        throws DataException

Creates a FeatureSelection

Returns:

a FeatureSelection

Throws:

DataException

getFeatureSelection

FeatureSelection getFeatureSelection()
                                     throws DataException

Returns the current FeatureSelection.

Returns:

current FeatureSelection.

Throws:

DataException

isLocksSupported

boolean isLocksSupported()

Indicates whether this store supports locks.

Returns:

true if this store supports locks, false if not.

getLocks

FeatureLocks getLocks()
                      throws DataException

Returns the set of locked features

Returns:

set of locked features

Throws:

DataException

getTransforms

FeatureStoreTransforms getTransforms()

Returns this store transforms

Returns:

this store transforms

createFeatureQuery

FeatureQuery createFeatureQuery()

Returns a new FeatureQuery associated to this store.

Returns:

a new FeatureQuery associated to this store.

getFeatureCount

long getFeatureCount()
                     throws DataException

Returns featue count of this store.

Returns:

Throws:

DataException

createCache

void createCache(String name,
                 DynObject parameters)
                 throws DataException

Creates a vectorial cache that is used to save and retrieve data.

Parameters:

name - the cache name.

parameters - parameters to create the stores used to save data.

Throws:

DataException

getCache

FeatureCache getCache()

Returns:

the vectorial cache

isKnownEnvelope

boolean isKnownEnvelope()

Return if the provider knows the real envelope of a layer. If not, the FeatureStoreProvider.getEnvelope() method doesn't return the full envelope.

Returns:

if it knows the real envelope.

hasRetrievedFeaturesLimit

boolean hasRetrievedFeaturesLimit()

Return if the maximum number of features provided by the provider are limited.

Returns:

if there is a limit of features.

getRetrievedFeaturesLimit

int getRetrievedFeaturesLimit()

If the FeatureStoreProvider.hasRetrievedFeaturesLimit() returns true, it returns the limit of features retrieved from the provider.

Returns:

The limit of the retrieved features.