diffusion/src/data/record/mutable-record-model.js

Diffusion JavaScript client

var _interface = require('util/interface')._interface;

/**
 * This is a mutable data model of {@link diffusion.datatypes.RecordV2} data based upon a
 * {@link diffusion.datatypes.RecordV2.Schema}.
 * <P>
 * An initial version of such a model can be created from a schema using the
 * {@link diffusion.datatypes.RecordV2.Schema#createMutableModel()} method. A model created in this way will
 * have all mandatory fields set to default values.
 * <P>
 * The model may then be updated as required and then at any time a
 * {@link diffusion.datatypes.RecordV2} object can be generated from the current state using
 * the {@link diffusion.datatypes.RecordV2.MutableRecordModel#asValue() asValue}
 * method. The {@link diffusion.datatypes.RecordV2} object may then be used to update a
 * topic.
 * <P>
 * When values for integer or decimal type fields are supplied the values are
 * validated and normalized. All number values will have any insignificant
 * leading zeroes removed. A decimal value will also be rounded to its specified
 * scale.
 * <P>
 * All mutator methods return the model so that calls can be chained.
 *
 * @class diffusion.datatypes.RecordV2.MutableRecordModel
 * @since 6.0
 */
module.exports = _interface('RecordModel', [
    /**
     * Get a field value.
     * <P>
     * This allows an item to be addressed using a key of the form
     * recordName(recordIndex).fieldName(fieldIndex). Indexes may be omitted in
     * which case <code>0</code> is assumed.
     *
     * @example
     * // Get field value with record & field names and indices
     * var value = model.get("record", 0, "field", 0);
     *
     * @param {String} recordName - the name of the record
     * @param {Number} [recordIndex=0] - the index of the record
     * @param {String} fieldName - the name of the field
     * @param {Number} [fieldIndex=0] - the index of the field
     * @return {String} the field value
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#get
     */
    'get',

    /**
     * Set a field value.
     * <P>
     * This allows an item to be addressed using a key of the form
     * recordName(recordIndex).fieldName(fieldIndex). Indexes may be omitted in
     * which case <code>0</code> is assumed.
     *
     * @example
     * // Get field value with record & field names and indices
     * var value = model.get("record", 0, "field", 0);
     *
     * @param {String} recordName - the name of the record
     * @param {Number} [recordIndex=0] - the index of the record
     * @param {String} fieldName - the name of the field
     * @param {Number} [fieldIndex=0] - the index of the field
     * @param {String} value - the value to be set
     * @return {diffusion.datatypes.RecordV2.MutableRecordModel} this model
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#set
     */
    'set',

    /**
     * Adds new values to the end of a variable length field list.
     * <P>
     * This can only be used for a variable multiplicity field which can only be
     * the last field in a record and therefore the field does not need to be
     * named.
     * <P>
     * If the record name and index are not supplied, this will add values to the last
     * record in the model. If the model's schema does not specify a variable last field
     * or record, an error will be thrown.
     *
     * @param {String} [recordName] - the name of the record
     * @param {Number} [recordIndex] - the index identifying the occurrence of the record
     * @param {String} values... the values to add
     *
     * @return {diffusion.datatypes.RecordV2.MutableRecordModel} this model
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#add
     */
    'add',

    /**
     * Adds a new initialized record occurrence to the end of a variable
     * multiplicity record list.
     * <P>
     * As the only variable multiplicity record can be the last one there is no
     * need to name the record. This method will add to the list of occurrences
     * of the last defined record. The record will be initialized with default
     * values appropriate to the schema definition and may then have individual
     * field items set separately.
     *
     * @return {diffusion.datatypes.RecordV2.MutableRecordModel} this model
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#addRecord
     */
    'addRecord',

    /**
     * Removes the specified occurrence of a variable multiplicity record.
     * <P>
     * A variable multiplicity record must be the last or only record within a
     * schema and therefore the record name is not required.
     *
     * @param {Number} index - the index of the record to remove
     * @return {diffusion.datatypes.RecordV2.MutableRecordModel} this model
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#removeRecord
     */
    'removeRecord',

    /**
     * Removes the specified occurrence of a variable multiplicity field.
     * <P>
     * A variable multiplicity field must be the last or only field within a
     * record and therefore the field name is not required.
     *
     * @param {String} recordName - the name of the record
     * @param {Number} recordIndex - the record index
     * @param {Number} the index of the field to remove
     * @return {diffusion.datatypes.RecordV2.MutableRecordModel} this model
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#removeField
     */
    'removeField',

    /**
     * Creates an immutable {@link diffusion.datatypes.RecordV2} object generated from the
     * model.
     *
     * @return {diffusion.datatypes.RecordV2} a new immutable instance
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#asRecordV2
     */
    'asValue',

    /**
     * Returns the actual number of occurrences of a named field within a
     * specified record.
     * <P>
     * For all but variable fields this simply returns the schema defined number
     * of occurrences of the field.
     *
     * @param {String} recordName - the record name
     * @param {Number} recordIndex - the record index
     * @param {String} fieldName - the field name
     * @return {Number} the actual number of occurrences of the field
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#fieldCount
     */
    'fieldCount',

    /**
     * Returns the actual number of occurrences of a named record.
     * <P>
     * If the record is not variable, this is the same as the defined number of
     * occurrences in the schema
     *
     * @param {String} recordName - the record name
     * @return {Number} the actual number of occurrences of the record
     * @function diffusion.datatypes.RecordV2.MutableRecordModel#recordCount
     */
    'recordCount'
]);