interfaces.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: interfaces.hpp,v $
 * PRODUCTION Revision 1000.1  2003/11/17 22:11:27  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [ORIGINAL] Dev-tree R1.25
 * PRODUCTION
 * ===========================================================================
 */

#ifndef DBAPI_DRIVER___INTERFACES__HPP
#define DBAPI_DRIVER___INTERFACES__HPP

/* $Id: interfaces.hpp,v 1000.1 2003/11/17 22:11:27 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE                          
 *               National Center for Biotechnology Information
 *                                                                          
 *  This software/database is a "United States Government Work" under the   
 *  terms of the United States Copyright Act.  It was written as part of    
 *  the author's official duties as a United States Government employee and 
 *  thus cannot be copyrighted.  This software/database is freely available 
 *  to the public for use. The National Library of Medicine and the U.S.    
 *  Government have not placed any restriction on its use or reproduction.  
 *                                                                          
 *  Although all reasonable efforts have been taken to ensure the accuracy  
 *  and reliability of the software and data, the NLM and the U.S.          
 *  Government do not and cannot warrant the performance or results that    
 *  may be obtained by using this software or data. The NLM and the U.S.    
 *  Government disclaim all warranties, express or implied, including       
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.                                                                
 *                                                                          
 *  Please cite the author in any work or product based on this material.   
 *
 * ===========================================================================
 *
 * Author:  Vladimir Soussov
 *   
 * File Description:  Data Server interfaces
 *
 */

#include <corelib/ncbimtx.hpp>
#include <dbapi/driver/types.hpp>
#include <dbapi/driver/exception.hpp>
#include <dbapi/driver/util/handle_stack.hpp>
#include <dbapi/driver/util/pointer_pot.hpp>
#include <map>


/** @addtogroup DbInterfaces
 *
 * @{
 */


BEGIN_NCBI_SCOPE


class I_BaseCmd;

class I_DriverContext;

class I_Connection;
class I_Result;
class I_LangCmd;
class I_RPCCmd;
class I_BCPInCmd;
class I_CursorCmd;
class I_SendDataCmd;

class CDB_Connection;
class CDB_Result;
class CDB_LangCmd;
class CDB_RPCCmd;
class CDB_BCPInCmd;
class CDB_CursorCmd;
class CDB_SendDataCmd;
class CDB_ResultProcessor;


/////////////////////////////////////////////////////////////////////////////
//
//  I_ITDescriptor::
//
// Image or Text descriptor.
//

class NCBI_DBAPIDRIVER_EXPORT I_ITDescriptor
{
public:
    virtual int DescriptorType() const = 0;
    virtual ~I_ITDescriptor();
};


class NCBI_DBAPIDRIVER_EXPORT C_ITDescriptorGuard
{
public:
    C_ITDescriptorGuard(I_ITDescriptor* d) {
        m_D = d;
    }
    ~C_ITDescriptorGuard() {
        if ( m_D )
            delete m_D;
    }
private:
    I_ITDescriptor* m_D;
};



/////////////////////////////////////////////////////////////////////////////
//
//  EDB_ResType::
//
// Type of result set
//

enum EDB_ResType {
    eDB_RowResult,
    eDB_ParamResult,
    eDB_ComputeResult,
    eDB_StatusResult,
    eDB_CursorResult
};



/////////////////////////////////////////////////////////////////////////////
//
//  CDB_BaseEnt::
//
// Base class for most interface classes.
// It keeps a double-reference to itself, and resets this reference
// (used by others to access this object) on the object destruction.
//

class NCBI_DBAPIDRIVER_EXPORT CDB_BaseEnt
{
public:
    CDB_BaseEnt() {
        m_BR = 0;
    }
    void Acquire(CDB_BaseEnt** br) {
        m_BR = br;
    }
    virtual void Release();
    virtual ~CDB_BaseEnt();

protected:
    CDB_BaseEnt** m_BR;  // double-reference to itself

    // To allow "I_***Cmd" to create CDB_Result
    static CDB_Result* Create_Result(I_Result& result);
};



/////////////////////////////////////////////////////////////////////////////
//
//  I_BaseCmd::
//
// Abstract base class for most "command" interface classes.
//

class NCBI_DBAPIDRIVER_EXPORT I_BaseCmd : public CDB_BaseEnt
{
public:
    // Send command to the server
    virtual bool Send() = 0;
    virtual bool WasSent() const = 0;

    // Cancel the command execution
    virtual bool Cancel() = 0;
    virtual bool WasCanceled() const = 0;

    // Get result set
    virtual CDB_Result* Result() = 0;
    virtual bool HasMoreResults() const = 0;

    // Check if command has failed
    virtual bool HasFailed() const = 0;

    // Get the number of rows affected by the command
    // Special case:  negative on error or if there is no way that this
    //                command could ever affect any rows (like PRINT).
    virtual int RowCount() const = 0;

    // Dump the results of the command
    // if result processor is installed for this connection, it will be called for
    // each result set
    virtual void DumpResults()= 0;

    // Destructor
    virtual ~I_BaseCmd();
};



/////////////////////////////////////////////////////////////////////////////
//
//  I_LangCmd::
//  I_RPCCmd::
//  I_BCPInCmd::
//  I_CursorCmd::
//  I_SendDataCmd::
//
// "Command" interface classes.
//


class NCBI_DBAPIDRIVER_EXPORT I_LangCmd : public I_BaseCmd
{
protected:
    // Add more text to the language command
    virtual bool More(const string& query_text) = 0;

    // Bind cmd parameter with name "name" to the object pointed by "value"
    virtual bool BindParam(const string& name, CDB_Object* param_ptr) = 0;

    // Set cmd parameter with name "name" to the object pointed by "value"
    virtual bool SetParam(const string& name, CDB_Object* param_ptr) = 0;

public:
    virtual ~I_LangCmd();

    friend class CDB_LangCmd;
};



class NCBI_DBAPIDRIVER_EXPORT I_RPCCmd : public I_BaseCmd
{
protected:
    // Binding
    virtual bool BindParam(const string& name, CDB_Object* param_ptr,
                           bool out_param = false) = 0;

    // Setting
    virtual bool SetParam(const string& name, CDB_Object* param_ptr,
                          bool out_param = false) = 0;

    // Set the "recompile before execute" flag for the stored proc
    virtual void SetRecompile(bool recompile = true) = 0;

public:
    virtual ~I_RPCCmd();

    friend class CDB_RPCCmd;
};



class NCBI_DBAPIDRIVER_EXPORT I_BCPInCmd : public CDB_BaseEnt
{
protected:
    // Binding
    virtual bool Bind(unsigned int column_num, CDB_Object* param_ptr) = 0;

    // Send row to the server
    virtual bool SendRow() = 0;

    // Complete batch -- to store all rows transferred by far in this batch
    // into the table
    virtual bool CompleteBatch() = 0;

    // Cancel the BCP command 
    virtual bool Cancel() = 0;

    // Complete the BCP and store all rows transferred in last batch into
    // the table
    virtual bool CompleteBCP() = 0;

public:
    virtual ~I_BCPInCmd();

    friend class CDB_BCPInCmd;
};



class NCBI_DBAPIDRIVER_EXPORT I_CursorCmd : public CDB_BaseEnt
{
protected:
    // Binding
    virtual bool BindParam(const string& name, CDB_Object* param_ptr) = 0;

    // Open the cursor.
    // Return NULL if cursor resulted in no data.
    // Throw exception on error.
    virtual CDB_Result* Open() = 0;

    // Update the last fetched row.
    // NOTE: the cursor must be declared for update in CDB_Connection::Cursor()
    virtual bool Update(const string& table_name, const string& upd_query) = 0;

    virtual bool UpdateTextImage(unsigned int item_num, CDB_Stream& data, 
                                 bool log_it = true) = 0;

    virtual CDB_SendDataCmd* SendDataCmd(unsigned int item_num, size_t size, 
                                         bool log_it = true) = 0;
    // Delete the last fetched row.
    // NOTE: the cursor must be declared for delete in CDB_Connection::Cursor()
    virtual bool Delete(const string& table_name) = 0;

    // Get the number of fetched rows
    // Special case:  negative on error or if there is no way that this
    //                command could ever affect any rows (like PRINT).
    virtual int RowCount() const = 0;

    // Close the cursor.
    // Return FALSE if the cursor is closed already (or not opened yet)
    virtual bool Close() = 0;

public:
    virtual ~I_CursorCmd();

    friend class CDB_CursorCmd;
};



class NCBI_DBAPIDRIVER_EXPORT I_SendDataCmd : public CDB_BaseEnt
{
protected:
    // Send chunk of data to the server.
    // Return number of bytes actually transferred to server.
    virtual size_t SendChunk(const void* pChunk, size_t nofBytes) = 0;

public:
    virtual ~I_SendDataCmd();

    friend class CDB_SendDataCmd;
};

    

/////////////////////////////////////////////////////////////////////////////
//
//  I_Result::
//

class NCBI_DBAPIDRIVER_EXPORT I_Result : public CDB_BaseEnt
{
public:
    // Get type of the result
    virtual EDB_ResType ResultType() const = 0;