/* DBSession
   Represents a single user's session (e.g., a single HTTP request).
*/

/*  getConnectionPool() 
    IMMEDIATE
    RETURNS the DBConnectionPool from which this DBSession was created.
*/
  getConnectionPool();


/* buildInsertOperation(DBTableHandler tableHandler, 
                        Object row,
                        DBTransactionHandler transaction,
                        function(error, DBOperation) userCallback)
   IMMEDIATE
   Define an operation which when executed will insert a row.
 
   RETURNS a DBOperation 
*/
  buildInsertOperation(tableHandler, row, transaction, callback);


/* buildWriteOperation(DBIndexHandler dbIndexHandler, 
                       Object row,
                       DBTransactionHandler transaction,
                       function(error, DBOperation) userCallback)
   IMMEDIATE
   Define an operation which when executed will update or insert
 
   RETURNS a DBOperation 
*/
  buildWriteOperation(dbIndexHandler, row, transaction, callback);


/* buildReadOperation(DBIndexHandler dbIndexHandler, 
                      Object keys,
                      DBTransactionHandler transaction,
                      function(error, DBOperation) userCallback)
   IMMEDIATE
   Define an operation which when executed will fetch a row.

   RETURNS a DBOperation 
*/
  buildReadOperation(indexHandler, keys, transaction, callback);
                      

/* buildReadProjectionOperation(DBIndexHandler dbIndexHandler, 
                      Object keys,
                      Projection projection,
                      DBTransactionHandler transaction,
                      function(error, DBOperation) userCallback)
   IMMEDIATE
   Define an operation which when executed will fetch a row and related rows
   according to the projection.

   RETURNS a DBOperation 
*/
  buildReadProjectionOperation(indexHandler, keys, projection, transaction, callback);
                      

/* buildUpdateOperation(DBIndexHandler dbIndexHandler,
                        Object keys, 
                        Object values,
                        DBTransactionHandler transaction,
                        function(error, DBOperation) userCallback)
   IMMEDIATE
   Define an operation which when executed will access a row using the keys
   object and update the values provided in the values object.
  
   RETURNS a DBOperation 
*/
  buildUpdateOperation(dbIndexHandler, keys, values, transaction, callback);


/* buildScanOperation(QueryHandler queryHandler,
                        Object properties, 
                        DBTransactionHandler transaction,
                        function(error, result) userCallback)
   IMMEDIATE
   Define an operation which when executed will scan a table using the index.
   
   QueryHandler is an object that is originally created from the Session.createQuery call
   and subsequently modified using a builder pattern to specify a query. Properties of
   QueryHandler include the QueryPredicate and DBIndexHandler, which in turn contains
   DBTableHandler.
   
   Properties is an object that contains a simple collection of named values:
     order: either 'asc' or 'desc' if the results are ordered
     skip: the number of items to skip from the result
     limit: the number of items to return after items have been skipped
     
     Other properties have names matching the query parameter names
     
   After the operation is executed, the result can be processed to retrieve values from the scan.
  
   RETURNS a DBOperation 
*/
  buildScanOperation(queryHandler, properties, transaction, callback);


/* buildScanProjectionOperation(QueryHandler queryHandler,
                        Object properties, 
                        Projection projection,
                        DBTransactionHandler transaction,
                        function(error, result) userCallback)
   IMMEDIATE
   Define an operation which when executed will scan a table using the index
   according to the projection.
   
   QueryHandler is an object that is originally created from the Session.createQuery call
   and subsequently modified using a builder pattern to specify a query. Properties of
   QueryHandler include the QueryPredicate and DBIndexHandler, which in turn contains
   DBTableHandler.
   
   Properties is an object that contains a simple collection of named values:
     order: either 'asc' or 'desc' if the results are ordered
     skip: the number of items to skip from the result
     limit: the number of items to return after items have been skipped
     
     Other properties have names matching the query parameter names
     
   After the operation is executed, the result can be processed to retrieve values from the scan.
  
   RETURNS a DBOperation 
*/
  buildScanOperation(queryHandler, properties, projection, transaction, callback);


/* buildDeleteOperation(DBIndexHandler dbIndexHandler, 
                        Object keys,
                        DBTransactionHandler transaction,
                        function(error, DBOperation) userCallback)
   IMMEDIATE 
   Define an operation which when executed will delete a row
 
   RETURNS a DBOperation 
*/  
  buildDeleteOperation(dbIndexHandler, keys, transaction, callback);


/* getTransactionHandler() 
   IMMEDIATE
   
   RETURNS the current transaction handler, creating it if necessary
*/
  getTransactionHandler()


/* void setLockMode(LockMode lockmode)
  IMMEDIATE

  Set the lock mode for read operations. This will take effect immediately
  and will remain in effect until this session is closed or this method
  is called again.
*/
  setLockMode(mode)


/* close(callback) 
   ASYNC
   
   Close DBSession and free all resources. 
   Callback is optional; if supplied, will receive (err).
*/
  close(callback);


/* begin() 
   IMMEDIATE
   
   Begin a user transaction context; exit autocommit mode.
*/
  begin();

/* commit(callback) 
   ASYNC
   
   Commit a user transaction. Enter autocommit mode.
   Callback is optional; if supplied, will receive (err).
*/
  commit(callback);

/* rollback(callback) 
   ASYNC
   
   Roll back a user transaction. Enter autocommit mode.
   Callback is optional; if supplied, will receive (err).
*/
  rollback(callback);