SOCI - backends

SOCI
Simple Oracle Call Interface (and more)

Backends reference

Note: This part of the documentation is provided for those who want to write (and contribute!) their own backends. It is anyway recommended that authors of new backend see the code of some existing backend for hints on how things are really done.

The backend interface is a set of base classes that the actual backends are supposed to specialize. The main SOCI interface uses only the interface and respecting the protocol (for example, the order of function calls) described here. Note that both the interface and the protocol were designed with the Oracle database in mind, which means that whereas it is quite natural with respect to the way Oracle API (OCI) works, it might impose some implementation burden on other backends, where things are done differently and therefore have to be adjusted, cached, converted, etc.

The interface to the common SOCI interface is defined in the soci-common.h header file. This file is dissected below.
All names are defined in either SOCI or SOCI::details namespace.

// data types, as seen by the user
enum eDataType { eString, eChar, eDate, eDouble, eInteger,
                 eUnsignedLong };

// the enum type for indicator variables
enum eIndicator { eOK, eNoData, eNull, eTruncated };

// data types, as used to describe exchange format
enum eExchangeType { eXChar, eXCString, eXStdString, eXShort, eXInteger,
                     eXUnsignedLong, eXDouble, eXStdTm, eXStatement,
                     eXRowID, eXBLOB };

struct CStringDescriptor
{
    CStringDescriptor(char *str, std::size_t bufSize)
        : str_(str), bufSize_(bufSize) {}

    char *str_;
    std::size_t bufSize_;
};

class SOCIError : public std::runtime_error
{
public:
    SOCIError(std::string const & msg, int errNum = 0);

    int errNum_;
};

The eDataType enumeration type defines all types that form the core type support for SOCI. The enum itself can be used by clients when dealing with dynamic rowset description.
The eIndicator enumeration type defines all recognized states of data. The eTruncated state is provided for the case where the string is retrieved from the database into the char buffer that is not long enough to hold the whole value.
The eExchangeType enumeration type defines all possible types that can be used with the into and use elements.
The CStringDescriptor is a helper class that allows to store the address of char buffer together with its size. The objects of this class are passed to the backend when the eXCString type is involved.
The SOCIError class is an exception type used for database-related (and also usage-related) errors. The backends should throw exceptions of this or derived type only.

class StandardIntoTypeBackEnd
{
public:
    virtual ~StandardIntoTypeBackEnd() {}

    virtual void defineByPos(int &position,
        void *data, eExchangeType type) = 0;

    virtual void preFetch() = 0;
    virtual void postFetch(bool gotData, bool calledFromFetch,
        eIndicator *ind) = 0;

    virtual void cleanUp() = 0;
};

The StandardIntoTypeBackEnd class implements the dynamic interactions with the simple (non-bulk) into elements. The objects of this class (or, rather, of the derived class implemented by the actual backend) are created by the Statement object when the into element is bound - in terms of lifetime management, Statement is the master of this class.

defineByPos - Called when the into element is bound, once and before the statement is executed. The data pointer points to the variable used for into element (or to the CStringDescriptor object, which is artificially created when the plain char buffer is used for data exchange). The position parameter is a "column number", assigned by the library. The backend should increase this parameter, according to the number of fields actually taken (usually 1).
preFetch - Called before each row is fetched.
postFetch - Called after each row is fetched. The gotData parameter is true if the fetch operation really retrieved some data and false otherwise; calledFromFetch is true when the call is from the fetch operation and false if it is from the execute operation (this is also the case for simple, one-time queries). In particular, (calledFromFetch && !gotData) indicates that there is an end-of-rowset condition. ind points to the indicator provided by the user, or is NULL, if there is no indicator.
cleanUp - Called once when the statement is destroyed.

The intended use of preFetch and postFetch functions is to manage any internal buffer and/or data conversion for each value retrieved from the database. If the given server supports binary data transmission and the data format for the given type agrees with what is used on the client machine, then these two functions need not do anything; otherwise buffer management and data conversions should go there.

class VectorIntoTypeBackEnd
{
public:
    virtual ~VectorIntoTypeBackEnd() {}

    virtual void defineByPos(int &position,
        void *data, eExchangeType type) = 0;

    virtual void preFetch() = 0;
    virtual void postFetch(bool gotData, eIndicator *ind) = 0;

    virtual void resize(std::size_t sz) = 0;
    virtual std::size_t size() = 0;

    virtual void cleanUp() = 0;
};

The VectorIntoTypeBackEnd has similar structure and purpose as the previous one, but is used for vectors (bulk data retrieval).
The data pointer points to the variable of type std::vector<T> (not to its internal buffer), resize is supposed to really resize the user-provided vector and size is supposed to return the current size of this vector.
The important difference with regard to the previous class is that ind points (if not NULL) to the beginning of the array of indicators. The backend should fill this array according to the actual state of the retrieved data.

class StandardUseTypeBackEnd
{
public:
    virtual ~StandardUseTypeBackEnd() {}

    virtual void bindByPos(int &position,
        void *data, eExchangeType type) = 0;
    virtual void bindByName(std::string const &name,
        void *data, eExchangeType type) = 0;

    virtual void preUse(eIndicator const *ind) = 0;
    virtual void postUse(bool gotData, eIndicator *ind) = 0;

    virtual void cleanUp() = 0;
};

The StandardUseTypeBackEnd implements the interactions with the simple (non-bulk) use elements, created and destroyed by the Statement object.

bindByPos - Called for each use element, once and before the statement is executed - for those use elements that do not provide explicit names for parameter binding. The meaning of parameters is same as in previous classes.
bindByName - Called for those use elements that provide the explicit name.
preUse - Called before the data is transmitted to the server (this means before the statement is executed, which can happen many times for the prepared statement). ind points to the indicator provided by the user (or is NULL).
postUse - Called after statement execution. gotData and ind have the same meaning as in StandardIntoTypeBackEnd::postFetch, and this can be used by those backends whose respective servers support two-way data exchange (like in/out parameters in stored procedures).

The intended use fot preUse and postUse methods is to manage any internal buffers and/or data conversion. They can be called many times with the same statement.

class VectorUseTypeBackEnd
{
public:
    virtual ~VectorUseTypeBackEnd() {}

    virtual void bindByPos(int &position,
        void *data, eExchangeType type) = 0;
    virtual void bindByName(std::string const &name,
        void *data, eExchangeType type) = 0;

    virtual void preUse(eIndicator const *ind) = 0;

    virtual std::size_t size() = 0;

    virtual void cleanUp() = 0;
};

Objects of this type (or rather of type derived from this one) are used to implement interactions with user-provided vector (bulk) use elements and are managed by the Statement object.
The data pointer points to the whole vector object provided by the user (not to its internal buffer); ind points to the beginning of the array of indicators (or is NULL). The meaning of this interface is analogous to those presented above.

class StatementBackEnd
{
public:
    virtual ~StatementBackEnd() {}

    virtual void alloc() = 0;
    virtual void cleanUp() = 0;
    virtual void prepare(std::string const &query) = 0;

    enum execFetchResult { eSuccess, eNoData };
    virtual execFetchResult execute(int number) = 0;
    virtual execFetchResult fetch(int number) = 0;

    virtual int getNumberOfRows() = 0;

    virtual std::string rewriteForProcedureCall(std::string const &query) = 0;

    virtual int prepareForDescribe() = 0;
    virtual void describeColumn(int colNum, eDataType &dtype,
        std::string &columnName, int &size, int &precision, int &scale,
        bool &nullOk) = 0;

    virtual StandardIntoTypeBackEnd * makeIntoTypeBackEnd() = 0;
    virtual StandardUseTypeBackEnd * makeUseTypeBackEnd() = 0;
    virtual VectorIntoTypeBackEnd * makeVectorIntoTypeBackEnd() = 0;
    virtual VectorUseTypeBackEnd * makeVectorUseTypeBackEnd() = 0;
};

The StatementBackEnd type implements the internals of the Statement objects (in fact, it is a basic Strategy design pattern).
The objects of this class are created by the Session object.

alloc - Called once to allocate everything that is needed for the statement to work correctly.
cleanUp - Supposed to clean up the resources, called once.
prepare - Called once with the text of the SQL query. For servers that support explicit query preparation, this is the place to do it.
execute - Called to execute the query; if number is zero, the intent is not to exchange data with the user-provided objects (into and use elements); positive values mean the number of rows to exchange (more than 1 is used only for bulk operations).
fetch - Called to fetch next bunch of rows; number is positive and determines the requested number of rows (more than 1 is used only for bulk operations).
getNumberOfRows - Called to determine the actual number of rows retrieved by the previous call to execute or fetch.
rewriteForProcedureCall - Used when the Procedure is used instead of Statement, to call the stored procedure. This function should rewrite the SQL query (if necessary) to the form that will allow to execute the given procedure.
prepareForDescribe - Called once when the into element is used with the Row type, which means that dynamic rowset description should be performed. It is supposed to do whatever is needed to later describe the column properties and should return the number of columns.
describeColumn - Called once for each column (column numbers - colNum - start from 1), should fill its parameters according to the column properties.
makeIntoTypeBackEnd, makeUseTypeBackEnd, makeVectorIntoTypeBackEnd, makeVectorUseTypeBackEnd - Called once for each into or use element, to create the objects of appropriate classes (described above).

Note:

Whether the query is executed using the simple one-time syntax or is prepared, the alloc, prepare and execute functions are always called, in this order.
All into and use elements are bound (their defineByPos or bindByPos/bindByName functions are called) between statement preparation and execution.

class RowIDBackEnd
{
public:
    virtual ~RowIDBackEnd() {}
};

The RowIDBackEnd class is a hook for the backends to provide their own state for the row identifier. It has no functions, since the only portable interaction with the row identifier object is to use it with into and use elements.

class BLOBBackEnd
{
public:
    virtual ~BLOBBackEnd() {}

    virtual std::size_t getLen() = 0;
    virtual std::size_t read(std::size_t offset, char *buf,
        std::size_t toRead) = 0;
    virtual std::size_t write(std::size_t offset, char const *buf,
        std::size_t toWrite) = 0;
    virtual std::size_t append(char const *buf, std::size_t toWrite) = 0;
    virtual void trim(std::size_t newLen) = 0;
};

The BLOBBackEnd interface provides the entry points for the BLOB methods.

class SessionBackEnd
{
public:
    virtual ~SessionBackEnd() {}

    virtual void begin() = 0;
    virtual void commit() = 0;
    virtual void rollback() = 0;

    virtual StatementBackEnd * makeStatementBackEnd() = 0;
    virtual RowIDBackEnd * makeRowIDBackEnd() = 0;
    virtual BLOBBackEnd * makeBLOBBackEnd() = 0;
};

The object of the class derived from SessionBackEnd implements the internals of the Session object.

begin, commit, rollback - Forward-called when the same functions of Session are called by user.
makeStatementBackEnd, makeRowIDBackEnd, makeBLOBBackEnd - Called to create respective implementations for the Statement, RowID and BLOB classes.

struct BackEndFactory
{
    virtual SessionBackEnd * makeSession(
        std::string const &connectString) const = 0;
};

class BackEndFactoryRegistry
{
public:
    void registerMe(std::string const &beName, BackEndFactory const *f);
    BackEndFactory const * find(std::string const &beName) const;

private:
    std::map<std::string, BackEndFactory const *> registry_;
};

// registry singleton
BackEndFactoryRegistry & theBEFRegistry();

The BackEndFactory is a base class for backend-provided factory class that is able to create valid sessions. The connectString parameter passed to makeSession is provided here by the Session constructor.
The BackEndFactoryRegistry and the theBEFRegistry function implement the Singleton registry for all instances of BackEndFactory (theBEFRegistry always returns the reference to the same registry object). When the Session object is created, the backend name (the first parameter to the Session constructor) is used to lookup the appropriate factory. If found (find always returns a valid pointer or throws an exception), its makeSession function is called to actually create the session.
The backends have to register themselves (by calling the registerMe function) in order to be found and used. It is recommended that backends register themselves with the help of some dummy global object, whose constructor performs the registration.
The following example is taken from soci-oracle.cpp, which is an implementation of the Oracle backend:

// concrete factory for Oracle concrete strategies
struct OracleBackEndFactory : BackEndFactory
{
    virtual OracleSessionBackEnd * makeSession(
        std::string const &connectString) const
    {
        std::string serviceName, userName, password;
        chopConnectString(connectString, serviceName, userName, password);

        return new OracleSessionBackEnd(serviceName, userName, password);
    }

} oracleBEF;

// global object for automatic factory registration
struct OracleAutoRegister
{
    OracleAutoRegister()
    {
        theBEFRegistry().registerMe("oracle", &oracleBEF);
    }
} oracleAutoRegister;

The above code ensures that it is enough to just compile and link the soci-oracle.cpp file to get the automatic registration of the whole backend. Later, when the Session object is created for the "oracle" backend, it will be found and used to create the OracleSessionBackEnd (which itself derives from SessionBackEnd). This, in turn, will be used to create implementations for any other objects that are needed, with the help of appropriate makeXYZ functions.

Note: There are soci-empty.h and soci-empty.cpp files provided as a skeleton for development of new backends (there is also test-empty.cpp as a skeleton for tests). It is recommended that all backends respect naming conventions by just appending their name to the base-class names. The backend name used for registration (and later lookup) should clearly identify the given database engine, like "oracle", "postgresql", "mysql", and so on.

Previous (Beyond SOCI)

Next (Rationale FAQ)