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

/* 
   A DBTableHandler is a persistent metadata object that combines table 
   information from the data dictionary with user-supplied information about 
   column selection, column name mapping, and data conversion handlers.

*/

/* Related objects:
   TableMetadata: as defined in api/TableMetadata
   TableMapping:  as defined in api/TableMapping 
*/


/* DBTableHandler() constructor
   IMMEDIATE

   Create a DBTableHandler for a table and a mapping.

   The TableMetadata may not be null.

   If the TableMapping is null, default mapping behavior will be used.
   Default mapping behavior is to:
     select all columns when reading
     use default converters for all data types
     perform no remapping between field names and column names
*/
  function DBTableHandler(tableMetadata, TableMapping) {};


/************************************************
      Methods for working with mapped objects 
 ************************************************/


/* DBTableHandler.newResultObject
   IMMEDIATE
   
   Create a new object using the constructor function (if set).
*/
  function newResultObject() {};
  

/* getMappedFieldCount()
   IMMEDIATE 
     
   Returns the number of fields mapped to columns in the table 
*/
  getMappedFieldCount();


/* allColumnsMapped()
   IMMEDIATE   

   Boolean: returns True if all columns are mapped
*/
  allColumnsMapped();


/* getColumnMetadata() 
   IMMEDIATE 
   
   Returns an array containing ColumnMetadata objects in field order
*/   
  getColumnMetadata();

  
/* get()
   IMMEDIATE
   
   Return the property of obj corresponding to fieldNumber 
*/
  get(obj, fieldNumber);


/* getFields(domainObject)
   IMMEDIATE 
   
   Returns an array containing the properties of domainObject in field order
*/
  getFields(obj);

/* getFieldsWithListener(domainObject, adapter, fieldValueDefinedListener) 
   IMMEDIATE 
   
   Returns an array containing the properties of domainObject in field order
   Calls into fieldValueDefinedListener to indicate whether each field is defined.
   Calls into databaseTypeConverter for adapter if needed.
*/
  getFieldsWithListener(obj, adapter, fieldValueDefinedListener);


/* set() 
   IMMEDIATE
  
   Set property of object, corresponding to fieldNumber, to value.
   Returns true on success, false on failure.
*/
  set(obj, fieldNumber, value);


/* setFields()
   IMMEDIATE
   
   Set all mapped fields in object according to an ordered array of field values
*/
  setFields(obj, values);
  

/* DBIndexHandler getIndexHandler(Object keys)
   IMMEDIATE

   Given an object containing keys as defined in API Context.find(),
   choose an index to use as an access path for the operation,
   and return a DBIndexHandler for that index.
   
   DBIndexHandler implements this subset of DBTableHandler methods:
      getMappedFieldCount()
      get()
      getFields()
*/
  getIndexHandler(keys);
  

/** boolean allFieldsIncluded(Object values)
 *  IMMEDIATE
 *  Boolean: returns True if values include all mapped fields
 */
  allFieldsIncluded(values);
