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