Session

/* @Class Session
 * 
 */
 
/** 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.
 * If the first parameter is a Projection, the find operation will return
 * the object corresponding to the key. Additionally, the properties 
 * defined in the projection as relationship properties will be fetched,
 * recursively.
 *
 * For multi-column primary or unique keys, all key fields must be set.
 *
 * The returned object will be loaded based on the mapping, the Projection,
 * 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 constructorOrProjection the constructor function of a mapped domain object
 * or a Projection 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 constructorOrProjection, 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]. [...]);
  
/** 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 tableMapping the TableMapping
 * @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(TableMapping tableMapping, 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], [...]);

/** 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 tableMapping the TableMapping
 * @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(TableMapping tableMapping, 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.
 *
 * To efficiently perform read/modify/write, the user should find the object,
 * modify the fields to be updated, set the fields *not* to be updated
 * to undefined, and call update on the object.
 *
 * 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], [...]);

/** 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 tableMapping the TableMapping
 * @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(TableMapping tableMapping, 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], [...]);

/** 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 tableMapping the TableMapping
 * @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(TableMapping tableMapping, 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();

/** Get mappings for a table or class. 
 * The result is a fully resolved TableMapping
 * The parameter may be a table name, a mapped constructor function, or
 * a domain object. 
 *
 * This function returns a promise.  On success, the promise will be fulfilled
 * with a resolved TableMapping value.  The optional callback receives an error 
 * value and the resolved mapping.  Any extra arguments passed after the 
 * callback will be passed to the callback function verbatim as parameters 
 * following the resolved mapping.
 *
 * @method getMapping
 * @param table the table name or constructor of a mapped class
 * @param callback function to be called when operation has completed,
 *                 with parameters:
 *                    err: the node.js Error object
 *                    mapping: the mapping for the parameter
 * @throws Error if the parameter is not an object, string, or function
 * @return promise
 * ASYNC
 */
getMapping(domainObjectTableNameOrConstructor, [callback], [...]);

/** Create a query object that can be used to query the database.
 * The first parameter is:
 *    an object of a type whose constructor has been annotated, or
 *    a constructor that has been annotated, or
 *    a Projection, or
 *    the name of a table.
 * The created query object implements the behavior of Query. 
 * 
 * This function returns a promise.  On success, the promise will be fulfilled
 * with a Query instance.  The optional callback receives an error 
 * value and Query instance.  Any extra arguments passed after the 
 * callback will be passed to the callback function verbatim as parameters 
 * following the Query.
 *
 * @method createQuery
 * @param table name, mapped instance, projection, or constructor of a mapped class
 * @return promise
 * ASYNC
 */
createQuery(domainObjectTableNameProjectionOrConstructor, [callback(err, query)], [...]);

/** Create an empty batch.
 *
 * The batch is used to collect multiple operations to be executed together. 
 *
 *
 * @method createBatch
 * @return Batch
 * IMMEDIATE
 */ 
Batch createBatch();

/** List all current batches.
 * IMMEDIATE
 * @method listBatches
 * @return Array
 */
Array listBatches();

/** Get the current Transaction. 
 * @method currentTransaction
 * @return the transaction
 * IMMEDIATE
 */
Transaction currentTransaction();

/** Close this session. This must be called when the session is
 * no longer needed.
 * 
 * @method close
 * @param callback
 @ async
 */
void close(Function(error) callback);

/** Is this session closed?
 *
 * @method isClosed
 * @return {Boolean} true if the session is closed
 * IMMEDIATE
 */
boolean isClosed();

/** Set the partition key for the next transaction.
 *
 * Normally, this is not needed. Jones will automatically set
 * the partition key based on the first operation in the transaction.
 * If the user needs explicit control over the partition key,
 * this is the way to do it.
 * 
 * The instance must be an object that is capable of being persisted. 
 * The values of the partition key will be taken from the values
 * in the instance.
 * 
 * @method setPartitionKey
 * @param instance the object with all partition key properties set
 * @return an Error object or null if no error
 * IMMEDIATE
 */
Error setPartitionKey(instance);

/** Set the partition key for the next transaction.
 *
 * Normally, this is not needed. Mysql-js will automatically set
 * the partition key based on the first operation in the transaction.
 * If the user needs explicit control over the partition key,
 * this is the way to do it.
 * 
 * The mapping is an object obtained from a class after the
 * class has been annotated. 
 * The parameter "keys" may be of a type that can 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.
 * The returned object will be loaded based on the mapping and the current
 * values in the database.
 * 
 * @return an Error object or null if no error
 * IMMEDIATE
 */
Error setPartitionKey(mapping, keys);

/** 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.
 * @param lockmode the LockMode: 'EXCLUSIVE', 'SHARED', or 'NONE'
 * @return an Error object or null if no error
 *
 * IMMEDIATE
 */
Error setLockMode(lockmode);


/** listTables(database, callback) 
 *  ASYNC
 *  
 *  list tables in database
 */
listTables(databaseName, callback);


/** getTableMetadata(databaseName, tableName, callback) 
 *  ASYNC
 *
 *  Fetch metadata for table 
 */
getTableMetadata(databaseName, tableName, callback);
}

/** allowCreateUnmappedTable
 *  BOOLEAN PROPERTY
 *  READ/WRITE
 *  Defaults to false.
 *
 *  If session.allowCreateUnmappedTable is set to true, then Session calls,
 *  rather than failing when a table does not exist, will create the table
 *  using the TableMapping.
*/


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