381 lines
16 KiB
Plaintext
381 lines
16 KiB
Plaintext
/** 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".
|
|
*/
|
|
|