/*
   Copyright (c) 2013, 2020, Oracle and/or its affiliates.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License, version 2.0,
   as published by the Free Software Foundation.

   This program is also distributed with certain software (including
   but not limited to OpenSSL) that is licensed under separate terms,
   as designated in a particular file or component or in included license
   documentation.  The authors of MySQL hereby grant you an additional
   permission to link the program and your derivative works with the
   separately licensed software that they have included with MySQL.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License, version 2.0, for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
*/

/* 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);

