/** openSession() : open a database session object
 * ASYNC
 *
 * Session provides a context for database transactions and operations.
 * Each independent user should have its own Session.
 *
 * The resources required for sessions are allocated in advance. 
 * It may return an error in the callback indicating that those resources are 
 * not available.
 *
 * 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.
 * 
 * The "mappings" parameter can be used to preload metadata for application 
 * tables and to validate the defind mappings between stored data and 
 * JavaScript objects.  If mappings 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.
 * If mappings 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 mappings    mappings to validate when connection is made
 * @param callback    the function to call when the session is ready for use
 * @param additional  parameters will be returned in the callback
 * @return promise
 * @async
 *
 */
openSession(Object mappings, [callback], [...]);

/** Get all open sessions that have been created by this factory.
 *
 * @return all open sessions
 * IMMEDIATE
 */
Array getOpenSessions();

/** close(): close the connection to the database
 * ASYNC
 * 
 * Close the connection to the database.
 * This ensures proper disconnection.
 * 
 * @param function to call when close is complete
 * @return nothing
 */
close(function(error));

/* registerTypeConverter 
   IMMEDIATE
   Register a converter for a SQL data type 
   If converterObject is null, *unregister* the typeConverter for this 
   data type.

   @param typeName is a column type as defined in TableMetadata
   @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);