SessionFactory

/*
   Copyright (c) 2013, 2021, Oracle and/or its affiliates.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License, version 2.0,
   as published by the Free Software Foundation.

   This program is also distributed with certain software (including
   but not limited to OpenSSL) that is licensed under separate terms,
   as designated in a particular file or component or in included license
   documentation.  The authors of MySQL hereby grant you an additional
   permission to link the program and your derivative works with the
   separately licensed software that they have included with MySQL.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License, version 2.0, for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
*/

/** 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);