| gvSIG desktop 1

package org.gvsig.fmap.dal;

import java.util.Iterator;

import org.gvsig.fmap.dal.exception.DataException;

import org.gvsig.metadata.Metadatable;

import org.gvsig.tools.observer.ComplexWeakReferencingObservable;

import org.gvsig.tools.observer.Observer;

import org.gvsig.tools.operations.Operations;

import org.gvsig.tools.persistence.Persistent;

/**

 * <p>This is the basic interface for all data stores. Depending on the context, 

 * it can represent a geographic layer, an alphanumeric database table or any data file. 

 * DataStore offers generic services like:

 *   <ul>

 *     <li>Open, close and reject data stores</li>

 *     <li>Access to data sets, with the possibility of loading data 

 *             in background.</li>

 *     <li>Use of selection and locks, as well as data sets</li>

 *     <li>Editing</li>

 *     <li>Register of event observers through the Observable interface</li>

 *     <li>Access to data stores embedded into itself (like GML)</li>

 *     <li>Information about the Spatial Reference Systems used by the data store</li>

 *   </ul>

 * </p>

 * <br>

 *

 */

public interface DataStore extends ComplexWeakReferencingObservable, Metadatable, Persistent,

                Operations {

        /**

         * Returns this store's name.

         * 

         * @return String containing this store's name.

         */

        public String getName();

        /**

         * Return the of parameters of this store

         *

         * @return parameters of this store

         */

        public DataStoreParameters getParameters();

        /**

         * Refreshes this store state.

         * 

         * @throws DataException

         */

        public void refresh() throws DataException;

        /**

         * Frees this store's resources

         * 

         * @throws DataException

         */

        public void dispose() throws DataException;

        /**

         * Returns all available data.

         *

         * @return a set of data

         * @throws DataException

         *             if there is any error while loading the data

         */

        DataSet getDataSet() throws DataException;

        /**

         * Returns a subset of data taking into account the properties and

         * restrictions of the DataQuery.

         *

         * @param dataQuery

         *            defines the properties of the requested data

         * @return a set of data

         * @throws DataException

         *             if there is any error while loading the data

         */

        DataSet getDataSet(DataQuery dataQuery) throws DataException;

        /**

         * Loads all available data and notifies the observer for each loaded block of data.

         *

         * @param observer

         *            to be notified for each block of data loaded

         * @throws DataException

         *             if there is any error while loading the data

         */

        void getDataSet(Observer observer) throws DataException;

        /**

         * Loads a subset of data taking into account the properties and

         * restrictions of the DataQuery. Data loading is performed by calling the

         * Observer, once each data block is loaded.

         *

         * @param dataQuery

         *            defines the properties of the requested data         

         * @param observer

         *            to be notified for each block of data loaded

         * @throws DataException

         *             if there is any error while loading the data

         */

        void getDataSet(DataQuery dataQuery, Observer observer) throws DataException;

        /**

         * Returns the selected set of data

         * 

         * @return DataSet

         */

        public DataSet getSelection() throws DataException;

        /**

         * Sets the current data selection with the given data set.

         * 

         * @param DataSet

         *            selection

         * @throws DataException

         */

        public void setSelection(DataSet selection) throws DataException;

        /**

         * Creates a new selection.

         *

         * @return DataSet that contains the selection

         * 

         * @throws DataException

         */

        public DataSet createSelection() throws DataException;

        /**

         * Returns an iterator over this store children

         * 

         * @return Iterator over this DataStore children

         */

        public Iterator getChildren();

        /**

         * Returns the DataServerExplorer to which this DataStore belongs, if there is any.

         * 

         * @return DataServerExplorer to which this DataStore belongs, or <code>null</code> if 

         *                    this was not accessed through any DataServerExplorer.

         * 

         * @throws DataException

         */

        public DataServerExplorer getExplorer() throws DataException;

}