vos/metaobjects/property/db_property.hh

Go to the documentation of this file.

/* $Id: db_property.hh,v 1.12 2003/07/24 23:08:35 reed Exp $ */

/*
    @file db_property.hh
    
    Defines interface for property with database backend. 

    Copyright (C) 2001, 2002 Reed Hedges

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library 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
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

*/
#ifndef _DB_PROPERTY_HH_
#define _DB_PROPERTY_HH_

#include <string>
#include "property.hh"



/** @class DBProperty db_property.hh vos/metaobjects/property/db_property.hh
 *
 *  General database-backend interface. By itself this doesn't do anything; 
    use a subclass like PGDBProperty (For Postgres databases).  This class
    is intended to be subclassed in order to implement VOS/database
    bridges with various SQL-based database systems. Subclasses will
    have to implement the actual updateToDB() and updateFromDB(), and
    methods, and the open() method to connect to the database.
    See database-specific classes for full usage details but the basic idea 
    is that the constructor should open a connection to the database,
    and create the associated table and columns if they don't exist,
    or just fetch the existing values if they do.
    write() and replace() immediately update the database with new data,
    but read() only returns cached data. updateFromDB()
    will get values from the database and replace cached data, and send
    property-update messages to all property listeners and remote objects.
    Some mechanism should be set up to call this function when necesary
    If the database backend has no such functionality, then
    the the subclass should extend read() to do an update before a read,
    and also periodically call updateFromDB() in case it changes.

    Use init() to set up the queries used to read and write to the database.


    Subclasses of DBProperty should open the database connection (in init), and
    actually do the communication with the database.
*/
class DBProperty : public virtual LocalProperty 
{

protected:

    /* Query strings for getting stuff from the database. */
    string select_data_query;
    string select_type_query;
    string select_all_query;

    /* Query strings for setting stuff in the database. */
    string update_data_query;
    string update_type_query; // this is really not needed, because type is only updated on replace, and we should use update_all for that. but for now...
    string update_all_query;

    /* If this isn't empty (""), then this contains the constant datatype. */
    string force_type;

public:


    /** Database Access Error exception */
    class DBAccessError : public runtime_error {
        public: DBAccessError(const string& w) : runtime_error(w){};
    };


    /** basic constructor */
    DBProperty(MetaObject *superobject) : LocalProperty(superobject), Property(superobject), MetaObject(superobject)  {
        // lala
    }


    /** called by factory to create a new instance */
    static MetaObject* new_DBProperty(MetaObject* superobject, const string& type) {
        return new DBProperty(superobject);
    }
    
    /** Register MetaObject extender for DBProperty. You must also call Property::registerExtenders() for stuff to work!.
    */
    static void registerExtenders()  {
        LocalSite::addLocalObjectExtension(typeid(DBProperty).name(), &DBProperty::new_DBProperty);
    }

    /** Set up query strings, for getting or changing just data, with constant
        data type.
        @param select_query Query for getting just data. Must return scalar.
        @param update_query Query for setting the data. %d is replaced with the new data.
        @param type Data type to always use.
    */

    virtual void init(const string& select_query, const string& update_query, const string& type);

    /** Set up query strings, for getting or changing both data value and data type.
        In the update queries, %d will
        be replaced by property data, and %t will be replaced by the datatype.
        These query strings should be in the format applicable to the 
        implementation subclass you are using.
        @param select_all_q Query for getting data and type. (in that order)
        @param select_data_q    Query for getting just data. 
        @param select_type_q    Query for getting type.
        @param update_all_q Query for changing data and type. %d will be replaced by property data, and %t with type 
        @param update_data_q    Query for changing data. %d will be replaced by data.
        @param update_type_q    Query for changing type. Eventually will be removed, in favor of the update_all query @deprecated.
    */
    virtual void init(const string& select_all_q, const string& select_data_q, const string& select_type_q, const string& update_all_q, const string& update_data_q, const string& update_type_q) ;

    /** Use given values to construct standard (I think) SQL query strings. 
        @warning may be broken; untested by author; use at own risk.....  but then send a patch, please :) 
        @param table    Name of the table we are interested in.
        @param name_col Column in the table used as primary key when looking up data. 
        @param val_col  Column containing property value.
        @param type_col Column containing property data type.
        @param name_val Value to use to identify this property in the database, as primary key.
    */
    void init_components(const string& table, const string& name_col, const string& val_col, const string& type_col, const string& name_val) ;

    /** change property data, starting at given byte (updated in DB) */
    virtual void write(int start, const string& newdata) throw(DBAccessError) {
        LocalProperty::write(start, newdata);
        updateToDB();
    }

    /** change all the property data, and datatype (updated in DB) */
    virtual void replace(const string& newdata, const string& newtype = "?") throw(DBAccessError) {
        LocalProperty::replace(newdata, newtype);
        updateToDB();
    }
        

    /** open database. this method must be overridden in implementation subclasses. */
    virtual void open(string dbinfo = "") {
        cout << "** OPEN: " << dbinfo << "\n";
    }

    /** perform a query on the database (in the implementation's language; e.g. SQL) This method must be overridden in implementation subclasses.  This method
    may throw range_error if there is an error in the query-string substiution.
    TODO: how shall non-scalars be returned?
    */

    virtual string queryDB(const string& query) throw(DBAccessError) {
        cout << "** QUERY: " << query << "\n";
        return "**UNIMPLEMENTED**";
    }

    /** fetch stuff from database and do a replace. */
    virtual void updateFromDB() throw(DBAccessError) ;
            
    /** write current data and type to DB. */
    virtual void updateToDB() throw(DBAccessError) ;



private:
    /* Do replacement of substring key with value on s.  Note: only replaces the first key in s.
        throws range_error exception if key is not found in s.
    */
    static string sreplace( const string& s, const string& key, const string& value) throw (range_error);

};


#endif

---