TableMapping

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

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