SqMod/vendor/POCO/Data/doc/00300-DataDeveloperManual.page

POCO Data Connectors Developer Guide
POCO Data Library

!!!Overview
Developing one's own <*Data Connector*> implementation is rather straight-forward.
Just implement the following interfaces:
  * Poco::Data::AbstractBinder
  * Poco::Data::AbstractExtractor
  * Poco::Data::StatementImpl
  * Poco::Data::SessionImpl
  * Poco::Data::Connector
  * optional: Poco::Data::AbstractPreparation

It is recommended to implement the classes from top to down (ie. start with Binder and Extractor) and to use a 
namespace that has <[ Poco::Data ]> as parent, e.g.<[ Poco::Data::SQLite ]>.

!!!AbstractBinder
An <[AbstractBinder]> is a class that maps values to placeholders. It is also responsible to bind primitive C++ data types to database 
data types. The constructor of the subclass should receive everything needed to bind variables to 
placeholders by position. An example taken from the SQLite implementation would be:

    Binder::Binder(sqlite3_stmt* pStmt):
        _pStmt(pStmt)
    {
    }
    
    void Binder::bind(std::size_t pos, const Poco::Int32& val)
    {
        int rc = sqlite3_bind_int(_pStmt, (int)pos, val);
        checkReturn(rc);
    }
    
    void Binder::bind(std::size_t pos, const Poco::Int16& val)
    {
        Poco::Int32 tmp = val;
        bind(pos, tmp);
    }
----
SQLite only needs an <*sqlite3_stmt*> as internal state, Int32 is bound via <*sqlite3_bind_int*> and Int16 values are mapped to Int32 values.

!!Complete Interface
All methods are public.

    AbstractBinder();
        /// Creates the AbstractBinder.
    
    virtual ~AbstractBinder();
        /// Destroys the AbstractBinder.
    
    virtual void bind(std::size_t pos, const Poco::Int8 &val) = 0;
        /// Binds an Int8.
    
    virtual void bind(std::size_t pos, const Poco::UInt8 &val) = 0;
        /// Binds an UInt8.
    
    virtual void bind(std::size_t pos, const Poco::Int16 &val) = 0;
        /// Binds an Int16.
    
    virtual void bind(std::size_t pos, const Poco::UInt16 &val) = 0;
        /// Binds an UInt16.
    
    virtual void bind(std::size_t pos, const Poco::Int32 &val) = 0;
        /// Binds an Int32.
    
    virtual void bind(std::size_t pos, const Poco::UInt32 &val) = 0;
        /// Binds an UInt32.
    
    virtual void bind(std::size_t pos, const Poco::Int64 &val) = 0;
        /// Binds an Int64.
    
    virtual void bind(std::size_t pos, const Poco::UInt64 &val) = 0;
        /// Binds an UInt64.
    
    virtual void bind(std::size_t pos, const bool &val) = 0;
        /// Binds a boolean.
    
    virtual void bind(std::size_t pos, const float &val) = 0;
        /// Binds a float.
    
    virtual void bind(std::size_t pos, const double &val) = 0;
        /// Binds a double.
    
    virtual void bind(std::size_t pos, const char &val) = 0;
        /// Binds a single character.
    
    virtual void bind(std::size_t pos, const char* const &pVal) = 0;
        /// Binds a const char ptr.
    
    virtual void bind(std::size_t pos, const std::string& val) = 0;
        /// Binds a string.
    
    virtual void bind(std::size_t pos, const BLOB& val) = 0;
        /// Binds a BLOB.
    
    virtual void reset() = 0;
        /// Resets the internal state, called before a rebind
----

!!!AbstractExtractor
An <[AbstractExtractor]> takes a result row and extracts from a given position one single value. It performs the reverse operation to the <[AbstractBinder]>,
ie. it maps database types to primitive C++ types. An <[AbstractExtractor]> also has to handle null values. If it detects a null value, it is not allowed to modify
the incoming value but will simply return false. An example taken from the SQLite implementation:

    Extractor::Extractor(sqlite3_stmt* pStmt):
        _pStmt(pStmt)
    {
    }
    
    bool Extractor::extract(std::size_t pos, Poco::Int32& val)
    {
        if (isNull(pos<[
            return false;
        val = sqlite3_column_int(_pStmt, (int)pos);
        return true;
    }
    
    bool Extractor::extract(std::size_t pos, Poco::Int16& val)
    {
        if (isNull(pos<[
            return false;
        val = sqlite3_column_int(_pStmt, (int)pos);
        return true;
    }
----

!!Complete Interface
All methods are public.

    AbstractExtractor();
        /// Creates the AbstractExtractor.
    
    virtual ~AbstractExtractor();
        /// Destroys the AbstractExtractor.
    
    virtual bool extract(std::size_t pos, Poco::Int8& val) = 0;
        /// Extracts an Int8. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::UInt8& val) = 0;
        /// Extracts an UInt8. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::Int16& val) = 0;
        /// Extracts an Int16. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::UInt16& val) = 0;
        /// Extracts an UInt16. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::Int32& val) = 0;
        /// Extracts an Int32. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::UInt32& val) = 0;
        /// Extracts an UInt32. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::Int64& val) = 0;
        /// Extracts an Int64. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, Poco::UInt64& val) = 0;
        /// Extracts an UInt64. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, bool& val) = 0;
        /// Extracts a boolean. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, float& val) = 0;
        /// Extracts a float. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, double& val) = 0;
        /// Extracts a double. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, char& val) = 0;
        /// Extracts a single character. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, std::string& val) = 0;
        /// Extracts a string. Returns false if null was received.
    
    virtual bool extract(std::size_t pos, BLOB& val) = 0;
        /// Extracts a BLOB. Returns false if null was received.
----

!!!AbstractPreparation
<[AbstractPreparation]> is an optional interface responsible for preparing an extract. If you need it depends on the <[DataConnector]> you implement. For example, SQLite can do perfectly without it, ODBC instead requires it.
SQLite doesn't need it because it works as follows:
  * sendQuery
  * getNextResult
  * extract single row values from result set

This works because SQLites <*getNextResult*> provides the data as string, i.e. it doesn't need any type information.

The ODBC implementation is different:
  * register/prepare for each column an output location
  * getNextResult
  * extract for each row the value by copying the content of the previously registered output location

<[AbstractPreparation]> is responsible for the first step. A typical prepare implementation will look like that:

    void prepare(std::size_t pos, Poco::Int32 val)
    {
       _myVec[pos] =  Poco::Any a(val);
       int* i = AnyCast<int>(&_myVec[pos]);
       //register int* i for output, Db specific
    } 
----
Extract now changes to:

    bool Extractor::extract(std::size_t pos, Poco::Int16& val)
    {
        if (isNull(pos))
            return false;
        val = AnyCast<int>(_myVec[pos]);
        return true;
    }
----

!!Complete Interface

    AbstractPreparation();
        /// Creates the AbstractPreparation.
    
    virtual ~AbstractPreparation();
        /// Destroys the AbstractPreparation.
    
    virtual void prepare(std::size_t pos, Poco::Int8) = 0;
        /// Prepares an Int8.
    
    virtual void prepare(std::size_t pos, Poco::UInt8) = 0;
        /// Prepares an UInt8.
    
    virtual void prepare(std::size_t pos, Poco::Int16) = 0;
        /// Prepares an Int16.
    
    virtual void prepare(std::size_t pos, Poco::UInt16) = 0;
        /// Prepares an UInt16.
    
    virtual void prepare(std::size_t pos, Poco::Int32) = 0;
        /// Prepares an Int32.
    
    virtual void prepare(std::size_t pos, Poco::UInt32) = 0;
        /// Prepares an UInt32.
    
    virtual void prepare(std::size_t pos, Poco::Int64) = 0;
        /// Prepares an Int64.
    
    virtual void prepare(std::size_t pos, Poco::UInt64) = 0;
        /// Prepares an UInt64.
    
    virtual void prepare(std::size_t pos, bool) = 0;
        /// Prepares a boolean.
    
    virtual void prepare(std::size_t pos, float) = 0;
        /// Prepares a float.
    
    virtual void prepare(std::size_t pos, double) = 0;
        /// Prepares a double.
    
    virtual void prepare(std::size_t pos, char) = 0;
        /// Prepares a single character.
    
    virtual void prepare(std::size_t pos, const std::string& ) = 0;
        /// Prepares a string.
    
    virtual void prepare(std::size_t pos, const BLOB&) = 0;
----

Note that it is recommended to prepare a statement only once in the compileImpl of <[StatementImpl]>. The AbstractPreparator objects (which make use of <[AbstractPreparation]>
can be created by iterating over the Extractor objects of the StatementImpl:

    Poco::Data::AbstractExtractingVec::iterator it = extractings().begin();
    Poco::Data::AbstractExtractingVec::iterator itEnd = extractings().end();
    std::size_t pos = 0; // sqlite starts with pos 0 for results! your DB maybe with 1
    for (; it != itEnd; ++it)
    {
         AbstractPreparator* pPrep = (*it)->createPrepareObject(pPreparation, pos);
        _prepareVec.push_back(pPrep);
        (*it)->extract(pos);
        pos += (*it)->numOfColumnsHandled();
    }
----
!!!StatementImpl
A <[StatementImpl]> stores as member a Binder and an Extractor (optional a Preparation object) and is responsible for compiling, binding, fetching single rows from the database and invoking the <*Extracting*> objects.
The interface it has to implement is given as:

    public:
        StatementImpl();
            /// Creates the StatementImpl.
        
        virtual ~StatementImpl();
            /// Destroys the StatementImpl.
    
    protected:
        virtual bool hasNext() = 0;
            /// Returns true if a call to next() will return data. Note that the 
            /// implementation must support several consecutive calls to hasNext 
            /// without data getting lost, ie. hasNext(); hasNext(); next() must 
            /// be equal to hasNext(); next();
    
        virtual void next() = 0;
            /// Retrieves the next row from the resultset.
            /// Will throw, if the resultset is empty.
            /// Expects the statement to be compiled and bound
    
        virtual bool canBind() const = 0;
            /// Returns if another bind is possible.
    
        virtual void compileImpl() = 0;
            /// Compiles the statement, doesn't bind yet.
            /// From now on AbstractBinder and AbstractExtractor 
            /// will be used
    
        virtual void bindImpl() = 0;
            /// Binds parameters.
    
        virtual AbstractExtractor& extractor() = 0;
            /// Returns the concrete extractor used by the statement.
    
        virtual AbstractBinder& binder() = 0;
            /// Returns the concrete binder used by the statement.  
----

The Extracting and Binding objects can be accessed via the calls to the super-class methods <*extractings()*> and <*bindings()*>.
A high-level <*bind*> implementation will look like this:

    [...]
    Poco::Data::AbstractBindingVec& binds = bindings();
    std::size_t pos = 1; // or 0 depending on your database
    Poco::Data::AbstractBindingVec::iterator it = binds.begin();
    Poco::Data::AbstractBindingVec::iterator itEnd = binds.end();
    for (; it != itEnd && (*it)->canBind(); ++it)
    {
        (*it)->bind(pos);
        pos += (*it)->numOfColumnsHandled();
    }
----

A high-level <*next*> implementation:

    if (!hasNext())
        throw Poco::Data::DataException("No data received");
    int nCol = countColumnsInResult...;
    poco_assert (columnsHandled() == nCol); 
    Poco::Data::AbstractExtractingVec::iterator it = extractings().begin();
    Poco::Data::AbstractExtractingVec::iterator itEnd = extractings().end();
    std::size_t pos = 0; // sqlite starts with pos 0 for results! your DB maybe with 1
    for (; it != itEnd; ++it)
    {
        (*it)->extract(pos);
        pos += (*it)->numOfColumnsHandled();
    }
    enableHasNext();
----

A high-level <*hasNext*> implementation:

    if (enabledhasNext())
    {
        checkIfItHasMoreData
        cacheResult
        disablehasNext()
    }
    
    return cachedResult;
----

A high-level <*compileImpl*>:

    if (compiled)
        return;
    
    std::string sqlStmt(toString());

   if database expects placeholders in different format than ":name", parse and replace them

    compile statement;
    
    create Binder;
    create Extractor;
----

A high-level <*canBind*>:

    bool ret = false;
    if (!bindings().empty() && validCompiledStatement)
        ret = (*bindings().begin())->canBind();
    
    return ret;
----

!!!SessionImpl
The purpose of the <[SessionImpl]> is simply to open/close a connection to the database, to act as factory for <[StatementImpl]> objects, and to handle transactions.
The connection is opened in the constructor, and closed in the destructor.

    Poco::Data::StatementImpl* createStatementImpl();
        /// Returns an SQLite StatementImpl
    
    void begin();
        /// Starts a transaction
    
    void commit();
        /// Commits and ends a transaction
    
    void rollback();
        /// Aborts a transaction
----

!!!Connector
Finally, one needs to implement the <[Connector]>.
Each <[Connector]> should have a public static const string member named <*KEY*> and must have a factory method to <*create*> <[ Poco::AutoPtr ]> objects of type <[SessionImpl]>.
It should also have a static <*addToFactory()*> and a static <*removeFromFactory()*> method:

    class My_API Connector: public Poco::Data::Connector
        /// Connector instantiates SessionImpl objects.
    {
    public:
        static const std::string KEY;
            /// Keyword for creating sessions
    
        Connector();
            /// Creates the Connector.
    
        ~Connector();
        /// Destroys the Connector.
    
        Poco::AutoPtr < Poco::Data::SessionImpl > createSession(const std::string& connectionString);
            /// Creates a SessionImpl object and initializes it with the given connectionString.
    
        static void registerConnector();
            /// Registers the Connector under the Keyword Connector::KEY at the Poco::Data::SessionFactory
    
        static void unregisterConnector();
            /// Unregisters the Connector under the Keyword Connector::KEY at the Poco::Data::SessionFactory
    };
----