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