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

/** Find a specific instance based on primary or unique key value.
 * ASYNC
 *
 * The constructor parameter is the constructor function of a mapped domain 
 * object.
 * 
 * The parameter "keys" may be of any type. Keys must uniquely identify
 * a single row in the database. 
 * If keys is a simple type (number or string), then the parameter type must 
 * be the same type as or compatible with the primary key type of the mapped 
 * object.  
 * Otherwise, properties are taken from the parameter and matched against 
 * property names in the mapping. Primary key properties will be used if all 
 * are present, and other properties will be ignored. 
 * If keys cannot identify the primary key, property names corresponding to 
 * unique key columns will be used. If no complete primary or unique key 
 * properties are found, an error is reported.
 *
 * For multi-column primary or unique keys, all key fields must be set.
 *
 * The returned object will be loaded based on the mapping and the current
 * values in the database.
 *
 * This function returns a promise.  On success, the promise will be fulfilled 
 * with the found object.  The optional callback receives an error value and the 
 * found object.  Any extra arguments passed after the callback will
 * be passed to the callback function verbatim as parameters following 
 * the found instance value.
 *
 * @method find
 * @param constructor the constructor function of a mapped domain object
 * @param keys the instance to find in the database
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                    err: the node.js Error object
 *                    instance: the domain model object or null if not found
 * @return promise
 */
find(Function constructor, Object keys, [callback], [...]);

/** Find a specific instance based on primary or unique key value.
 * See other variant for semantics.
 * ASYNC
 * 
 * @method find
 * @param tableName the table name
 * @param keys the instance to find in the database
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                    err: the node.js Error object
 *                    instance: the domain model object or null if not found
 * @return promise
 */
find(String tableName, Object keys, [callback], [...]);


/** Load a specific instance by matching its primary or unique key with 
 * a database row. Load will never create a new domain object.
 * ASYNC
 * 
 * The parameter "instance" must have its primary or unique key value(s) set.
 * The mapped values in the object will be loaded based on the current
 * values in the database. Unmapped properties in the object will be unchanged.
 * 
 * Primary key properties will be used if all are present,
 * and all other properties will be ignored.
 * Otherwise, property names corresponding to unique key columns
 * will be used. If no complete primary or unique key properties
 * are found, an error is reported.
 *
 * This function returns a promise.  On success, the promise will be fulfilled 
 * with the loaded instance.  The optional callback receives an error value and 
 * the loaded instance.  Any extra arguments passed after the callback will 
 * be passed to the callback function verbatim as parameters following 
 * the loaded instance value.
 * 
 * @method load
 * @param instance the instance to load from the database
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                    err: the node.js Error object
 *                    instance: the domain model object or null if not found
 * @return promise
 */
load(Object instance, [callback], [...]);

/** Insert the instance into the database.
 * ASYNC
 *
 * If the instance already exists in the database, an exception is 
 * reported in the callback.
 * 
 * For autogenerated values, the values will be present in the instance
 * when the callback is called.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param instance the instance to insert
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                    err: the node.js Error object
 * @return promise
 */
persist(Object instance, [callback], [...]);
  
/** Insert the instance into the database. See the other variant for semantics.
 * ASYNC
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param constructor the constructor function for a mapped domain object
 * @param values: values for the new instance
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 */
persist(Function constructor, Object values, [callback], [...]);
  
/** Insert the instance into the database. See the other variant for semantics.
 * ASYNC
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param tableName the table name
 * @param values: values for the new instance
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 */
persist(String tableName, Object values, [callback]. [...]);
  
/** Delete an instance of a class from the database by a primary or unique key.
 * ASYNC
 * The key values in the object must uniquely identify
 * a single row in the database. 
 * If the instance does not exist in the database,
 * an error is reported in the callback.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 * 
 * @param the instance of a mapped domain object to delete from the database
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 */
remove(Object instance, [callback], [...]);

/** Delete a row from the database by a unique or primary key.
 * ASYNC
 * The constructor parameter is the constructor function for a mapped domain 
 * object. If keys is a simple type (number or string), then the parameter type
 * must be the same type as or compatible with the primary key type 
 * of the mapped object.
 * Otherwise, properties are taken from the parameter and matched against 
 * property names in the mapping. 
 * If all Primary Key properties are present, they will be used, 
 * and other properties will be ignored. 
 * Otherwise, if keys cannot identify the primary key, property names 
 * corresponding to unique key columns will be used. 
 * If no complete primary or unique key properties are found, an error
 * is reported.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param constructor the constructor for a mapped domain object
 * @param keys object containing the keys of the object to delete
 * @param callback function to be called when operation has completed, with parameters:
 *   err: the node.js Error object
 * @return promise
 */
remove(Function constructor, Object keys, [callback], [...]);

/** Delete a row from the database by a unique or primary key.
 * ASYNC
 * See other variant for semantics.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param tableName the table name
 * @param keys object containing the keys of the object to delete
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 */
remove(String tableName, Object keys, [callback], [...]);

/** Update the instance in the database without necessarily retrieving it.
 * The primary key field is used to determine which instance is to be updated.
 * If the instance does not exist in the database, an error is reported.
 * This method cannot be used to change the primary key.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param instance the instance to update
 * @param callback function to be called when operation has completed, 
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 * ASYNC
 */
update(Object instance, [callback], [...]);

/** Update the instance in the database without necessarily retrieving it.
 * Unique key field(s) of the keys object determine which instance
 * is to be updated. The values object provides values to be updated.
 * If the keys object contains all fields corresponding to the primary key,
 * the primary key will identify the instance. If not, unique keys will be
 * chosen non-deterministically.
 * If the instance does not exist in the database, an error is reported.
 * This method cannot be used to change the primary key.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param constructor constructor function of a mapped domain object
 * @param keys an object containing unique keys for the instance to update
 * @param values an object containing values to update
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 * ASYNC
 */
update(Function constructor, keys, values,  [callback], [...]);

/** Update the instance in the database without necessarily retrieving it.
 * See other variant for semantics.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param tableName the table name
 * @param keys an object containing unique keys for the instance to update
 * @param values an object containing values to update
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 * ASYNC
 */
update(String tableName, keys, values, [callback], [...]);

/** Save the instance in the database without checking for existence.
 * The id field is used to determine which instance is to be saved.
 * If the instance exists in the database it will be updated.
 * If the instance does not exist, it will be created.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param instance the instance to insert or update
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 * ASYNC
 */
save(Object instance, [callback], [...]);

/** Save the instance in the database without checking for existence.
 * See other variant for semantics.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param constructor the constructor function of a mapped domain object
 * @param values the values to insert or update
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 * ASYNC
 */
save(Function constructor, Object values,  [callback], [...]);

/** Save the instance in the database without checking for existence.
 * See other variant for semantics.
 *
 * This function returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value.  Any extra arguments 
 * passed after the callback will be passed to the callback function verbatim
 * as parameters following the error value.
 *
 * @param tableName the name of the table
 * @param values the values to insert or update
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                   err: the node.js Error object
 * @return promise
 * ASYNC
 */
save(String tableName, Object values, [callback], [...]);

/** Is this context a batch?
 * @return true if this context is a batch; false if this context is a session
 * IMMEDIATE
 */
isBatch();

/** How many operations are currently defined in this batch?
 * @return number of operations in batch
 * IMMEDIATE
 */
getOperationCount();

/** execute()
 * ASYNC
 * Execute this batch. All operations are executed and for each operation
 * the callback for that operation is called (in no particular order).
 * The execute function's callback is also called.
 * The batch is executed in the context of the session's current state:
 * autocommit if a transaction has not been started;
 * 
 * execute() returns a promise.  On success, the promise will be fulfilled.
 * The optional callback receives only an error value and any extra arguments. 
 * Extra arguments passed after the callback will be passed to the callback 
 * function verbatim as parameters following the error.
 *
 * @method execute
 * @param callback
 * @return promise
 */
execute([callback], [...]);

/** clear()
 * IMMEDIATE
 * Clear this batch. The transaction state is unaffected.
 * The batch is still valid, but all operations previously defined
 * are removed, restoring the batch to a clean state.
 * If operations are defined, the callback for each operation will be called
 * with an error indicating that the batch has been cleared.
 */
clear();

/** getSession()
 * IMMEDIATE
 * Get the session from which this batch was created.
 * @return the session
 */
getSession();


/* 
 * Users may find useful a "user" property of session and batch.
 * The mynode implementation will not ever define a property called "user".
 */

