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

Diffusion JavaScript client

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

/**
 * {@link diffusion.datatypes.RecordV2} data model.
 * <P>
 * A read only model can be created from any {@link diffusion.datatypes.RecordV2} object
 * using the {@link diffusion.datatypes.RecordV2#asModel asModel} method. The model
 * then provides direct access to the fields within the data. Fields may be
 * accessed either by explicitly specifying the record and field occurrence or
 * by specifying a key of the form:
 *
 * <pre>
 * recordName(recordIndex).fieldName(fieldIndex)
 * </pre>
 *
 * Indexes start from 0 and if omitted then 0 is assumed. The record name may
 * also be omitted, in which case the first record definition. This form of
 * addressing is useful when there is only one record definition.
 * <P>
 * So valid keys would be: <table border summary="">
 * <tr>
 * <td><code>Address(4).AddressLine(3)</code></td>
 * <td>The 4th <code>AddressLine</code> occurrence within the 5th
 * <code>Address</code> record</td>
 * </tr>
 * <tr>
 * <td><code>Address.Name</code></td>
 * <td>The first (or only) <code>Name</code> field within the first (or only)
 * <code>Address</code> record</td>
 * </tr>
 * <tr>
 * <td><code>AddressLine(1)</code></td>
 * <td>The 2nd <code>AddressLine</code> field within the first (or only) record
 * </td>
 * </tr>
 * <tr>
 * <td><code>Name</code></td>
 * <td>The first (or only) <code>Name</code> field within the first (or only)
 * record</td>
 * </tr>
 * </table>
 * <P>
 * The {@link diffusion.datatypes.RecordV2.RecordModel#recordCount} and
 * {@link diffusion.datatypes.RecordV2.RecordModel#fieldCount} methods are useful for
 * determining the actual number of occurrences of variable multiplicity items.
 *
 * @class diffusion.datatypes.RecordV2.RecordModel
 * @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.RecordModel#get
     */
    'get',

    /**
     * Creates an immutable {@link diffusion.datatypes.RecordV2} object generated from the
     * model.
     *
     * @return {diffusion.datatypes.RecordV2} a new immutable instance
     * @function diffusion.datatypes.RecordV2.RecordModel#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.RecordModel#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.RecordModel#recordCount
     */
    'recordCount'
]);