diffusion
Version:
Diffusion JavaScript client
941 lines (940 loc) • 40.6 kB
JavaScript
;
/**
* @module diffusion.topics
*/
var __assign = (this && this.__assign) || function () {
__assign = Object.assign || function(t) {
for (var s, i = 1, n = arguments.length; i < n; i++) {
s = arguments[i];
for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
t[p] = s[p];
}
return t;
};
return __assign.apply(this, arguments);
};
var __values = (this && this.__values) || function(o) {
var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
if (m) return m.call(o);
if (o && typeof o.length === "number") return {
next: function () {
if (o && i >= o.length) o = void 0;
return { value: o && o[i++], done: !o };
}
};
throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.TopicSpecification = void 0;
var errors_1 = require("./../errors/errors");
/**
* Valid TopicSpecification keys
*/
var keys = [
'PUBLISH_VALUES_ONLY',
'SCHEMA',
'VALIDATE_VALUES',
'TIDY_ON_UNSUBSCRIBE',
'TIME_SERIES_EVENT_VALUE_TYPE',
'TIME_SERIES_RETAINED_RANGE',
'TIME_SERIES_SUBSCRIPTION_RANGE',
'DONT_RETAIN_VALUE',
'PERSISTENT',
'REMOVAL',
'OWNER',
'COMPRESSION',
'CONFLATION',
'PRIORITY'
];
/**
* Topic specifications provide the information required to create a topic.
* Topics can be created from a topic specification using
* {@link TopicControl.add}.
*
* Topic specifications allow an application to introspect the type and
* capabilities of a topic. Topic specifications are provided to
* {@link ValueStream ValueStreams} and {@link TopicNotificationListener topic
* notification listeners}.
*
* A topic is specified in terms of its {@link TopicType type}
* and a map of optional property settings which can alter the default behavior
* of the topic.
*
* A topic specification has a {@link TopicType topic type} and a map of property settings
* which define the behavior of the topic. A default topic specification for a topic
* type can be created using `new diffusion.topics.TopicSpecification(TopicType)`. Topic
* specifications with different properties can be derived from a default instance
* using the {@link TopicSpecification.withProperties} and
* {@link TopicSpecification.withProperty} builder methods.
*
* <h4>Topic Properties</h4>
*
* Depending on the topic type, some properties must be included in the
* specification when creating a topic and some properties have no effect. All
* topic specification property values must be supplied as strings.
*
* The required and optional properties for each topic type are set out in the following table.
* Properties unsupported by the topic type are ignored.
*
* <table style="width: 100%; font-size: 0.7rem">
* <tr>
* <th></th>
* <th>Default when optional</th>
* <th>{@link TopicType.STRING STRING}<br/>
* {@link TopicType.JSON JSON}<br/>
* {@link TopicType.BINARY BINARY}<br/>
* </th>
* <th>{@link TopicType.DOUBLE DOUBLE}<br/>
* {@link TopicType.INT64 INT64}</th>
* <th>{@link TopicType.RECORD_V2 RECORD_V2}</th>
* <th>{@link TopicType.TIME_SERIES TIME_SERIES}</th>
* </tr>
* <tr>
* <th>{@link TopicSpecification.COMPRESSION COMPRESSION}</th>
* <td><code>low</code></td>
* <td>Optional</td>
* <td>-</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.CONFLATION CONFLATION}</th>
* <td><code>conflate</code></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.DONT_RETAIN_VALUE DONT_RETAIN_VALUE}</th>
* <td><code>false</code></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>-</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.OWNER OWNER}</th>
* <td></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.PERSISTENT PERSISTENT}</th>
* <td><code>true</code></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.PRIORITY PRIORITY}</th>
* <td><code>default</code></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.PUBLISH_VALUES_ONLY PUBLISH_VALUES_ONLY}</th>
* <td><code>false</code></td>
* <td>Optional</td>
* <td>-</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.REMOVAL REMOVAL}</th>
* <td></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.SCHEMA SCHEMA}</th>
* <td></td>
* <td>-</td>
* <td>-</td>
* <td>Optional</td>
* <td>-</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.TIDY_ON_UNSUBSCRIBE TIDY_ON_UNSUBSCRIBE}</th>
* <td><code>false</code></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.TIME_SERIES_EVENT_VALUE_TYPE TIME_SERIES_EVENT_VALUE_TYPE}</th>
* <td></td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>Required</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.TIME_SERIES_RETAINED_RANGE TIME_SERIES_RETAINED_RANGE}</th>
* <td><code>limit 10</code></td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.TIME_SERIES_SUBSCRIPTION_RANGE TIME_SERIES_SUBSCRIPTION_RANGE}</th>
* <td>as documented</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link TopicSpecification.VALIDATE_VALUES VALIDATE_VALUES}</th>
* <td><code>false</code></td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* </table>
*
* `TIME_SERIES` topics have restricted values for the
* `CONFLATION` property. They are only allowed to have the values
* `off` or `unsubscribe`.
*/
var TopicSpecification = /** @class */ (function () {
/**
* Create a new TopicSpecification
*
* @param type the topic type for this specification.
* @param properties the properties to use for this specification.
* @since 5.9
*
* **Example:**
*
* Properties can be set when creating the specification by passing an object
* ```
* // Create specification for JSON topics which validate update values on the server
* const TopicSpecification = diffusion.topics.TopicSpecification;
*
* var specification = new TopicSpecification(diffusion.topics.TopicType.JSON, {
* "VALIDATE_VALUES" : "true"
* });
* ```
*
* **Example:** <caption>New specifications can be created with additional properties</caption>
* ```
* // Create specification for JSON topics which validate update values on the server
* const TopicSpecification = diffusion.topics.TopicSpecification;
*
* var specification = new TopicSpecification(diffusion.topics.TopicType.JSON)
* .withProperty(TopicSpecification.VALIDATE_VALUES, "true");
* ```
*/
function TopicSpecification(type, properties) {
if (properties === void 0) { properties = {}; }
this.type = type;
this.properties = properties;
}
/**
* Returns a new TopicSpecification with the specified property set to the supplied value.
* @param key the new property key
* @param value the new property value
* @returns a new TopicSpecification with the specified property set.
*
* @throws an {@link IllegalArgumentError} if the key is not a valid property key.
*/
TopicSpecification.prototype.withProperty = function (key, value) {
var _a;
/* tslint:disable-next-line:strict-type-predicates */
if (typeof key !== 'string' || keys.indexOf(key.toUpperCase()) < 0) {
throw new errors_1.IllegalArgumentError("Invalid key: " + key);
}
/* tslint:disable-next-line:strict-type-predicates */
if (typeof value !== 'string') {
throw new errors_1.IllegalArgumentError("Invalid value, must be string: " + value);
}
var newProperties = __assign(__assign({}, this.properties), (_a = {}, _a[key] = value, _a));
return new TopicSpecification(this.type, newProperties);
};
/**
* Returns a new TopicSpecification with the specified property set to the supplied value.
* @param key the new property key
* @param value the new property value
* @returns a new TopicSpecification with the specified property set.
*
* @throws an {@link IllegalArgumentError} if the key is not a valid property key.
*/
TopicSpecification.prototype.withProperties = function (properties) {
var e_1, _a;
try {
for (var _b = __values(Object.getOwnPropertyNames(properties)), _c = _b.next(); !_c.done; _c = _b.next()) {
var key = _c.value;
/* tslint:disable-next-line:strict-type-predicates */
if (typeof key !== 'string' || keys.indexOf(key.toUpperCase()) < 0) {
throw new errors_1.IllegalArgumentError("Invalid key: " + key);
}
var value = properties[key];
/* tslint:disable-next-line:strict-type-predicates */
if (typeof value !== 'string') {
throw new errors_1.IllegalArgumentError("Invalid value, must be string: " + value);
}
}
}
catch (e_1_1) { e_1 = { error: e_1_1 }; }
finally {
try {
if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
}
finally { if (e_1) throw e_1.error; }
}
var newProperties = __assign(__assign({}, this.properties), properties);
return new TopicSpecification(this.type, newProperties);
};
/**
* Key of the topic property that specifies whether a topic should publish
* only values.
*
* By default, a topic that supports delta streams will publish the
* difference between two values (a delta) when doing so is more efficient
* than publishing the complete new value. Subscribing sessions can use a
* {@link ValueStream} to automatically apply the delta to a local copy of
* the topic value to calculate the new value.
*
* Setting PUBLISH_VALUES_ONLY to `true` disables this behavior so that
* deltas are never published. Doing so is usually not recommended because
* it will result in more data being transmitted, less efficient use of
* network resources, and increased transmission latency. On the other hand,
* calculating deltas can require significant CPU from the server or, if
* update streams are used, from the updating client. The CPU cost will be
* higher if there are many differences between successive values, in which
* case delta streams confer fewer benefits. If successive values are
* unrelated to each other, consider setting PUBLISH_VALUES_ONLY to `true`.
* Also consider setting PUBLISH_VALUES_ONLY to `true` if the network
* capacity is high and the bandwidth savings of deltas are not required.
*
* @see {@link TopicSpecification.DONT_RETAIN_VALUE}
*/
TopicSpecification.PUBLISH_VALUES_ONLY = 'PUBLISH_VALUES_ONLY';
/**
* Key of the topic property that specifies whether a topic should validate
* inbound values.
*
* By default, the server does not validate received values before sending
* them on to client sessions. Invalid or corrupt values will be stored in
* the topic and passed on to sessions. If this property is set to `true`,
* the server will perform additional validation on values to check that
* they are valid instances of the data type, and if it is not then it will
* return an error to the updater and not update the topic.
*
* If this value is not set (or set to something other than `true`), no
* server validation of inbound values is performed. This is the recommended
* setting as there is a performance overhead to validation and values
* produced through the {@link DataTypes data type} API will not
* be invalid anyway.
*/
TopicSpecification.VALIDATE_VALUES = 'VALIDATE_VALUES';
/**
* Key of the topic property that specifies the 'tidy on unsubscribe' option
* for a topic.
*
* By default, if a session unsubscribes from a topic, it will receive any
* updates for that topic that were previously queued but not sent.
*
* If this property is set to `true`, when a session unsubscribes from the
* topic, any updates for the topic that are still queued for the session
* are removed. There is a performance overhead to using this option as the
* client queue must be scanned to find topic updates to remove, however it
* may prove useful for preventing unwanted data being sent to sessions.
*
* @since 6.0
*/
TopicSpecification.TIDY_ON_UNSUBSCRIBE = 'TIDY_ON_UNSUBSCRIBE';
/**
* Key of the topic property that specifies the event data type for a time
* series topic.
*
* The value is the {@link DataType.name type name} of a
* data type.
*
* @since 6.0
*/
TopicSpecification.TIME_SERIES_EVENT_VALUE_TYPE = 'TIME_SERIES_EVENT_VALUE_TYPE';
/**
* Key of the topic property that specifies the range of events retained by
* a time series topic.
*
* When a new event is added to the time series, older events that fall
* outside of the range are discarded.
*
* If the property is not specified, a time series topic will retain the ten
* most recent events.
*
* <h4>Time series range expressions</h4>
*
* The property value is a time series <em>range expression</em> string
* composed of one or more constraint clauses. Constraints are combined to
* provide a range of events from the end of the time series.
*
* <dl>
* <dt>limit constraint
* <dd>A limit constraint specifies the maximum number of events from the
* end of the time series.
* <dt>last clause
* <dd>A last constraint specifies the maximum duration of events from the
* end of the time series. The duration is expressed as an integer followed
* by one of the following time units. <br>
* <br>
* <code>MS</code> – milliseconds; <br>
* <code>S</code> – seconds; <br>
* <code>H</code> – hours.
* </dl>
*
* If a range expression contains multiple constraints, the constraint that
* selects the smallest range is used.
*
* Property value | Meaning
* --------------- | ---------
* `limit 5` | The five most recent events
* `last 10s` | All events that are no more than ten seconds older than the latest event
* `last 10s limit 5` | The five most recent events that are no more than ten seconds older than the latest event
*
* Range expressions are not case sensitive: `limit 5 last 10s` is
* equivalent to `LIMIT 5 LAST 10S`.
*
* @since 6.0
*/
TopicSpecification.TIME_SERIES_RETAINED_RANGE = 'TIME_SERIES_RETAINED_RANGE';
/**
* Key of the topic property that specifies the range of time series topic
* events to send to new subscribers.
*
* The property value is a time series range expression, following the
* format used for {@link TopicSpecification.TIME_SERIES_RETAINED_RANGE
* TIME_SERIES_RETAINED_RANGE}.
*
* If the property is not specified, new subscribers will be sent the latest
* event if delta streams are enabled and no events if delta streams are
* disabled. See the description of <em>Subscription range</em> in the
* {@link TimeSeries time series feature} documentation.
*
* @since 6.0
*/
TopicSpecification.TIME_SERIES_SUBSCRIPTION_RANGE = 'TIME_SERIES_SUBSCRIPTION_RANGE';
/**
* Key of the topic property that specifies a schema which constrains topic
* values.
*
* This property is only used by {@link TopicType.RECORD_V2
* RECORD_V2} topics. The property value can be generated using
* the {@link Schema.asJSON} method of a {@link Schema} created using a
* {@link SchemaBuilder}.
*
* @since 6.0
*/
TopicSpecification.SCHEMA = 'SCHEMA';
/**
* Key of the topic property that specifies a topic should not retain its
* last value.
*
* By default, a topic will retain its latest value. The latest value will
* be sent to new subscribers. Setting this property to `true` disables
* this behavior. New subscribers will not be sent an initial value. No
* value will be returned for fetch operations that select the topic. This
* is useful for data streams where the values are only transiently valid.
*
* Setting DONT_RETAIN_VALUE to `true` also disables delta streams,
* regardless of the {@link TopicSpecification.PUBLISH_VALUES_ONLY
* PUBLISH_VALUES_ONLY} value. If subsequent values are likely to be
* related, delta streams usually provide performance benefits (see {@link
* TopicSpecification.PUBLISH_VALUES_ONLY PUBLISH_VALUES_ONLY}). Consider
* leaving DONT_RETAIN_VALUE set to `false` to benefit from delta streams,
* even if there is no other requirement to retain the last value.
*
* Bearing in mind the performance trade-offs of disabling delta streams,
* there are two reasons to consider setting DONT_RETAIN_VALUE to `true`.
* First, it stops the server and each subscribed client from keeping a copy
* of the value, reducing their memory requirements. Second, when a topic
* has a high update rate and is replicated across a cluster, it can
* significantly improve throughput because the values need not be persisted
* to the cluster.
*
* Time series topics ignore this property and always retain the latest
* value.
*
* @since 6.0
*/
TopicSpecification.DONT_RETAIN_VALUE = 'DONT_RETAIN_VALUE';
/**
* Key of the topic property that can be used to prevent a topic from being
* persisted when the server is configured to enable persistence.
*
* By default, a topic will be persisted if persistence is enabled at the
* server and the topic type supports persistence.
*
* Setting PERSISTENT to `false` will prevent the topic from being
* persisted.
*
* @since 6.1
*/
TopicSpecification.PERSISTENT = 'PERSISTENT';
/**
* Key of the topic property that specifies a removal policy for automatic
* removal of the topic (and/or other topics).
*
* This property is specified as an expression which defines one or more
* conditions that are to be satisfied before automatic removal occurs.
*
* The expression takes the form:
*
* <code>
* when <i>conditions</i> [remove '<i>selector</i>']
* </code>
*
* At least one condition must be supplied. If more than one is supplied,
* they must be separated by logical operators (`and` or `or`).
* The natural evaluation order of the operators may be changed by
* surrounding with parentheses (e.g. (<i>condition</i> `and`
* <i>condition</i>)).
*
* The `remove` clause is optional. It provides a {@link TopicSelector}
* expression representing the topics to be removed. If a `remove` clause is
* specified, the topic with the removal policy will only be removed if its
* path matches the selector expression. The selector must be surrounded by
* either double or single quotes.
*
* When many topics have the same removal policy, it is better to
* set the `REMOVAL` property for one of them, using a `remove`
* clause that selects all of the topics. This is more efficient because it
* allows the server to avoid evaluating the same condition many times.
*
* The permissions that are applied at the time of removal are those defined
* by the roles of the principal that created the topic at the time of
* creation. The roles of that principal may therefore change before the
* removal with no effect, but if the permissions given to the roles change
* it may have an effect upon the final removal.
*
* Only one occurrence of each of the following condition types may be
* included within the expression:
* <table style="width: 100%; font-size:0.9rem;">
* <tr>
* <th align="left" style="width:20%">Condition Type</th>
* <th align="left">Format</th>
* <th align="left">Usage</th>
* </tr>
* <tr valign="top">
* <th align="left" style="width:20%"><b>time after</b></th>
* <td style="width:40%"><code>time after <i>absoluteTime</i></code></td>
* <td style="width:40%">Removal should occur after a specified absolute time. Absolute time
* may be specified as a number of milliseconds since the epoch (00:00:00 on
* 1 January 1970) <b>or</b> as a quoted date and time formatted in <a href=
* "https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#RFC_1123_DATE_TIME">RFC_1123
* date time format</a>. Either single or double quotes may be used.</td>
* </tr>
* <tr valign="top">
* <th align="left" style="width:20%"><b>subscriptions less than</b></th>
* <td style="width:40%"><code>[local] subscriptions < <i>n</i> for <i>forPeriod</i> [after <i>afterPeriod</i>]</code></td>
* <td style="width:40%">Removal should occur when the topic has had less than the specified
* number (<i>n</i>) of subscriptions for a given period (<i>forPeriod</i>)
* of time. Optionally, an initial period (<i>afterPeriod</i>) may be
* specified by which to delay the initial checking of this condition. See
* below for period formats.
* <p>The optional <code>local</code> keyword restricts evaluation to only count
* subscriptions from sessions belonging to the local server or cluster,
* ignoring subscriptions from sessions belonging to downstream remote servers that
* host fanout replicas of the topic.</td>
* </tr>
* <tr valign="top">
* <th align="left" style="width:20%"><b>no updates for</b></th>
* <td style="width:40%"><code>no updates for <i>forPeriod</i> [after <i>afterPeriod</i>]</code></td>
* <td style="width:40%">Removal should occur when the topic has had no updates for a given
* period (<i>forPeriod</i>) of time. Optionally, an initial period
* (<i>afterPeriod</i>) may be specified by which to delay the initial
* checking of this condition. See below for period formats.</td>
* </tr>
* </table>
*
* Multiple occurrences of the following condition types may be
* included within the expression:
* <table style="width: 100%; font-size:0.9rem;">
* <tr>
* <th align="left" style="width:20%">Condition Type</th>
* <th align="left">Format</th>
* <th align="left">Usage</th>
* </tr>
* <tr valign="top">
* <th align="left" style="width:20%"><b>no session has</b></th>
* <td style="width:40%"><code>no [local] session has <i>'criteria'</i> [for <i>forPeriod</i>] [after <i>afterPeriod</i>]</code></td>
* <td style="width:40%">Removal should occur when no sessions satisfy certain <i>criteria</i>.
* Optionally the criteria can be required to be satisfied for a period of time
* (<i>forPeriod</i>). Optionally, an initial period (<i>afterPeriod</i>) can
* be specified to delay the initial check of the criteria. Session selection
* criteria are specified as defined in {@link Session session filters} and
* must be surrounded by single or double quotes. See below for period formats.
* <p>The optional <code>local</code> keyword restricts evaluation to sessions
* belonging to the local server or cluster, ignoring sessions belonging to
* downstream remote servers that host fanout replicas of the topic.</td>
* </tr>
* <tr valign="top">
* <th style="width:20%"></th>
* <td style="width:40%"><code>this session closes</code></td>
* <td style="width:40%">This is a shorthand form of `no local session has` that may be used to
* indicate that the topic is to be removed when the session that created it
* closes.</td>
* </tr>
* </table>
*
* Time periods are specified as a number followed (with no intermediate
* space) by a single letter representing the time unit. The time unit may
* be `s` (seconds), `m` (minutes), `h` (hours) or `d` (days). For example,
* 10 minutes would be specified as 10m.
*
* If quotes or backslashes (`\`) are required within quoted values such as
* selectors or session criteria then they may be escaped by preceding with
* `\`. The convenience method {@link escape} is provided to escape such
* characters in a value. The expression is validated only by the server and
* therefore if an invalid expression is specified it will be reported as an
* Error.
*
* **Examples:**
*
* ```
* when time after 1518780068112
* ```
*
* The topic will be removed when the date and time indicated by the
* specified number of milliseconds since the epoch has passed.
*
* ```
* when time after 'Tue, 3 Jun 2018 11:05:30 GMT'
* ```
*
* The topic will be removed when the specified date and time has passed.
*
* ```
* when time after 'Tue, 3 Jun 2018 11:05:30 GMT' remove '*alpha/beta//'
* ```
*
* The topic alpha/beta and all topics subordinate to it will be removed
* when the specified date and time has passed.
*
* ```
* when subscriptions < 1 for 20m
* ```
*
* The topic will be removed when it has had no subscriptions for a
* continuous period of 20 minutes.
*
* ```
* when subscriptions < 2 for 20m after 1h
* ```
*
* The topic will be removed when it has had less than 2 subscriptions for a
* continuous period of 20 minutes after one hour has passed since its
* creation.
*
* ```
* when no updates for 3h
* ```
*
* The topic will be removed when it has had no updates for a continuous
* period of 3 hours.
*
* ```
* when no updates for 15m after 1d
* ```
*
* The topic will be removed when it has had no updates for a continuous
* period of 15 minutes after one day has passed since its creation.
*
* ```
* when this session closes
* ```
*
* The topic will be removed when the session that created it closes.
*
* ```
* when no session has '$Principal is "Alice"'
* ```
*
* The topic will be removed when there is no session with the principal 'Alice'.
*
* ```
* when no session has '$Principal is "Alice"' for 10m
* ```
*
* The topic will be removed when there are no sessions with the principal
* 'Alice' for a continuous period of 10 minutes.
*
* ```
* when no session has 'Department is "Accounts"' for 30m after 2h
* ```
*
* The topic will be removed when there have been no sessions from the Account
* department for a continuous period of 30 minutes after 2 hours have passed
* since its creation.
*
* ```
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" and subscriptions < 1 for 30m
* ```
*
* The topic will be removed when the specified date and time has passed and
* the topic has had no subscriptions for a continuous period of 30 minutes
* after that time.
*
* ```
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" and subscriptions < 2 for 10m after 1h
* ```
*
* The topic will be removed when the specified date and time has passed and
* the topic has had less than 2 subscriptions for a continuous period of 10
* minutes after that time plus one hour.
*
* ```
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" or subscriptions < 2 for 10m after 1h
* ```
*
* The topic will be removed when the specified date and time has passed or
* the topic has had less than 2 subscriptions for a continuous period of 10
* minutes after one hour from its creation.
*
* ```
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" and (subscriptions < 2 for 10m after 1h or no updates for 20m)
* ```
*
* The topic will be removed when the specified date and time has passed and
* either the topic has had less than 2 subscriptions for a continuous
* period of 10 minutes after that time plus one hour or it has had no
* updates for a continuous period of 20 minutes. Note that the parentheses
* are significant here as without them the topic would be removed if it had
* had no updates for 20 minutes regardless of the time and subscriptions
* clause.
*
* **Notes and restrictions on use**
*
* The `after` time periods refer to the period since the topic was
* created or restored from persistence store after a server is restarted.
* They are designed as a 'grace' period after the topic comes into
* existence before the related conditions starts to be evaluated. When not
* specified the conditions start to be evaluated as soon as the topic is
* created or restored.
*
* The server will evaluate conditions on a periodic basis (every few
* seconds) so the exact removal time will not be precise for low periodic
* granularity.
*
* The meaning of the `for` period in a `no session has` condition is subtly
* different from its use in other conditions. It does not guarantee that
* there has been no session satisfying the condition at some point between
* evaluations, only that when evaluated the given period of time has passed
* since it was last evaluated and found to have no matching sessions.
*
* Subscriptions is the number of subscriptions to a topic.
*
* Automatic topic removal is supported for a topic that is replicated
* across the local cluster, and for a topic with with fanout replicas on
* downstream remote servers. A `subscriptions less than` condition will be evaluated
* against the total number of subscriptions across the cluster and on all
* fanout replicas on downstream remote servers. A `no session has`
* condition will consider all sessions hosted across the cluster and all
* sessions hosted by downstream remote servers that have a fanout replica
* of the topic. The `local` keyword can be used to restrict evaluation to
* the local cluster, ignoring fanout replicas.
*
* @since 6.1
*/
TopicSpecification.REMOVAL = 'REMOVAL';
/**
* Key of the topic property that specifies the conflation policy of the
* topic. The policy specifies how the server manages queued topic updates.
* Conflation is applied individually to each session queue.
*
* Conflation is the process of merging or discarding topic updates queued
* for a session to reduce the server memory footprint and network data. The
* server will conflate sessions that have a large number of queued messages
* to meet configured queue size targets. The sessions with the largest
* queues are typically slow consumers or have been disconnected - both will
* benefit from conflation. This property allows conflation behavior to be
* tuned on a topic-by-topic basis.
*
* The supported policies are:
*
* * `off`
* * `conflate`
* * `unsubscribe`
* * `always`
*
* The default policy used when the property is not specified and the topic
* type is not time series is `conflate`. The default policy used when the
* property is not specified and the topic type is time series is `off`.
*
* The policy `off` disables conflation for the topic. This policy
* disables all conflation for the topic, so topic updates will never be
* merged or discarded.
*
* The policy `conflate` automatically conflates topic updates when
* back pressure is detected by the server.
*
* The policy `unsubscribe` automatically unsubscribes the topic when
* back pressure is detected by the server. The unsubscription is not
* persisted to the cluster. If a session fails over to a different server
* it will be resubscribed to the topic.
*
* The policy `always` automatically conflates topic updates as they
* are queued for the session. This is an eager policy that ensures only the
* latest update is queued for the topic, minimising the server memory and
* network bandwidth used by the session.
*
* The `conflate` and `unsubscribe` policies are applied when
* the server detects back pressure for a session. The server configuration
* places limits on the data queued for each session. If these limits are
* breached, the server will conflate the session queue to attempt to reduce
* its size. If the session queue still exceeds the limits after conflation,
* the session will be terminated.
*
* Conflation can be disabled on a session-by-session basis. If conflation is
* disabled for a session the policy will not be applied to topic updates
* queued for the session but will be for other sessions that have conflation
* enabled.
*
* The policies `conflate` and `always` are not supported for
* time series topics as they would cause missing events. Attempts to enable
* these policies with time series topics will cause the creation of the
* topic to fail, reporting that the specification is invalid.
*
* @since 6.2
*/
TopicSpecification.CONFLATION = 'CONFLATION';
/**
* Key of the topic property that allows the creator of a topic to extend
* READ_TOPIC, MODIFY_TOPIC, and UPDATE_TOPIC permissions to a specific
* principal, in addition to the permissions granted by the authorisation
* rules in the security store.
*
* A session that has authenticated using the principal can update and
* remove the topic, so the principal can be considered the topic owner. To
* fetch or subscribe to the topic, the principal must also be granted
* the SELECT_TOPIC permission by the security store rules.
*
* This may be used in the following cases:
* 1) A session creates a topic and makes its own principal the owner.
* 2) A session creates a topic and makes another principal the owner.
*
* The format of the property value is:
*
* `$Principal is "<i>name</i>"`
*
* where <i>name</i> is the name of the principal. Single quotes may be used
* instead of double quotes and special characters can be escaped using
* {@link escape} if required.
*
* The purpose of this property is to allow a client to create topics on
* behalf of other users. This can be used in conjunction with the
* {@link REMOVAL} property so that such topics are removed when there are
* no longer any sessions for the named principal.
*
* **Example:**
* ```
* specification.withProperty(diffusion.topics.TopicSpecification.OWNER,
* "$Principal is 'myPrincipal'")
* .withProperty(diffusion.topics.TopicSpecification.REMOVAL,
* "when no session has '$Principal is \"myPrincipal\"' for 5s");
* ```
*
* @since 6.1
*/
TopicSpecification.OWNER = 'OWNER';
/**
* Key of the topic property that allows the compression policy to be set
* on a per-topic basis.
*
* Compression reduces the bandwidth required to broadcast topic updates to
* subscribed sessions, at the cost of increased server CPU.
*
* Changes to a topic's value are published to each subscribed session as a
* sequence of topic messages. A topic message can carry the latest value or
* the difference between the latest value and the previous value (a delta).
* The compression policy determines if and how published topic messages
* are compressed. Topic messages are not exposed through the client API;
* the client library handles decompression and decodes deltas
* automatically, passing reconstructed values to the application.
*
* The compression policy for a topic is specified by setting this property
* to one of several values:
*
* * `off`
* * `low`
* * `medium`
* * `high`
*
* The policies are listed in the order of increasing compression and
* increasing CPU cost. `off` disables compression completely for the
* topic and requires no additional CPU; `high` compresses the topic
* messages to the smallest number of bytes, but has the highest CPU cost.
* Generally some compression is beneficial, so the default value for this
* property is `low`.
*
* Prior to version 6.4, only two values were allowed: `true`
* (equivalent to `medium`, and the previous default policy) and
* `false` (equivalent to `off`). These values are still
* supported.
*
* This property is only one factor that determines whether a topic message
* will be compressed. Other factors include:
*
* * Compression must be enabled in the server configuration.
*
* * The client library must support the server's compression
* scheme. In this release, the server supports zlib
* compression, and also allows compression to be disabled on a
* per-connector basis. From 6.4, all client libraries are
* capable of zlib compression. A JavaScript client may or may
* not support zlib compression, depending on whether the zlib
* library can be loaded. The zlib library is packaged
* separately to reduce the download size of the core library.
*
* @since 6.2
*/
TopicSpecification.COMPRESSION = 'COMPRESSION';
/**
* Key of the topic property that specifies the topic delivery priority.
*
* The supported delivery priorities are:
*
* * `low`
* * `default`
* * `high`
*
* The delivery priority affects the order of topic updates sent to a
* subscribed client session. When there are multiple topic updates for
* topics with different priorities in a session's outbound queue, updates
* for `high` priority topics will be delivered first, followed by
* updates for `default` priority topics, followed by updates for
* `low` priority topics. Topic subscription and unsubscription
* notifications are also delivered according to the topic delivery
* priority.
*
* Using different delivery priorities is most beneficial when there is a
* large backlog of queued updates to deliver to a client session. On
* lightly loaded systems, updates typically remain in the outbound queue
* for a few milliseconds and so there is a lower chance of topic updates
* being reordered based on their priority. The backlog will be larger if
* the topic update rate is higher; the server or the client are more
* heavily loaded; the client session becomes temporarily disconnected; or
* if there is poor network connectivity between the server and the client.
*
* Messages from the server to the client that are not topic updates, for
* example ping requests and responses, are queued with the
* `default` delivery priority.
*
* @since 6.4
*/
TopicSpecification.PRIORITY = 'PRIORITY';
return TopicSpecification;
}());
exports.TopicSpecification = TopicSpecification;