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

/**
 * ConnectionProperties()
 * IMMEDIATE
 * CONSTRUCTOR
 *
 * If implName_or_connectionProperties is the name of a backend adapter,
 * (i.e. either "mysql" or "ndb"), this constructor returns the default
 * ConnectionProperties for that adapter.
 * 
 * If implName_or_connectionProperties is a ConnectionProperties object, 
 * then this works as a copy constructor, copying it to and returning a new 
 * ConnectionProperties object.
 * 
 * Otherwise, returns undefined.
 */
ConnectionProperties(implName_or_connectionProperties);


/**
 * 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 "superheavyweight" 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 backend 
 * driver implementating the SessionFactory.
 *
 * 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 properties  properties object describing the session
 *  @param mappings    mappings 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 "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.
 *
 * 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 mappings    mappings to validate when connection is made
 *  @param callback    function called after connection is complete.
 *  @return a promise
 */
openSession(Properties, mappings, [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();


// 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.

Connection();
getConnectionKey();
getConnection();
newConnection();
deleteFactory();
