/** @class TableMapping 
 *
 * A TableMapping describes the mapping of a domain object in the application
 * to a table stored in the database.
 *
 * A *default* TableMapping is one where each column in a table is mapped
 * to a field of the same name. 
 *
 * Errors that are detected during construction of a TableMapping, including
 * field mapping functions, are reported via the error field. 
 */
TableMapping = {
  table                  :  "" ,  /** Table name @type String */
  database               :  "" ,  /** Database name @type String */
  mapAllColumns          : true,  /** Create a default FieldMapping for
                                      all columns not listed in fields[].
                                      Specifies that all columns, not explicitly
                                      mapped, should be given a default mapping 
                                      to a field of the same name.
                                      @property mapAllColumns @type Boolean 
                                      @default true 
                                  */
  fields                 : null,  /** Holds an array of FieldMapping objects.
                                      Can also be called "field",
                                      and can also hold a single FieldMapping. 
                                      @property fields @type Array */
  error                  : '',    /** Reports errors during construction */ 
  mappedFieldNames       : [],    /** mapped field names (excluded from sparse field handling) */
  meta                   : []
 
};


/** @class FieldMapping 
 *  A FieldMapping describes a single field in a domain object.
 *  There is no public constructor for a FieldMapping.
 *  A FieldMapping can be created using TableMapping.mapField(), or
 *  FieldMapping literals can be used directly in the TableMapping constructor.
 *  
 */
FieldMapping = {
  fieldName     :  "" ,    /** Name of the field in the domain object 
                               @type String */
  columnName    :  "" ,    /** Column name where this field is stored  
                               @type String */
  persistent    : true,    /** Whether this field should be stored in database.
                               @type Boolean @default true */
  converter     : null,    /** Converter class to use with this field  
                               @type Converter @default null */
  sparseFieldNames: null,  /** sparse field names to store in this column 
                               @type array @default null */
  meta         : undefined /** meta for forward table definition
                               @see Meta for usage
                               @type Meta @default undefined */
};



/** TableMapping constructor 
 *
 *  There are two forms of the TableMapping constructor.
 *  1:  TableMapping(tableName) : Create a new TableMapping for table tableName.
 *      tableName can be in dotted "database.table" form.
 *
 *  2:  TableMapping(tableMappingLiteral) : Create a new TableMapping from 
 *      an existing object or object literal. 
 *
 * @class TableMapping
 * @constructor
 * @param {String} [tableName] 
 * @param {TableMapping} [tableMappingLiteral]
 */
function TableMapping(tableName_or_tableMapping) {};



/*****                      TableMapping methods 
                            --------------------                      *****/
  
/* @method mapField
   mapField(fieldName, [columnName], [converterClass], [persistent])
   IMMEDIATE
   
   Create a fieldMapping for a named field of a mapped object. 
  
   @param fieldName {String}
   The fieldName parameter is mandatory.  It denotes a field in a JavaScript
   application object.

   The other parameters are optional, and may appear in any order.  

   @param columnName {String}
   columnName specifies the name of the database column that maps to this object
   field.  If omitted, it defaults to a column with the same name as the field.

   @param converterClass {Converter}
   converterClass can be used to supply a class to perform custom conversion
   between JavaScript values and database values.  It defaults to null.  If 
   supplied, it must conform to the description of a Converter.

   @param persistent {Boolean=true}
   Persistent specifies whether the field will be persisted to the database.
   It defaults to true.  If persistent is given as false, then the columnName 
   and converterClass parameters may not be supplied.  
   Note that the persistent parameter to mapField() is the inverse of the 
   notPersistent 
   
    @return {TableMapping} @chainable
    mapField() returns the current TableMapping object, so that method
    invocations can be chained.
*/
  function mapField(fieldName, columnName, converterClass, persistent) {};


/* @method applyToClass
   applyToClass(constuctor)
   IMMEDIATE 
   
   Attach a TableMapping to the constructor for mapped objects.
   
   After this is done, any object created from the constructor will qualify
   as a "mapped instance."  With mapped instances, several idiomatic forms 
   of the Session and Batch methods can be used.  For example, an application
   can construct a partially filled-in instance, and then use Session.load() to 
   populate it with all mapped fields from the database.  After the application
   modifies the instance, Session.save() will save it back.   

   Similarly, Session.find() can take the mapped constructor, retrieve an object
   based on keys, and then use the constructor to create a fully-fledged domain
   object.
   
   @param constructor {Function} Constructor of mapped class
   @return TableMapping @chainable
*/
  function applyToClass(constructor) {};


/* This file is a JavaScript module */
exports.FieldMapping = FieldMapping;
exports.TableMapping = TableMapping;