<?php
/*
 * Specialized Database Abstraction Layer for the CLN
 *
 * This is a layer on top of the PEAR:DB layer, because we realized we wanted some
 * additional functionality, but at the same time, we didn't want to edit the PEAR
 * libraries directly, so that we could easily update them at a later date when
 * new versions arise. Another reason to abstract the DB one more layer is so that we
 * can change the DAL that we use at a later day, if we want to go to adodb for example
 * or phpLib.
 *
 * Copyright (c) 2003-4 St. Christopher House
 *
 * Developed by The Working Group Inc.
 *
 * 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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 * @version $Id: Cln_Db.php,v 1.7 2004/11/19 04:41:21 cbooth7575 Exp $
 *
 */

require_once 'DB.php';

class Cln_Db extends DB
{
    /**
     *
     * Based upon singleton code used in the PEAR:Log package, by Chuck Hagenbuch
     * <hide@address.com> and Jon Parise <hide@address.com>
     *
     * Attempts to return a reference to an existing DB instance for the $dsn, only
     * creating a new instance if no instance with the same $dsn
     * currently exists.
     *
     * You should use this if there are multiple places you might use a DB connection
     * and you don't want to create multiple connections, and you don't want to
     * check for the existance of one each time.
     *
     * <b>You MUST call this method with the $var = &Cln_Db::singleton() syntax.
     * Without the ampersand (&) in front of the method name, you will not get
     * a reference, you will get a copy.</b>
     *
     * @param string $dsn       A dsn for the database, similar to the one needed
     *                          for PEAR::DB
     *
     * @param string $query optional
     *                          An optional SQL query. If a query is passed, the connection
     *                          object will be made, but instead of it being returned,
     *                          a DB_Result object will be returned.
     *
     * @return object           The newly created concrete DB instance, or a result instance or
     *                          false on an error.
     * @access public
     */
    function &singleton($dsn, $query = null)
    {
        static $instances;

        if (!isset($instances)) {
            $instances = array();
        }

        if (!isset($instances[$dsn])) {
            $instances[$dsn] = &DB::connect($dsn); // :MAYBE: - check out the other parameter
                                                   // $options and see if we need to
                                                   // handle that one, if it ever will be used.
        }

        if ($query == null) {
            return $instances[$dsn];
        } else {
            return $instances[$dsn]->query($query);
        }
    }
}
?>