connection.h

/* This file is part of the KDE project
   Copyright (C) 2003-2007 Jaroslaw Staniek <js@iidea.pl>
 
   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library 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
   Library General Public License for more details.
 
   You should have received a copy of the GNU Library General Public License
   along with this program; see the file COPYING.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
*/
 
#ifndef KEXIDB_CONNECTION_H
#define KEXIDB_CONNECTION_H
 
#include <tqobject.h>
#include <tqstringlist.h>
#include <tqintdict.h>
#include <tqdict.h>
#include <tqptrdict.h>
#include <tqvaluevector.h>
#include <tqvaluelist.h>
#include <tqvariant.h>
#include <tqguardedptr.h>
 
#include <kexidb/object.h>
#include <kexidb/connectiondata.h>
#include <kexidb/tableschema.h>
#include <kexidb/queryschema.h>
#include <kexidb/queryschemaparameter.h>
#include <kexidb/transaction.h>
#include <kexidb/driver.h>
#include <kexidb/preparedstatement.h>
 
#include <kexiutils/tristate.h>
 
namespace KexiDB {
 
typedef TQValueVector<TQVariant> RowData; 
 
class Cursor;
class ConnectionPrivate;
class RowEditBuffer;
class DatabaseProperties;
class AlterTableHandler;
 
class KEXI_DB_EXPORT Connection : public TQObject, public KexiDB::Object
{
    TQ_OBJECT
  
 
    public:
 
        virtual ~Connection();
 
        ConnectionData* data() const;
 
        inline Driver* driver() const { return m_driver; }
 
        bool connect();
 
        bool isConnected() const;
 
        bool isDatabaseUsed() const;
 
        virtual bool isReadOnly() const;
 
        virtual void clearError();
 
        bool disconnect();
 
        TQStringList databaseNames(bool also_system_db = false);
 
        bool databaseExists( const TQString &dbName, bool ignoreErrors = true );
 
        bool createDatabase( const TQString &dbName );
 
        bool useDatabase( const TQString &dbName, bool kexiCompatible = true, bool *cancelled = 0, 
            MessageHandler* msgHandler = 0 );
 
        bool closeDatabase();
 
        TQString currentDatabase() const;
 
        bool dropDatabase( const TQString &dbName = TQString() );
 
        TQStringList objectNames(int objType = KexiDB::AnyObjectType, bool* ok = 0);
 
        TQStringList tableNames(bool also_system_tables = false);
 
        static const TQStringList& kexiDBSystemTableNames();
 
        KexiDB::ServerVersionInfo* serverVersion() const;
 
        KexiDB::DatabaseVersionInfo* databaseVersion() const;
 
        DatabaseProperties& databaseProperties();
 
        TQValueList<int> tableIds();
 
        TQValueList<int> queryIds();
 
        TQValueList<int> objectIds(int objType);
 
        Transaction beginTransaction();
 
        bool commitTransaction( Transaction trans = Transaction::null,
            bool ignore_inactive = false );
        
        bool rollbackTransaction( Transaction trans = Transaction::null,
            bool ignore_inactive = false );
        
        Transaction& defaultTransaction() const;
 
        void setDefaultTransaction(const Transaction& trans);
        
        const TQValueList<Transaction>& transactions();
 
        bool autoCommit() const;
 
        bool setAutoCommit(bool on);
 
//js: MOVED TO Driver       virtual TQString escapeString(const TQString& str) const = 0;
//      virtual TQCString escapeString(const TQCString& str) const = 0;
        
        virtual Cursor* prepareQuery( const TQString& statement, uint cursor_options = 0) = 0;
 
        Cursor* prepareQuery( QuerySchema& query, const TQValueList<TQVariant>& params, 
            uint cursor_options = 0 );
 
        virtual Cursor* prepareQuery( QuerySchema& query, uint cursor_options = 0 ) = 0;
 
        Cursor* prepareQuery( TableSchema& table, uint cursor_options = 0);
 
        Cursor* executeQuery( const TQString& statement, uint cursor_options = 0 );
 
        Cursor* executeQuery( QuerySchema& query, const TQValueList<TQVariant>& params, 
            uint cursor_options = 0 );
 
        Cursor* executeQuery( QuerySchema& query, uint cursor_options = 0 );
 
        Cursor* executeQuery( TableSchema& table, uint cursor_options = 0 );
 
        bool deleteCursor(Cursor *cursor);
 
        TableSchema* tableSchema( int tableId );
        
        TableSchema* tableSchema( const TQString& tableName );
        
        QuerySchema* querySchema( int queryId );
 
        QuerySchema* querySchema( const TQString& queryName );
 
        bool setQuerySchemaObsolete( const TQString& queryName );
 
//js: MOVED TO Driver       TQString valueToSQL( const Field::Type ftype, const TQVariant& v ) const;
//      TQString valueToSQL( const Field *field, const TQVariant& v ) const;
 
        tristate querySingleRecord(const TQString& sql, RowData &data, bool addLimitTo1 = true);
 
        tristate querySingleRecord(QuerySchema& query, RowData &data, bool addLimitTo1 = true);
 
        tristate querySingleString(const TQString& sql, TQString &value, uint column = 0, 
            bool addLimitTo1 = true);
 
        tristate querySingleNumber(const TQString& sql, int &number, uint column = 0, 
            bool addLimitTo1 = true);
 
        bool queryStringList(const TQString& sql, TQStringList& list, uint column = 0);
 
        bool resultExists(const TQString& sql, bool &success, bool addLimitTo1 = true);
 
        bool isEmpty( TableSchema& table, bool &success );
 
 
        int resultCount(const TQString& sql);
 
        //PROTOTYPE:
        #define A , const TQVariant&
        #define H_INS_REC(args) bool insertRecord(TableSchema &tableSchema args)
        #define H_INS_REC_ALL \
        H_INS_REC(A); \
        H_INS_REC(A A); \
        H_INS_REC(A A A); \
        H_INS_REC(A A A A); \
        H_INS_REC(A A A A A); \
        H_INS_REC(A A A A A A); \
        H_INS_REC(A A A A A A A); \
        H_INS_REC(A A A A A A A A)
        H_INS_REC_ALL;
        
        #undef H_INS_REC
        #define H_INS_REC(args) bool insertRecord(FieldList& fields args)
 
        H_INS_REC_ALL;
        #undef H_INS_REC_ALL
        #undef H_INS_REC
        #undef A
        
        bool insertRecord(TableSchema &tableSchema, TQValueList<TQVariant>& values);
        
        bool insertRecord(FieldList& fields, TQValueList<TQVariant>& values);
 
        bool createTable( TableSchema* tableSchema, bool replaceExisting = false );
 
        tristate dropTable( TableSchema* tableSchema );
 
        tristate dropTable( const TQString& table );
 
        tristate alterTable( TableSchema& tableSchema, TableSchema& newTableSchema);
 
        bool alterTableName(TableSchema& tableSchema, const TQString& newName, bool replace = false);
 
        bool dropQuery( QuerySchema* querySchema );
 
        bool dropQuery( const TQString& query );
 
        bool removeObject( uint objId );
 
        Field* findSystemFieldName(FieldList *fieldlist);
 
        virtual TQString anyAvailableDatabaseName();
        
        void setAvailableDatabaseName(const TQString& dbName);
 
        bool useTemporaryDatabaseIfNeeded(TQString &tmpdbName);
 
        TQ_ULLONG lastInsertedAutoIncValue(const TQString& aiFieldName, const TQString& tableName, 
            TQ_ULLONG* ROWID = 0);
        
        TQ_ULLONG lastInsertedAutoIncValue(const TQString& aiFieldName, 
            const TableSchema& table, TQ_ULLONG* ROWID = 0);
 
        bool executeSQL( const TQString& statement );
 
        class KEXI_DB_EXPORT SelectStatementOptions
        {
            public:
                SelectStatementOptions();
                ~SelectStatementOptions();
 
                int identifierEscaping;
 
                bool alsoRetrieveROWID : 1;
 
                bool addVisibleLookupColumns : 1;
        };
 
        TQString selectStatement( QuerySchema& querySchema, 
            const TQValueList<TQVariant>& params, 
            const SelectStatementOptions& options = SelectStatementOptions() ) const;
 
        inline TQString selectStatement( QuerySchema& querySchema, 
            const SelectStatementOptions& options = SelectStatementOptions() ) const
        {
            return selectStatement(querySchema, TQValueList<TQVariant>(), options);
        }
 
        bool storeObjectSchemaData( SchemaData &sdata, bool newObject );
 
        tristate loadObjectSchemaData( int objectID, SchemaData &sdata );
 
        tristate loadObjectSchemaData( int objectType, const TQString& objectName, SchemaData &sdata );
 
        tristate loadDataBlock( int objectID, TQString &dataString, const TQString& dataID );
 
        bool storeDataBlock( int objectID, const TQString &dataString, const TQString& dataID = TQString() );
 
        bool removeDataBlock( int objectID, const TQString& dataID = TQString());
 
        class KEXI_DB_EXPORT TableSchemaChangeListenerInterface
        {
            public:
                TableSchemaChangeListenerInterface() {}
                virtual ~TableSchemaChangeListenerInterface() {}
                virtual tristate closeListener() = 0;
 
                TQString listenerInfoString;
        };
//TMP// TODO: will be more generic
        void registerForTableSchemaChanges(TableSchemaChangeListenerInterface& listener, 
            TableSchema& schema);
 
        void unregisterForTableSchemaChanges(TableSchemaChangeListenerInterface& listener, 
            TableSchema &schema);
 
        void unregisterForTablesSchemaChanges(TableSchemaChangeListenerInterface& listener);
 
        TQPtrList<Connection::TableSchemaChangeListenerInterface>*
            tableSchemaChangeListeners(TableSchema& tableSchema) const;
 
        tristate closeAllTableSchemaChangeListeners(TableSchema& tableSchema);
 
        void removeTableSchemaInternal(KexiDB::TableSchema *tableSchema);
 
        void insertInternalTableSchema(TableSchema *tableSchema);
 
 
        virtual bool drv_containsTable( const TQString &tableName ) = 0;
 
        virtual bool drv_createTable( const TableSchema& tableSchema );
 
        virtual bool drv_alterTableName(TableSchema& tableSchema, const TQString& newName);
 
        virtual bool drv_dropTable( const TQString& name );
 
        virtual PreparedStatement::Ptr prepareStatement(PreparedStatement::StatementType type, 
            FieldList& fields) = 0;
 
        bool isInternalTableSchema(const TQString& tableName);
 
        bool setupObjectSchemaData( const RowData &data, SchemaData &sdata );
 
        KexiDB::Field* setupField( const RowData &data );
 
    protected:
        Connection( Driver *driver, ConnectionData &conn_data );
 
        void destroy();
 
        tristate dropTable( KexiDB::TableSchema* tableSchema, bool alsoRemoveSchema);
 
        virtual bool drv_connect(KexiDB::ServerVersionInfo& version) = 0;
 
        virtual bool drv_disconnect() = 0;
 
        virtual bool drv_executeSQL( const TQString& statement ) = 0;
 
        virtual bool drv_getDatabasesList( TQStringList &list );
 
 
        virtual bool drv_getTablesList( TQStringList &list ) = 0;
 
        virtual bool drv_databaseExists( const TQString &dbName, bool ignoreErrors = true );
 
        virtual bool drv_createDatabase( const TQString &dbName = TQString() ) = 0;
 
        virtual bool drv_useDatabase( const TQString &dbName = TQString(), bool *cancelled = 0, 
            MessageHandler* msgHandler = 0 ) = 0;
 
        virtual bool drv_closeDatabase() = 0;
        
        virtual bool drv_isDatabaseUsed() const { return true; }
 
        virtual bool drv_dropDatabase( const TQString &dbName = TQString() ) = 0;
 
        TQString createTableStatement( const TableSchema& tableSchema ) const;
 
 
        TQString selectStatement( TableSchema& tableSchema,
            const SelectStatementOptions& options = SelectStatementOptions() ) const;
 
        virtual bool drv_createTable( const TQString& tableSchemaName );
 
//      /*! Executes query \a statement and returns resulting rows 
//          (used mostly for SELECT query). */
//      virtual bool drv_executeQuery( const TQString& statement ) = 0;
 
        virtual TQ_ULLONG drv_lastInsertRowID() = 0;
 
        virtual TransactionData* drv_beginTransaction();
        
        virtual bool drv_commitTransaction(TransactionData* trans);
        
        virtual bool drv_rollbackTransaction(TransactionData* trans);
 
        virtual bool drv_setAutoCommit(bool on);
 
        bool beginAutoCommitTransaction(TransactionGuard& tg);
        
        bool commitAutoCommitTransaction(const Transaction& trans);
        
        bool rollbackAutoCommitTransaction(const Transaction& trans);
 
//      virtual CursorData* drv_createCursor( const TQString& statement ) = 0;
//      virtual bool drv_deleteCursor( CursorData *data ) = 0;
        
        bool checkConnected();
 
        bool checkIsDatabaseUsed();
 
        TableSchema* setupTableSchema( const RowData &data );
 
        QuerySchema* setupQuerySchema( const RowData &data );
 
        bool updateRow(QuerySchema &query, RowData& data, RowEditBuffer& buf, bool useROWID = false);
        bool insertRow(QuerySchema &query, RowData& data, RowEditBuffer& buf, bool getROWID = false);
        bool deleteRow(QuerySchema &query, RowData& data, bool useROWID = false);
        bool deleteAllRows(QuerySchema &query);
 
        bool setupKexiDBSystemSchema();
 
        TableSchema* newKexiDBSystemTableSchema(const TQString& tsname);
 
 
        inline TQString escapeIdentifier(const TQString& id, 
            int escaping = Driver::EscapeDriver|Driver::EscapeAsNecessary ) const {
                return m_driver->escapeIdentifier(id, escaping);
        }
        
        void removeMe(TableSchema *ts);
 
        bool checkIfColumnExists(Cursor *cursor, uint column);
 
        tristate querySingleRecordInternal(RowData &data, const TQString* sql, 
            QuerySchema* query, bool addLimitTo1 = true);
 
        void setReadOnly(bool set);
 
        bool loadExtendedTableSchemaData(TableSchema& tableSchema);
 
        bool storeExtendedTableSchemaData(TableSchema& tableSchema);
 
        bool storeMainFieldSchema(Field *field);
 
        //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
        virtual tristate drv_changeFieldProperty(TableSchema &table, Field& field, 
            const TQString& propertyName, const TQVariant& value) {
            Q_UNUSED(table); Q_UNUSED(field); Q_UNUSED(propertyName); Q_UNUSED(value);
            return cancelled; }
 
        TQPtrDict<KexiDB::Cursor> m_cursors;
 
    private:
        ConnectionPrivate* d; 
        Driver* const m_driver; 
        bool m_destructor_started : 1; 
 
    friend class KexiDB::Driver;
    friend class KexiDB::Cursor;
    friend class KexiDB::TableSchema; 
    friend class KexiDB::DatabaseProperties; 
    friend class ConnectionPrivate;
    friend class KexiDB::AlterTableHandler;
};
 
} //namespace KexiDB
 
#endif