merge latest nodejs-adapter into cluster 7.3

Author: jdduncan

storage/ndb/nodejs/API-documentation/Batch

@@ -1,4 +1,334 @@
-Batch extends Context
+/** 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();
 
 /** execute()
  * ASYNC
@@ -7,11 +337,17 @@ Batch extends Context
  * 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;
- * default lock mode;
- * the partition key.
- * @return undefined
+ * 
+ * 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(Function(error, ... ) callback, ...);
+execute([callback], [...]);
 
 /** clear()
  * IMMEDIATE
@@ -29,3 +365,10 @@ clear();
  * @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".
+ */
+