/* Copyright (C) 2007 con terra GmbH (http://www.conterra.de)
 * All rights reserved
 *
 * $Id: Datasource.java,v 1.4 2008/01/30 12:38:34 blume Exp $
 *
 * created by:      drewnak
 * created at :     21.11.2007
 * created at :     14:25:50
 *
 * modified by:     $Author: blume $
 * modified at:     $Date: 2008/01/30 12:38:34 $
 */
package de.intevation.gnv.geobackend.sde.datasources;

import java.util.Map;

import de.intevation.gnv.geobackend.sde.datasources.exception.DatasourceException;

/**
 * Abstract class for handling different datasources.
 * This method provides a static method for creating dataosurce objects.
 *
 * @author drewnak
 */
public abstract class Datasource {

    protected Map mParameters;

    protected String mName;


    /**
     * Triggers the creation of a dataosurce object. Following the guidelines, the parameters for creating this datasource are delivered by the configuration file.
     *
     * @param pName      a name for the datasource.
     * @param pClassname The name of the class extending this abstract datasource class. Used to create a new instance.
     * @param pParams    a Map of Parameters needed for the initialization of the datasource.
     * @return a datasourceobject
     * @throws DatasourceException if the class could not be found or the initialization of the datasource fails.
     */
    public static final Datasource create(String pName, String pClassname,
                                          Map pParams) throws DatasourceException {
        Class lDatasourceClass;
        try {
            lDatasourceClass = Class.forName(pClassname);
        } catch (ClassNotFoundException e) {
            throw new DatasourceException("Could not load class " + pClassname);
        }
        Datasource lNewInstance;
        try {
            lNewInstance = (Datasource) lDatasourceClass.newInstance();
        } catch (Exception e) {
            throw new DatasourceException("Could not create instance of " + pClassname, e);
        }
        lNewInstance.init(pName, pParams);

        return lNewInstance;
    }

    /**
     * An abstract method for the initialization of a datasource instance.
     * Of course, only the concrete implementation knwos about the ncessary parameters for the initialization.
     *
     * @param pName   a name for the datasource.
     * @param pParams a Map of Parameters needed for the initialization of the datasource.
     */
    protected abstract void init(String pName, Map pParams) throws DatasourceException;

    /**
     * @return
     */
    public String getName() {
        return mName;
    }


    /**
     * This method returns a datasourceconnection.
     * Only the concrete implementation of the Datasource knwos about the DatasourceConnection-Implementation to return.
     *
     * @return a DatasourceConnection
     */
    public abstract DatasourceConnection getConnection();

    /**
     * Returns a DatasourceConnection. This method is usualy called after an executed query.
     * See: Some datasource implementations need to explicitly close an existing connection.
     *
     * @param pConnection the connection to be returned.
     */
    public abstract void returnConnection(DatasourceConnection pConnection);
}