| gvSIG desktop 1

/* gvSIG. Geographic Information System of the Valencian Government

 *

 * Copyright (C) 2007-2008 Infrastructures and Transports Department

 * of the Valencian Government (CIT)

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

 * MA  02110-1301, USA.

 *

 */

/*

 * AUTHORS (In addition to CIT):

 * 2008 IVER T.I. S.A.   {{Task}}

 */

package org.gvsig.fmap.dal;

import java.util.List;

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

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

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

import org.gvsig.fmap.dal.feature.FeatureIndex;

import org.gvsig.fmap.dal.feature.spi.index.FeatureIndexProvider;

import org.gvsig.fmap.dal.resource.ResourceManager;

import org.gvsig.tools.dynobject.DynObject;

import org.gvsig.tools.evaluator.Evaluator;

/**

 * There are two top level management roles within DAL: data access and resource

 * management.

 * 

 * This class is responsible of the data access management role. It provides

 * ways for registering and instantiating {@link DataServerExplorer}(s),

 * {@link DataStore}(s), {@link Evaluator}(s) and {@link FeatureIndex}(es).

 * 

 * @see ResourceManager

 * 

 */

public interface DataManager {

        /**

         * Returns the default DAL's temporary directory

         * 

         * @return Temporary directory name

         */

        public String getTemporaryDirectory();

        /*

         * ====================================================================

         * 

         * Store related services

         */

        /**

         * Creates, initializes and returns an instance of DataStoreParameters given

         * the name with which their provider is registered.

         * 

         * @param name

         *            provider name

         * 

         * @throws InitializeException

         * 

         * @throws InitializeException

         * @throws ProviderNotRegisteredException

         **/

        public DataStoreParameters createStoreParameters(String name)

                        throws InitializeException, ProviderNotRegisteredException;

        /**

         * Creates, initializes and returns an instance of NewDataStoreParameters

         * given the name with which their provider is registered.

         * 

         * @param name

         * 

         * @throws InitializeException

         * @throws ProviderNotRegisteredException

         */

        public NewDataStoreParameters createNewStoreParameters(String explorer, String provider)

                        throws InitializeException, ProviderNotRegisteredException;

        /**

         * 

         * Creates, initializes and returns an instance of DataStore given the

         * DataStoreParameters.

         * 

         * @param name of the provider

         * @param parameters

         *            parameters used to instantiate and initialize the DataStore

         * 

         * @throws InitializeException

         * 

         * @throws ProviderNotRegisteredException

         * @throws ValidateDataParametersException

         **/

        public DataStore openStore(String provider, DataStoreParameters parameters)

                        throws InitializeException, ProviderNotRegisteredException,

                        ValidateDataParametersException;

        /**

         * @deprecated see openStore

         */

        public DataStore createStore(DataStoreParameters parameters)

                        throws InitializeException, ProviderNotRegisteredException,

                        ValidateDataParametersException;

        /**

         * Create a new physical store 

         *  

         * @param parameters

         *

         * @throws InitializeException

         * @throws ProviderNotRegisteredException

         * @throws ValidateDataParametersException

         */

        public void newStore(String explorer, String provider, NewDataStoreParameters parameters, boolean overwrite)

                        throws InitializeException, ProviderNotRegisteredException,

                        ValidateDataParametersException;

        /**

         * Returns a list of Strings containing the names of all available DataStore

         * providers.

         * 

         * @return list of String containing available DataStore provider names

         */

        public List getStoreProviders();

        /**

         * Returns a list of Strings containing the names of all available DataStore

         * providers for an explorer.

         * 

         * @param explorer

         *            name

         */

        public List getStoreProviders(String name);

        /*

         * ====================================================================

         * 

         * Explorer related services

         */

        /**

         * Returns an instance of {@link DataServerExplorerParameters} corresponding

         * to the given name.

         * 

         * @param name

         *            name of a registered server explorer provider

         * 

         * @throws InitializeException

         *             if parameter initialization causes an error.

         * 

         * @throws ProviderNotRegisteredException

         *             if could not find a provider by the given name.

         * 

         **/

        public DataServerExplorerParameters createServerExplorerParameters(

                        String name) throws InitializeException,

                        ProviderNotRegisteredException;

        /**

         * Returns an instance of {@link DataServerExplorer} given its parameters.

         * 

         * @param name of the explorer

         * @param parameters

         *            parameters used to instantiate and initialize the

         *            {@link DataServerExplorer}.

         * 

         * @return an instance of {@link DataServerExplorer}.

         * 

         * @throws InitializeException

         * 

         * @throws ProviderNotRegisteredException

         * @throws ValidateDataParametersException

         */

        public DataServerExplorer openServerExplorer(

                        String name,

                        DataServerExplorerParameters parameters)

                        throws InitializeException, ProviderNotRegisteredException,

                        ValidateDataParametersException;

        /**

         * @deprecated see openServerExplorer

         */

        public DataServerExplorer createServerExplorer(

                        DataServerExplorerParameters parameters)

                        throws InitializeException, ProviderNotRegisteredException,

                        ValidateDataParametersException;

        /**

         * Returns a list of String containing the names of the available

         * DataServerExplorer providers.

         * 

         * @return list of String containing the names of the available

         *         DataServerExplorer providers.

         */

        public List getExplorerProviders();

        /*

         * ====================================================================

         * 

         * Expression evaluation related services

         */

        /**

         * Registers the default expression evaluator. It is used by DAL to evaluate

         * and resolve query filters and expressions.

         * 

         * @param evaluator

         *            Class that will be called to evaluate the expression. It must

         *            implement {@link Evaluator}.

         */

        public void registerDefaultEvaluator(Class evaluator);

        /**

         * Creates an instance of Evaluator that represents the given expression.

         * 

         * @param expression

         *            String containing a CQL expression.

         * @return instance of Evaluator representing the given expression.

         * @throws InitializeException

         */

        public Evaluator createExpresion(String expression)

                        throws InitializeException;

        /*

         * ====================================================================

         * 

         * Index related services

         */

        /**

         * Returns a list of String containing the names of the available index

         * providers.

         * 

         * @return list of strings with the names of the available index providers

         */

        public List getFeatureIndexProviders();

        /**

         * Sets the default DataIndexProvider for the given data type.

         * 

         * @param dataType

         *            one of the data types defined in {@link DataTypes}.

         * @param name

         *            Provider's name

         */

        public void setDefaultFeatureIndexProviderName(int dataType, String name);

        /**

         * Returns the default DataIndexProvider name, given a data type. Data types

         * are defined in {@link DataTypes}.

         * 

         * @param dataType

         *            one of the constants in {@link DataTypes}.

         * 

         * @return the name of the default {@link FeatureIndexProvider} if there is

         *         anyone available for the given data type.

         */

        public String getDefaultFeatureIndexProviderName(int dataType);

        /**

         * Returns a list of String containing the names of the available cache

         * providers.

         * 

         * @return list of strings with the names of the available cache providers

         */

        public List getFeatureCacheProviders();

        /**

         * Returns an instance of {@link DataServerExplorerParameters} corresponding to

         * the given name used by the cache to create a store to save the retrieved data.

         *

         * @param name

         *            name of a registered feature cache provider

         *

         * @throws InitializeException

         *                         if parameter initialization causes an error.

         *

         * @throws ProviderNotRegisteredException

         *                         if could not find a cache provider by the given name.

         *

         **/

    public DynObject createCacheParameters(String name) throws InitializeException, 

            ProviderNotRegisteredException;

}