diffusion/src/data/record/schema-builder.js

Diffusion JavaScript client

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

/**
 * Used to build an immutable {@link diffusion.datatypes.RecordV2.Schema}.
 * <P>
 * A schema defines the records and fields that may occur on record-based topic
 * content.
 * <P>
 * The schema must declare at least one record type and every record must have
 * at least one field type declared.
 * <P>
 * Every record type and field type has a 'multiplicity' which defines the
 * number of times that the record or field may occur within the data.
 * Multiplicity is specified as a 'minimum' and 'maximum' number of occurrences
 * or where the minimum and maximum are the same (fixed multiplicity) then the
 * multiplicity may be specified as a single 'occurs' value. If the minimum and
 * maximum are different, this is referred to a 'variable' multiplicity. Only
 * the last record declared or the last field within a record may have variable
 * multiplicity. The maximum value may be declared as -1 to indicate that the
 * record or field can have an unlimited number of occurrences.
 * <P>
 * The builder is used to add a record definition followed by the fields within
 * it. After all fields have been added to a record another may then be added,
 * and so on, and then finally {@link diffusion.datatypes.RecordV2.SchemaBuilder#build() #build()} is called to create
 * an immutable
 * schema object.
 * <P>
 * Every call returns the builder instance allowing calls to be chained, for
 * example:
 *
 * <pre>
 * const schema = builder.record(&quot;R1&quot;).string(&quot;S1&quot;).string(&quot;S2&quot;, 1, 5)
 *     .record(&quot;R2&quot;, 0, -1).decimal(&quot;D&quot;, 5).build();
 * </pre>
 *
 * A builder is obtained using the
 * {@link diffusion.datatypes.RecordV2DataType#schemaBuilder()} method.
 *
 * @class diffusion.datatypes.RecordV2.SchemaBuilder
 * @since 6.0
 */
module.exports = _interface('SchemaBuilder', [
    /**
     * Add a new record to the schema
     * <P>
     * The record added must not have the same name as a previously added record.
     * <P>
     * A record may not be added after a record that has variable multiplicity (min != max)
     * <P>
     * A record may not be added directly after another record which has had no fields added.
     *
     * @param {String} name - record name. This must not the same as any record already added
     * @param {Number} [min=1] - the minimum number of times the record should occur within the schema
     * @param {Number} [max=1] - the maximum number of times the record should occur within the schema.
     * May be either <code>-1</code> (indicating no upper limit) or a positive value that is not less than
     * <code>min</code>
     *
     * @function diffusion.datatypes.RecordV2.SchemaBuilder#record
     */
    'record',

    /**
     * Add a string field to the current record.
     * <P>
     * A field may not be added after a field that has variable multiplicity (min != max)
     *
     * @param {String} name - field name. This must not the same as any field already added
     * @param {Number} [min=1] - the minimum number of times the field should occur within the record
     * @param {Number} [max=1] - the maximum number of times the field should occur within the record.
     * May be either <code>-1</code> (indicating no upper limit) or a positive value that is not less than
     * <code>min</code>
     *
     * @function diffusion.datatypes.RecordV2.SchemaBuilder#string
     */
    'string',

    /**
     * Add an integer field to the current record.
     * <P>
     * A field may not be added after a field that has variable multiplicity (min != max)
     *
     * @param {String} name - field name. This must not the same as any field already added
     * @param {Number} [min=1] - the minimum number of times the field should occur within the record
     * @param {Number} [max=1] - the maximum number of times the field should occur within the record.
     * May be either <code>-1</code> (indicating no upper limit) or a positive value that is not less than
     * <code>min</code>
     *
     * @function diffusion.datatypes.RecordV2.SchemaBuilder#integer
     */
    'integer',

    /**
     * Add a decimal field to the current record.
     * <P>
     * A field may not be added after a field that has variable multiplicity (min != max)
     *
     * @param {String} name - field name. This must not the same as any field already added
     * @param {Number} scale - the scale of the field (number of decimal places). This must be positive.
     * @param {Number} [min=1] - the minimum number of times the field should occur within the record
     * @param {Number} [max=1] - the maximum number of times the field should occur within the record.
     * May be either <code>-1</code> (indicating no upper limit) or a positive value that is not less than
     * <code>min</code>
     *
     * @function diffusion.datatypes.RecordV2.SchemaBuilder#decimal
     */
    'decimal',

    /**
     * Build an immutable Schema.
     * <P>
     * At least one record with at least one field must have been added to the
     * builder.
     *
     * @return {diffusion.datatypes.RecordV2.Schema} a new immutable schema object representing the current state of
     *         the builder
     * @function diffusion.datatypes.RecordV2.SchemaBuilder#build
     */
    'build'
]);