merge latest nodejs-adapter into 7.4

Author: jdduncan

storage/ndb/nodejs/.bzrignore

@@ -9,3 +9,5 @@ test/disabled-tests.conf
 config.gypi
 config.waf
 benchmark_logs
+node_modules
+build

storage/ndb/nodejs/API-documentation/Meta

@@ -0,0 +1,97 @@
+
+/** meta is a factory used to define forward mapping for tables and columns.
+ * Functions are called to create Meta objects that are stored with field mappings.
+ * The Meta objects returned from these functions can be annotated with additional properties.
+ *
+ * Functions that can be used with fields:
+ *    meta.binary(lengthInBytes)       doit callback.binary(lengthInBytes, lob, nullable);
+ *    meta.char(lengthInCharacters)    doit callback.char(lengthInCharacters, lob, nullable);
+ *    meta.date()                      doit callback.date(nullable);
+ *    meta.datetime(fsp)               doit callback.datetime(fsp, nullable);
+ *    meta.decimal(precision, scale)   doit callback.decimal(precision, scale, nullable);
+ *    meta.double()                    doit callback.double(nullable);
+ *    meta.float()                     doit callback.float(nullable);
+ *    meta.integer(bits)               doit callback.integer(bits, unsigned, nullable);
+ *    meta.interval(fsp)               doit callback.interval(fsp, nullable);
+ *    meta.int synonym for integer     doit callback.integer(bits, unsigned, nullable);
+ *    meta.number synonym for decimal  doit callback.decimal(precision, scale, nullable);
+ *    meta.time(fsp)                   doit callback.time(fsp, nullable);
+ *    meta.timestamp(fsp)              doit callback.timestamp(fsp, nullable);
+ *    meta.varchar(lengthInCharacters) doit callback.varchar(lengthInCharacters, lob, nullable);
+ *    meta.varbinary(lengthInBytes)    doit callback.varbinary(lengthInBytes, lob, nullable);
+ *    meta.year()                      doit callback.year(nullable);
+ *
+ * Meta objects can be modified to include additional properties that apply to field mapping:
+ *    Meta.charset(name1, name2)       character set and collation; applies to char and varchar types
+ *    Meta.hash()                      hash (only) index; applies to all indexable types
+ *    Meta.lob()                       large object; applies to varbinary and varchar
+ *    Meta.notNull()                   not null; applies to all types
+ *    Meta.primaryKey()                primary key; applies to all primary key types
+ *    Meta.uniqueKey()                 unique key; applies to all indexable types
+ *    Meta.unsigned()                  unsigned; applies to integer types
+ *
+ * Examples: 
+ *   tableMapping.mapField('id', meta.int(32).primaryKey().unsigned()) => id INT UNSIGNED PRIMARY KEY
+ *   tableMapping.mapField('name', meta.varchar(32).notNull()) => name VARCHAR(32) NOT NULL
+ *   tableMapping.mapField('ssn', meta.char(9).hash()) ==> ssn char(9) INDEX USING HASH
+ *   tableMapping.mapField('scan', meta.varchar(1024000).lob() ==> TEXT(1024000)
+ *
+ * Functions that can be used with tables:
+ *    meta.index([columnNames], optionalIndexName);
+ *    meta.primaryKey([columnNames]);
+ *    meta.uniqueKey([columnNames], optionalIndexName);
+ *    meta.hashKey([columnNames], optionalIndexName);
+ *    meta.orderedIndex([columnNames], optionalIndexName);
+ *
+ * Examples:
+ *  new TableMapping('a', meta.primaryKey(['b', 'c'])); specifies primary key over columns b and c
+ *  new TableMapping('a', meta.primaryKey(['b', 'c'])).hash; specifies hash-only primary key over columns b and c
+ *  new TableMapping('a', meta.uniqueKey('b')); specifies unique ordered key over column b
+ *  new TableMapping('a', meta.uniqueKey('b').hash()); specifies unique hash key over column b
+ *  new TableMapping('a', meta.index('b')); specifies ordered index over column b
+ *  new TableMapping('a', meta.hashKey('b')); specifies unique hash key over column b
+ 
+ */
+meta
+
+/** Create a new Meta object that holds meta information. This constructor function is private,
+ * and can only be used by a method on meta. All Meta objects are defined with a doit function
+ * which calls back a function specific to the type of the Meta. The callback may be used
+ * to create table definitions.
+ */
+Meta();
+
+/** Call back the caller based on the type of Meta. See above for method called based on type.
+ * A Meta constructed via meta.year() will call callback.year with the nullable value as a parameter
+ * and return the value to the caller of doit.
+ */
+doit(callback);
+
+/** Annotate a Meta with NOT NULL property. 
+ @return this; // allows fluent method chaining
+ */
+notNull();
+
+/** Annotate a Meta with UNSIGNED property. 
+ @return this; // allows fluent method chaining
+ */
+unsigned();
+
+/** Annotate a Meta with PRIMARY KEY property.
+ @return this; // allows fluent method chaining
+ */
+primary();
+
+/** Annotate a Meta with UNIQUE KEY property.
+ * This annotation specifies an ordered index unless hash is also used.
+ @return this; // allows fluent method chaining
+ */
+uniqueKey();
+unique();
+
+/** Annotate a Meta with USING HASH property. 
+ * When used with primaryKey or uniqueKey, this specifies that the index created uses a hash index (only).
+ @return this;
+ */
+hash();
+

storage/ndb/nodejs/API-documentation/Mynode

@@ -117,6 +117,19 @@ openSession(Properties, mappings, [callback], [...]);
 getOpenSessionFactories();
 
 
+/** Close all open SessionFactories 
+ *
+ * This method closes all SessionFactories.
+ * Because a SessionFactory likely uses an open TCP connection with registered
+ * callbacks, Node.JS will generally not exit while any SessionFactory is
+ * still open.
+ *
+ * @param callback   function called after all SessionFactories are closed
+ * @return a promise
+ */
+closeAllOpenSessionFactories();
+
+
 // The following functions are part of the public API but are not intended for
 // application use.  They form part of the contract between mynode and 
 // SessionFactory.

storage/ndb/nodejs/API-documentation/Query

@@ -143,25 +143,51 @@
  */
  function between(Object parameterOrLiteral, Object parameterOrLiteral);
 
+/** isNull represents null comparison of a property.
+ * @return QueryPredicate
+ * IMMEDIATE
+ */
+ function isNull();
+
+/** isNotNull represents not-null comparison of a property.
+ * @return QueryPredicate
+ * IMMEDIATE
+ */
+ function isNotNull();
+
 /** QueryPredicate represents the result of comparing a query field to a
  * parameter. QueryPredicate can be used as the filter for a query or can be
- * combined with other QueryPredicates using boolean functions 'and', 'or', 
- * and unary function 'not'.
+ * combined with other QueryPredicates using functions 'and', 'or', 
+ * 'andNot', 'orNot', and 'not'.
  */
  function QueryPredicate();
 
-/** and represents the and condition joining this QueryPredicate with another.
+/** and represents the 'and' condition joining this QueryPredicate with another.
  * @return QueryPredicate
  * IMMEDIATE
  */
  function and(QueryPredicate other);
 
-/** or represents the or condition joining this QueryPredicate with another.
+/** andNot represents the 'and' condition joining this QueryPredicate with
+ * the negation of another.
+ * @return QueryPredicate
+ * IMMEDIATE
+ */
+ function andNot(QueryPredicate other);
+
+/** or represents the 'or' condition joining this QueryPredicate with another.
  * @return QueryPredicate
  * IMMEDIATE
  */
  function or(QueryPredicate other);
 
+/** orNot represents the 'or' condition joining this QueryPredicate with
+ * the negation of another.
+ * @return QueryPredicate
+ * IMMEDIATE
+ */
+ function orNot(QueryPredicate other);
+
 /** not represents the negation of this QueryPredicate.
  * @return QueryPredicate
  * IMMEDIATE

storage/ndb/nodejs/API-documentation/Session

@@ -19,11 +19,15 @@
  * 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 and the current
- * values in the database.
+ * 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 
@@ -32,15 +36,16 @@
  * the found instance value.
  *
  * @method find
- * @param constructor the constructor function of a mapped domain object
+ * @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 constructor, Object keys, [callback], [...]);
+find(Function constructorOrProjection, Object keys, [callback], [...]);
 
 /** Find a specific instance based on primary or unique key value.
  * See other variant for semantics.
@@ -494,18 +499,6 @@ listTables(databaseName, callback);
 getTableMetadata(databaseName, tableName, callback);
 }
 
-/** Use the projection for find and query operations on the domain object.
- * projection:= {constructor: domainObject, 
- *   fields: [field, field...], 
- *   relationships: [relationship, relationship...]}
- * The domain object must be mapped and will be validated by this function.
- * If fields is omitted, all fields in the mapping will be fetched.
- * If relationships is omitted, no relationships in the mapping will be fetched.
- * This method returns a promise and can use a callback.
- * ASYNC
- */
-useProjection(projection, callback);
-
 /* 
  * Users may find useful a "user" property of session and batch.
  * The mynode implementation will not ever define a property called "user".

storage/ndb/nodejs/API-documentation/SessionFactory

@@ -60,3 +60,23 @@ close(function(error));
    @param converterObject is as defined in Converter
 */
 registerTypeConverter(typeName, converterObject);
+
+/** db(): get a new db object bound to a database that supports "easy to use"
+ *  insert and find operations without defining tables or mappings. Each operation
+ *  is executed in auto-commit mode using a new session.
+ *  IMMEDIATE
+ *  @param databaseName is the name of the database to use; default is session factory's database
+ *  @return the db object
+ */
+db db(databaseName);
+
+/** mapTable(): associate a TableMapping with a database and table name.
+ *  If a table is needed for an operation and the table does not exist, use the TableMapping
+ *  meta to define the table. The database and table name are taken from the TableMapping.
+ *  If the TableMapping does not include the datbase, use the default database for this session
+ *  factory. If there is already a TableMapping with the same database and table, it is replaced.
+ *  IMMEDIATE
+ *  @param tableMapping is the mapping to associate with the database and table in this session factory
+ */
+mapTable(tableMapping);
+

storage/ndb/nodejs/API-documentation/TableMapping

@@ -24,7 +24,9 @@ TableMapping = {
                                       Can also be called "field",
                                       and can also hold a single FieldMapping. 
                                       @property fields @type Array */
-  error                  : ''     /** Reports errors during construction */ 
+  error                  : '',    /** Reports errors during construction */ 
+  mappedFieldNames       : [],    /** mapped field names (excluded from sparse field handling) */
+  meta                   : []
 
 };
 
@@ -43,8 +45,13 @@ FieldMapping = {
                                @type String */
   persistent    : true,    /** Whether this field should be stored in database.
                                @type Boolean @default true */
-  converter     : null     /** Converter class to use with this field  
+  converter     : null,    /** Converter class to use with this field  
                                @type Converter @default null */
+  sparseFieldNames: null,  /** sparse field names to store in this column 
+                               @type array @default null */
+  meta         : undefined /** meta for forward table definition
+                               @see Meta for usage
+                               @type Meta @default undefined */
 };
 
 

storage/ndb/nodejs/Adapter/adapter_config.js

@@ -19,51 +19,63 @@
 */
 
 
-global.path            = require("path");
-global.fs              = require("fs");
-global.assert          = require("assert");
-global.util            = require("util");
-
-global.adapter_dir     = __dirname;
-global.parent_dir      = path.dirname(adapter_dir);
-global.api_dir         = path.join(adapter_dir, "api");
-global.spi_dir         = path.join(adapter_dir, "impl");
-global.spi_doc_dir     = path.join(spi_dir, "SPI-documentation");
-global.api_doc_dir     = path.join(parent_dir, "API-documentation");
-global.converters_dir  = path.join(parent_dir, "Converters");
-
-global.spi_module      = path.join(spi_dir, "SPI.js");
-global.api_module      = path.join(api_dir, "mynode.js");
-global.udebug_module   = path.join(api_dir, "unified_debug.js");
-global.unified_debug   = require(udebug_module);
+var path               = require("path");
+var fs                 = require("fs");
+var mynode, parent_dir, udebug_module;
+
+mynode                     = {};
+mynode.fs                  = {};
+parent_dir                 = path.dirname(__dirname);
+
+mynode.fs.adapter_dir      = __dirname;
+mynode.fs.api_dir          = path.join(mynode.fs.adapter_dir, "api");
+mynode.fs.spi_dir          = path.join(mynode.fs.adapter_dir, "impl");
+
+mynode.fs.spi_doc_dir      = path.join(mynode.fs.spi_dir, "SPI-documentation");
+mynode.fs.api_doc_dir      = path.join(parent_dir, "API-documentation");
+mynode.fs.backend_doc_dir  = path.join(parent_dir, "Backend-documentation");
+mynode.fs.converters_dir   = path.join(parent_dir, "Converters");
+
+mynode.fs.spi_module       = path.join(mynode.fs.spi_dir, "SPI.js");
+mynode.fs.api_module       = path.join(mynode.fs.api_dir, "mynode.js");
+
+mynode.fs.suites_dir       = path.join(parent_dir, "test");
+mynode.fs.samples_dir      = path.join(parent_dir, "samples");
+
+udebug_module              = path.join(mynode.fs.api_dir, "unified_debug.js");
 
 
 /* Find the build directory */
-var build1 = path.join(spi_dir, "build");
+var build1 = path.join(mynode.fs.spi_dir, "build");
 var build2 = path.join(parent_dir, "build");
 var existsSync = fs.existsSync || path.existsSync;
 
 if(existsSync(path.join(build1, "Release", "ndb_adapter.node"))) {
-  global.build_dir = path.join(build1, "Release");
+  mynode.fs.build_dir = path.join(build1, "Release");
 }
 else if(existsSync(path.join(build2, "Release", "ndb_adapter.node"))) {
-  global.build_dir = path.join(build2, "Release");
+  mynode.fs.build_dir = path.join(build2, "Release");
 }
 else if(existsSync(path.join(build1, "Debug", "ndb_adapter.node"))) {
-  global.build_dir = path.join(build1, "Debug");
+  mynode.fs.build_dir = path.join(build1, "Debug");
 }
 else if(existsSync(path.join(build2, "Debug", "ndb_adapter.node"))) {
-  global.build_dir = path.join(build2, "Debug");
+  mynode.fs.build_dir = path.join(build2, "Debug");
 }
 
 /* Some compatibility with older versions of node */
 if(typeof global.setImmediate !== 'function') {
   global.setImmediate = process.nextTick;
 }
 
+/* Export the filesystem config */
+module.exports = mynode.fs;
 
+/* Also make it available globally */
+if(!global.mynode) { global.mynode = {} };
+global.mynode.fs = mynode.fs;
 
-
-
+/* And export unified_debug globally */
+global.unified_debug   = require(udebug_module);
 
 

storage/ndb/nodejs/Adapter/api/Batch.js

@@ -18,8 +18,6 @@
  02110-1301  USA
  */
 
-/*global unified_debug */
-
 "use strict";
 
 var userContext = require("./UserContext.js"),