diffusion/src/data/record/schema.js

Diffusion JavaScript client

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

/**
 * Record schema.
 * <P>
 * A schema describes data content in terms of one or more record definitions. A
 * record definition describes the layout of a record and comprises one or more
 * field definitions.
 * <P>
 * Within the data content there can be multiple occurrences of a record or
 * field described by a single definition. The defined (or allowed, when
 * describing variable numbers) number of occurrences of each definition is
 * referred to as its 'multiplicity'. The multiplicity can be fixed (the item
 * occurs a fixed number of times), or variable (the item occurs from a minimum
 * number of times to a maximum number of times). If a variable field is used it
 * must be the last in a record definition and if a variable record is used it
 * must be the last in the schema definition.
 * <P>
 * A field may be defined as of type 'string', 'integer' or 'decimal'. A decimal
 * type has a further property of 'scale' which defines the number of digits to
 * the right of the decimal point.
 *
 * @class diffusion.datatypes.RecordV2.Schema
 * @since 6.0
 */
module.exports = _interface('Schema', [
    /**
     * @typedef Node
     * @property {String} Node.name - the node name
     * @property {Number} Node.min - the minimum number of occurences of the node within its parent
     * @property {Number} Node.max - the maximum number of occurences of the node within its parent
     * @property {Boolean} Node.isVariable - if the node has variable multiplicity, or has fixed multiplicity,
     * i.e min != max
     */

    /**
     * @typedef Record
     * @augments Node
     * @property {Array<Field>} Record.fields - a list of the field definitions. There will be at least one
     */

    /**
     * @typedef Field
     * @augments Node
     * @property {Number} scale - the scale of a decimal field
     */

    /**
     * Returns an immutable, ordered list of record definitions.
     * <P>
     * There will be at least one.
     *
     * @return {Array<diffusion.datatypes.RecordV2.Schema.Record>}
     *  a list of the record definitions in the schema
     * @function diffusion.datatypes.RecordV2.Schema#getRecords
     */
    'getRecords',

    /**
     * Returns the schema in a JSON format
     *
     * @return {Object} schema in JSON format
     * @function diffusion.datatypes.RecordV2.Schema#asJSON
     */
    'asJSON',

    /**
     * Create a mutable model based upon the schema.
     * <P>
     * The model will be created with all mandatory record occurrences and all
     * mandatory field occurrences initialized to default values.
     * <P>
     * Such a model may be mutated and used to generate updated
     * {@link diffusion.datatypes.RecordV2} occurrences for updating purposes.
     *
     * @return {diffusion.datatypes.RecordV2.MutableRecordModel} a new initialized model
     */
    'createMutableModel'
]);