Introduction
========

dbframework is a small C++ framework designed to implement object-relational mapping (ORM) in applications that interact with relational DBMSs.
The main purpose of this framework is to simplify the writing of code for reading the results of SQL queries that implement a join of several tables into a complex hierarchical 
objects. A complex hierarchical structure is understood as a class that includes containers that contain objects of other classes, which in turn contain container objects, etc.

Features of dbframework
======================

1. dbframework is implemented as C++ class templates. Using dbframework is done by using or inheriting from dbframework class templates.
   Additional preprocessors, compilers, etc. are not required.
2. No modification of existing classes is required.
3. dbframework does not contain code for working with any specific DBMS. It is assumed that a third-party library will be used to perform database queries.

Installation
=========

To install, just unpack the dbframework archive into any directory.

Usage
=============

To use dbframework in your application you need:
- include the dbframework2.h file;
- add the dbframework installation directory to the list of include directories.

All framework classes are in dbframework namespace.

An example of using dbframework is located in the example subdirectory of the dbframework installation directory.

Short description
================

dbframework is designed to implement interaction beetwen  the main part of the program and the part that is responcible for interaction with relational DBMS. The class from the main part of the program which data is stored in some database table will be called simple class. The class that has members that are simple classes or containers of classes will be called complex class. Complex classes can be used to store results of execution of SQL queries joining several tables.

dbframework containes two main class temlate hierarchys: 
- classes for reading the results of executing an SQL query, the base class of the template is dbframework::DBReader;
- classes for passing parameters to an SQL query, the base template class is dbframework::DBBinder.
In what follows, dbframework::DBReader will be called Reader, and the descendants of dbframework::DBBinder will be called Binder.

Readers are used as follows. For each simple class, a descendant dbframework::DBReader2Storage is created. For a complex class, Reader is created using Readers for simple classes and
Readers from the framework. Before reading the results of executing an SQL query, the created Reader instance is associated with an instance of the corresponding complex class. Then 
read(...) method is called to read the results of the SQL query execution. This is described in more detail in the comments for the example.

Binders are used in the following way. Before SQL query execution Binder instance is linked with the instance of some class or with variable of standard type (for example, int). For cases when parameters are contained in several variables or objects, dbframework has Binder that allows to combine several Binders to one. Then Binders method bind(...) is called. It should bind object fields or variable with SQL query parameters. After that the SQL query can be executed.

ORM implementation using dbframework can be divided into 4 stages.

1. Creation of the subroutine that controls SQL query execution. This subroutine must have following parameters: SQL query, Binder and Reader. The subroutine must bind SQL query parameters by calling Binder.bind(...), execute SQL query and call Reader.read(...) for each record of query execution result. Later the execution of every SQL query can be done by this subroutine by providing suitable Binder and Reader. Easiest way to do this is to inherit from dbframework::DBSQLExecutor.
2. Creation of the Binder for each simple class. Easiest way to do this is to inherit from template class dbframework::DBBindObject. This stage is optional. If it isn't supposed to execute SQL queries with many parameters binded with the fields of some object, then one can use class templates dbframework::DBBind and dbframework::DBBinders.  
3. Creation of the Reader for each simple class. Such Reader must store data into simple class members. This Reader can be implemented by inheriting from dbframework::DBReader2Object.
4. Selection of the complex class for storing data for each SQL query. Creation of the Reader for selected complex class. Such Reader can be implemented by combining Readers for simple classes and dbframework Reader class templates for storing data into containers.

In this way, the SQL query execution is reduced to creation of suitable Reader and Binder.

The example subdirectory contains the example of application using dbframework. 

dbframework documentation can be generated by processing header files with doxygen. Just run doxygen from the directory of dbframework installation.