Jones

/**
 * ConnectionProperties()
 * IMMEDIATE
 * CONSTRUCTOR
 * 
 * ConnectionProperties provides a powerful and flexible means to obtain the
 * particular set of ConnectionProperties for an instance of an application.
 * Its two parameters identify a backend database (e.g. "mysql", "ndb", etc.)
 * and a connection environment (e.g. "test", "staging", "readonly", etc.).
 *
 * implName_or_connectionProperties may either be the name of a Jones
 * adapter (e.g. "mysql"), or a ConnectionProperties object.
 *   - If it is a string naming a backend adapter, then the default
 *     ConnectionProperties for that adapter will be fetched.
 *   - If it is an object, and contains a member property
 *     "implementation", the default ConnectionProperties for
 *     adapter <implementation> are fetched, and then overridden by
 *     the properties specified in the object.
 *
 * deployment is optional, and may be a string or a function.  In both cases
 * it refers to a function that can receive the ConnectionProperties obtained
 * using implName_or_connectionProperties and further modify them.
 *    - If it is unspecified or undefined, the ConnectionProperties object
 *      described above will be returned directly to the caller.
 *    - If it is a function, the function will be called with a single parameter
 *      holding a ConnectionProperties object.  The function may modify the
 *      object in place, or it may return a new object.  The new object or
 *      modified properties will be the return value of ConnectionProperties().
 *    - If it is a string, Jones will search all jones_deployments.js files
 *      found in the search path described below.  For the first file found
 *      to export a function whose name matches the string value, that function
 *      will be called with a single parameter as above.  If the named
 *      deployment function is not found in any file, an AssertionError is
 *      thrown.
 *
 *  After any supplied deployment function has been called, but before
 *  being returned to the user, the ConnectionProperties object is tested
 *  for a string member named "implementation".  If this property does not
 *  exist, or if it exists but does not name a Jones DBServiceProvider,
 *  an AssertionError is thrown.
 *
 *    jones_deployments.js seach path
 *    -------------------------------
 *    ConnectionProperties() searches for jones_deployments.js in the following
 *    directories:
 *       * The directory containing the currently executing main source file.
 *       * For each required() module in a chain from the main source file to
 *         jones.js, the directory containing that module.
 *       * The parent directory of the one containing the main source file,
 *         and then its parent, etc., up to the filesystem root.
 *       * The current working directory as stored in the CWD environment variable.
 *
 *  A sample jones_deployments.js file is provided.
 */
ConnectionProperties(implName_or_connectionProperties, deployment);


/**
 * TableMapping()
 * IMMEDIATE
 * CONSTRUCTOR
 *
 * The TableMapping constructor is visible as a top-level function.
 * Refer to the TableMapping documentation for details.
 */
TableMapping(tableName_or_tableMapping);

 
/**
 * Projection()
 * IMMEDIATE
 * CONSTRUCTOR
 *
 * The Projection constructor is visible as a top-level function.
 * Refer to the Projection documentation for details.
 */
Projection(constructor);

 
/**
 * connect()
 * ASYNC
 * 
 * Connect to the data source. 
 * This is a "super-heavyweight" call:  it could involve connecting to many 
 * other nodes on the network, waiting for them to become ready, and making 
 * multiple requests to them. 
 *
 * This function returns a promise.  On success, the promise will be fulfilled 
 * with a SessionFactory.  The optional callback receives an error value and a 
 * SessionFactory.  Any extra arguments passed after the callback function will
 * be returned to the callback verbatim.
 *
 * The "implementation" member of the properties object determines the back end 
 * driver implementing the SessionFactory.
 *
 * The "constructorsOrTableNames" parameter can be used to preload metadata for application 
 * tables and to validate the defined mappings between stored data and 
 * JavaScript objects.  If constructorsOrTableNames contains a string table name, a Domain 
 * Object Constructor function, or an array of these, then metadata is loaded 
 * from the database and validated against the requirements of the mapping.
 * Any failure to validate the mappings will result in an error.
 * If constructorsOrTableNames is undefined, null, or an empty array, no mappings will be 
 * loaded or validated; this means validation is deferred until tables are 
 * used in application code.
 *  
 *  @param properties  properties object describing the session
 *  @param constructorsOrTableNames constructors or table names to validate when connection is made
 *  @param callback    function called after connection is complete.
 *  @return a promise
 */
connect(properties, mappings, [callback], [...]);


/**
 * openSession()
 * ASYNC
 * 
 * Connect to the data source and get a Session.  
 *
 * This is a convenience method. It returns a Session in the callback function.
 * This is equivalent to calling connect and then getSession on the
 * SessionFactory that is returned in the callback function.
 *
 * The "implementation" member of the properties object determines the 
 * implementation of the Session.
 *
 * The "constructorsOrTableNames" parameter can be used to preload metadata for application 
 * tables and to validate the defined mappings between stored data and 
 * JavaScript objects.  If constructorsOrTableNames contains a string table name, a Domain 
 * Object Constructor function, or an array of these, then metadata is loaded 
 * from the database and validated against the requirements of the mapping.
 * Any failure to validate the mappings will result in an error.
 * If constructorsOrTableNames is undefined, null, or an empty array, no mappings will be 
 * loaded or validated; this means validation is deferred until tables are 
 * used in application code.
 *
 * This function returns a promise.  On success, the promise will be fulfilled 
 * with a Session.  The optional callback receives an error value and a 
 * Session.  Any extra arguments passed after the callback function will
 * be returned to the callback verbatim.
 *
 *  
 *  @param properties  properties object describing the session
 *  @param constructorsOrTableNames    constructorsOrTableNames to validate when connection is made
 *  @param callback    function called after connection is complete.
 *  @return a promise
 */
openSession(Properties, constructorsOrTableNames, [callback], [...]);


/** Get all SessionFactories that have been created by this module.
 * All session factories are returned in an array. 
 * @return open session factories
 * IMMEDIATE
 */
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();


/** getDBServiceProvider
 *  Generally not used in application development.
 *  Given a name, returns a DBServiceProvider.
 * IMMEDIATE
 */
getDBServiceProvider(name);


/** registerDBServiceProvider(name, module)
 *  Generally not used in application development.
 *
 *  This allows you to bootstrap a DBServiceProvider in development,
 *  registering it by name so that Jones can use it before it has been
 *  installed.
 *
 * IMMEDIATE
 */
registerDBServiceProvider(name, node_module);