diffusion
Version:
Diffusion JavaScript client
890 lines (864 loc) • 34.5 kB
JavaScript
// Valid TopicSpecification keys
var keys = [
"PUBLISH_VALUES_ONLY",
"SCHEMA",
"VALIDATE_VALUES",
"SLAVE_MASTER_TOPIC",
"TIDY_ON_UNSUBSCRIBE",
"TIME_SERIES_EVENT_VALUE_TYPE",
"TIME_SERIES_RETAINED_RANGE",
"TIME_SERIES_SUBSCRIPTION_RANGE",
"DONT_RETAIN_VALUE",
"PERSISTENT",
"REMOVAL",
"OWNER",
"COMPRESSION",
"CONFLATION"
];
/**
* Topic specifications provide the information required to create a topic.
* Topics can be created from a topic specification using
* {@link Session.topics#add}.
*
* <p>
* 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}.
*
* <P>
* A topic is specified in terms of its {@link diffusion.topics.TopicType type} and a map of
* optional property settings which can alter the default behavior of the topic.
* <P>
* <h4>Topic Properties</h4>
* <p>
* 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.
* <P>
* The required and optional properties for each topic type are set out in the following table.
* <p>
* <table style="width: 100%">
* <tr>
* <th></th>
* <th>{@link diffusion.topics.TopicType.STRING STRING}<br/>
* {@link diffusion.topics.TopicType.JSON JSON}<br/>
* {@link diffusion.topics.TopicType.BINARY BINARY}<br/>
* </th>
* <th>{@link diffusion.topics.TopicType.DOUBLE DOUBLE}<br/>
* {@link diffusion.topics.TopicType.INT64 INT64}</th>
* <th>{@link diffusion.topics.TopicType.ROUTING ROUTING}<br/>
* <th>{@link diffusion.topics.TopicType.SLAVE SLAVE}</th>
* <th>{@link diffusion.topics.TopicType.TIME_SERIES TIME_SERIES}</th>
* <th>{@link diffusion.topics.TopicType.RECORD_V2 RECORD_V2}</th>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.COMPRESSION COMPRESSION}</th>
* <td>Optional</td>
* <td>-</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.CONFLATION CONFLATION}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.DONT_RETAIN_VALUE DONT_RETAIN_VALUE}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.PUBLISH_VALUES_ONLY PUBLISH_VALUES_ONLY}</th>
* <td>Optional</td>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.SCHEMA SCHEMA}</th>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.SLAVE_MASTER_TOPIC SLAVE_MASTER_TOPIC}</th>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>Required</td>
* <td>—</td>
* <td>—</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.TIDY_ON_UNSUBSCRIBE TIDY_ON_UNSUBSCRIBE}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.TIME_SERIES_EVENT_VALUE_TYPE TIME_SERIES_EVENT_VALUE_TYPE}</th>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>Required</td>
* <td>—</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.TIME_SERIES_RETAINED_RANGE TIME_SERIES_RETAINED_RANGE}</th>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>—</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.TIME_SERIES_SUBSCRIPTION_RANGE TIME_SERIES_SUBSCRIPTION_RANGE}</th>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.VALIDATE_VALUES VALIDATE_VALUES}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>—</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.PERSISTENT PERSISTENT}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>—</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.REMOVAL REMOVAL}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>—</td>
* </tr>
* <tr>
* <th>{@link diffusion.topics.TopicSpecification.OWNER OWNER}</th>
* <td>Optional</td>
* <td>Optional</td>
* <td>—</td>
* <td>—</td>
* <td>Optional</td>
* <td>—</td>
* </tr>
* </table>
* <p>
* <p>
*
* ‡ Prefer the {@link diffusion.topics.TopicType.RECORD_V2 RECORD_V2} topic type
* for Diffusion record data since it provides full support for topic
* specifications.
*
* @class TopicSpecification
* @param {diffusion.topics.TopicType} type - The topic type for this specification.
* @param {Object} [properties={}] - The properties to use for this specification.
* @memberOf diffusion.topics
* @alias TopicSpecification
* @since 5.9
*
* @example <caption>Properties can be set when creating the specification by passing an object</caption>
* // Create specification, to be used for creating 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, to be used for creating 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");
*/
module.exports = function TopicSpecification(type, properties) {
/**
* @property {diffusion.topics.TopicType} type - The topic type.
*/
this.type = type;
/**
* @property {Object} properties - A map of the topic properties.
*/
this.properties = properties || {};
/**
* Returns a new TopicSpecification with the specified property set to the supplied value.
* @param {String} key - The new property key
* @param {String} value - The new property value
* @returns {diffusion.topics.TopicSpecification} A new TopicSpecification with the specified property set.
* @function diffusion.topics.TopicSpecification#withProperty
*/
this.withProperty = function(key, value) {
if (typeof key !== 'string' || keys.indexOf(key.toUpperCase()) < 0) {
throw new Error("Invalid key: " + key);
}
if (typeof value !== 'string') {
throw new Error('Invalid value, must be string: ' + value);
}
var newProperties = {};
newProperties[key] = value;
for (var k in this.properties) {
if (k !== key) {
newProperties[k] = this.properties[k];
}
}
return new TopicSpecification(this.type, newProperties);
};
this.equals = function(other) {
if (other && type === other.type && Object.keys(properties).length === Object.keys(other.properties).length) {
for (var k in properties) {
if (other.properties[k] !== properties[k]) {
return false;
}
}
return true;
}
return false;
};
};
/**
* Key of the topic property that specifies whether a topic should publish
* only values.
* <P>
* By default, a topic that supports delta streams will publish the
* difference between two values (a delta) when doing so is more efficient
* than to 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. If a session
* uses a {@link Subscription subscription}, it must process the deltas
* manually using the {@link diffusion.datatypes data type} API.
*
* <p>
* Setting PUBLISH_VALUES_ONLY to <code>"true"</code> disables this behavior so that
* deltas are never published. Doing so is not recommended because it will
* result in more data being transmitted and less efficient use of network
* resources. Reasons to consider setting the value to "true" include
* compatibility with older client libraries that do not support delta
* streams; to simplify applications that use topic streams and do not wish
* to deal with the complexities of delta processing (it would be better for
* such an application to use a {@link ValueStream}); and to disable
* delta streams to investigate their performance benefits.
*
* @memberof diffusion.topics.TopicSpecification
* @alias PUBLISH_VALUES_ONLY
*/
module.exports.PUBLISH_VALUES_ONLY = "PUBLISH_VALUES_ONLY";
/**
* Key of the topic property indicating whether a topic should validate
* inbound values.
* <P>
* 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 <code>"true"</code>,
* 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.
* <P>
* If this value is not set (or set to something other than <code>"true"</code>), 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 diffusion.datatypes data type} API will not be invalid anyway.
*
* @memberof diffusion.topics.TopicSpecification
* @alias VALIDATE_VALUES
*/
module.exports.VALIDATE_VALUES = "VALIDATE_VALUES";
/**
* Key of the topic property that specifies the master topic path for a
* {@link diffusion.topics.TopicType.SLAVE slave} topic.
* <P>
* When creating a slave topic using a topic specification then this must be
* specified. For all other topic types it is ignored.
*
* @memberof diffusion.topics.TopicSpecification
* @alias SLAVE_MASTER_TOPIC
* @since 6.0
*/
module.exports.SLAVE_MASTER_TOPIC = "SLAVE_MASTER_TOPIC";
/**
* Key of the topic property that specifies the 'tidy on unsubscribe' option
* for a topic.
* <P>
* By default, if a session unsubscribes from a topic, it will receive any
* updates for that topic that were previously queued but not sent.
* <P>
* If this property is set to <code>"true"</code>, 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.
*
* @memberof diffusion.topics.TopicSpecification
* @alias TIDY_ON_UNSUBSCRIBE
* @since 6.0
*/
module.exports.TIDY_ON_UNSUBSCRIBE = "TIDY_ON_UNSUBSCRIBE";
/**
* Key of the topic property that specifies the event data type for a time
* series topic.
*
* <p>
* The value is the {@link diffusion.datatypes.DataType#name type name} of a data type.
*
* @memberof diffusion.topics.TopicSpecification
* @alias TIME_SERIES_EVENT_VALUE_TYPE
* @since 6.0
*/
module.exports.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.
*
* <p>
* When a new event is added to the time series, older events that fall
* outside of the range are discarded.
*
* <p>
* If the property is not specified, a time series topic will retain the ten
* most recent events.
*
* <h4>Time series range expressions</h4>
*
* <p>
* 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>
*
* <p>
* If a range expression contains multiple constraints, the constraint that
* selects the smallest range is used.
*
* <table>
* <tr>
* <th>Property value</th>
* <th>Meaning</th>
* </tr>
* <tr>
* <td><code>limit 5</code></td>
* <td>The five most recent events</td>
* </tr>
* <tr>
* <td><code>last 10s</code></td>
* <td>All events that are no more than ten seconds older than the latest
* event</td>
* </tr>
* <tr>
* <td><code>last 10s limit 5</code></td>
* <td>The five most recent events that are no more than ten seconds older
* than the latest event</td>
* </tr>
* </table>
*
* <p>
* Range expressions are not case sensitive: <code>limit 5 last 10s</code> is
* equivalent to <code>LIMIT 5 LAST 10S</code>.
*
* @memberof diffusion.topics.TopicSpecification
* @alias TIME_SERIES_RETAINED_RANGE
* @since 6.0
*/
module.exports.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.
*
* <p>
* The property value is a time series range expression, following the
* format used for {@link diffusion.topics.TopicSpecification.TIME_SERIES_RETAINED_RANGE TIME_SERIES_RETAINED_RANGE}.
*
* <p>
* 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 session.timeseries time series feature} documentation.
*
* @memberof diffusion.topics.TopicSpecification
* @alias TIME_SERIES_SUBSCRIPTION_RANGE
* @since 6.0
*/
module.exports.TIME_SERIES_SUBSCRIPTION_RANGE = "TIME_SERIES_SUBSCRIPTION_RANGE";
/**
* Key of the topic property that specifies a schema which constrains topic
* values.
*
* <p>
* This property is only used by {@link diffusion.topics.TopicType#RECORD_V2 RECORD_V2} topics. The value is converted
* to a Diffusion record schema using {@link diffusion.datatypes.RecordV2DataType#parseSchema}.
*
* @memberof diffusion.topics.TopicSpecification
* @alias SCHEMA
* @since 6.0
*/
module.exports.SCHEMA = "SCHEMA";
/**
* Key of the topic property that specifies a topic should not retain
* its last value. Setting this property to "true" allows the topic to behave
* like a stateless topic, while retaining other properties such as its data
* type.
*
* <p> By default, a topic (other than a <code>SLAVE</code>, or
* <code>ROUTING</code> 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.
*
* <p>
* Setting DONT_RETAIN_VALUE to "true" disables delta streams,
* regardless of the {@link
* diffusion.topics.TopicSpecification.PUBLISH_VALUES_ONLY
* PUBLISH_VALUES_ONLY} value. If subsequent values are likely to be
* related, delta streams can provide a performance benefit. Consider
* not setting this property to benefit from delta streams, even if
* there is no other requirement to retain the last value.
*
* <p>
* Setting this property affects the default subscription range of a time
* series topic. If set to "true", the default subscription range will
* not provide an initial event to new subscribers. The default
* subscription range can be overridden with the {@link
* diffusion.topics.TopicSpecification.TIME_SERIES_SUBSCRIPTION_RANGE
* TIME_SERIES_SUBSCRIPTION_RANGE} property. Regardless of whether
* DONT_RETAIN_VALUE is set, a time series topic will continue to
* record events according to the {@link
* diffusion.topics.TopicSpecification.TIME_SERIES_RETAINED_RANGE
* TIME_SERIES_RETAINED_RANGE} property.
*
* @memberof diffusion.topics.TopicSpecification
* @alias DONT_RETAIN_VALUE
* @since 6.0
*/
module.exports.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.
* <P>
* By default, a topic will be persisted if persistence is enabled at the
* server and the topic type supports persistence.
* <p>
* Setting PERSISTENT to "false" will prevent the topic from being
* persisted.
*
* @memberof diffusion.topics.TopicSpecification
* @alias PERSISTENT
* @since 6.1
*/
module.exports.PERSISTENT = "PERSISTENT";
/**
* Key of the topic property that specifies a removal policy for automatic
* removal of the topic (and/or other topics).
* <p>
* This property is specified as an expression which defines one or more
* conditions that are to be satisfied before automatic removal occurs.
* <p>
* The expression takes the form:-
* <p>
* <code>
* when <i>conditions</i> [remove "<i>selector</i>"]
* </code>
* <p>
* At least one condition must be supplied. If more than one is supplied,
* they must be separated by logical operators (<code> and</code> or <code> or</code>).
* The natural evaluation order of the operators may be changed by
* surrounding with parentheses (e.g. (<i>condition</i> <code> and</code>
* <i>condition</i>)).
* <p>
* The <code> remove</code> clause is optional. It provides a
* {@link TopicSelector} expression representing the topics to be removed.
* If a <code> remove</code> 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.
* <p>
* 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.
* <p>
* Only one occurrence of each of the following condition types may be
* included within the expression:-
* <table>
* <tr>
* <th align="left">Condition Type</th>
* <th align="left">Format</th>
* <th align="left">Usage</th>
* </tr>
* <tr valign="top">
* <th align="left"><b>time after</b></th>
* <td><code>time after <i>absoluteTime</i></code></td>
* <td>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"><b>subscriptions less than</b></th>
* <td><code>subscriptions < <i>n</i> for <i>forPeriod</i> [after <i>afterPeriod</i>]</code></td>
* <td>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.</td>
* </tr>
* <tr valign="top">
* <th align="left"><b>no updates for</b></th>
* <td><code>no updates for <i>forPeriod</i> [after <i>afterPeriod</i>]</code></td>
* <td>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>
* <tr valign="top">
* <th align="left"><b>no session has</b></th>
* <td><code>no session has <i>"criteria"</i> [for <i>forPeriod</i>] [after <i>afterPeriod</i>]</code></td>
* <td>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.</td>
* </tr>
* <tr valign="top">
* <th></th>
* <td><code>this session closes</code></td>
* <td>This is a shorthand form of 'no 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.
* <p>
* 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 Diffusion#escape(String)} 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 {@link InvalidTopicSpecificationException}.
* <p>
* <b>Examples:</b>
* <p>
* <code>
* when time after 1518780068112
* </code><br>
* The topic will be removed when the date and time indicated by the
* specified number of milliseconds since the epoch has passed.
* <p>
* <code>
* when time after "Tue, 3 Jun 2018 11:05:30 GMT"
* </code><br>
* The topic will be removed when the specified date and time has passed.
* <p>
* <code>
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" remove "*alpha/beta//"
* </code><br>
* The topic alpha/beta and all topics subordinate to it will be removed
* when the specified date and time has passed.
* <p>
* <code>
* when subscriptions < 1 for 20m
* </code><br>
* The topic will be removed when it has had no subscriptions for a
* continuous period of 20 minutes.
* <p>
* <code>
* when subscriptions < 2 for 20m after 1h
* </code><br>
* 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.
* <p>
* <code>
* when no updates for 3h
* </code><br>
* The topic will be removed when it has had no updates for a continuous
* period of 3 hours.
* <p>
* <code>
* when no updates for 15m after 1d
* </code><br>
* 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.
* <p>
* <code>
* when this session closes
* </code><br>
* The topic will be removed when the session that created it closes.
* <p>
* <code>
* when no session has '$Principal is "Alice"'
* </code><br>
* The topic will be removed when there is no session with the principal 'Alice'.
* <p>
* <code>
* when no session has '$Principal is "Alice"' for 10m
* </code><br>
* The topic will be removed when there have been no sessions with the principal
* 'Alice' for a continuous period of 10 minutes.
* <p>
* <code>
* when no session has 'Department is "Accounts"' for 30m after 2h
* </code><br>
* 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.
* <p>
* <code>
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" and subscriptions < 1 for 30m
* </code><br>
* 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.
* <p>
* <code>
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" and subscriptions < 2 for 10m after 1h
* </code><br>
* 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.
* <p>
* <code>
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" or subscriptions < 2 for 10m after 1h
* </code><br>
* 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.
* <p>
* <code>
* when time after "Tue, 3 Jun 2018 11:05:30 GMT" and (subscriptions < 2 for 10m after 1h or no updates for 20m)
* </code><br>
* 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.
* <p>
* <b>Notes and restrictions on use</b>
* <p>
* The <code> after</code> 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.
* <p>
* 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.
* <p>
* The meaning of the <code> for</code> period on <code> no session has</code>
* conditions is subtly different from on 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.
* <p>
* Automatic topic removal is supported for replicated topics. A 'subscriptions
* less than' condition for a replicated topic will be evaluated against the
* total number of subscriptions to the topic across the cluster. A 'no session
* has' condition will consider all sessions hosted across the cluster.
* <p>
* The 'subscriptions less than' condition does not count indirect subscriptions
* to a topic from sessions hosted on a secondary server connected using fan-out.
* Similarly the 'no session has' condition does not count sessions on secondary
* servers connected using fan-out.
*
* @memberof diffusion.topics.TopicSpecification
* @alias REMOVAL
* @since 6.1
*/
module.exports.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.
* <p>
* 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.
* <p>
* The supported policies are:
* <ul>
* <li>`off`</li>
* <li>`conflate`</li>
* <li>`unsubscribe`</li>
* <li>`always`</li>
* </ul>
* The default policy used when the property is not specified is
* `conflate`.
* <p>
* 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.
* <p>
* The policy `conflate` automatically conflates topic updates when
* back pressure is detected by the server.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
*
* @memberof diffusion.topics.TopicSpecification
* @alias CONFLATION
* @since 6.2
*/
module.exports.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.
* <p>
* 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
* SELECT_TOPIC by the security store rules.
* <p>
* This may be used in the following cases:-<br>
* 1) A session creates a topic and makes its own principal the owner.<br>
* 2) A session creates a topic and makes another principal the owner.
* <p>
* The format of the property value is:-
* <p>
* <code>$Principal is "<i>name</i>"</code>
* <p>
* 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 diffusion#escape(String)} if required.
* <p>
* 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.<p>
* For example:<p>
* <code>
* specification<br>
* .withProperty(diffusion.topics.TopicSpecification.OWNER,
* "$Principal is 'myPrincipal'")<br>
* .withProperty(diffusion.topics.TopicSpecification.REMOVAL,
* "when no session has '$Principal is \"myPrincipal\"' for 5s");
* </code>
*
* @memberof diffusion.topics.TopicSpecification
* @alias OWNER
* @since 6.1
*/
module.exports.OWNER = "OWNER";
/**
* Key of the topic property that allows compression to be disabled on a
* per-topic basis.
* <p>
* Compression reduces the bandwidth required to broadcast topic updates to
* subscribed sessions.
* <p>
* 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 property determines if and how the published 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.
* <p>
* Generally compression is beneficial, so the default value for this
* property is `true`, meaning compression is enabled. Setting this
* property to `false` disables compression for the topic.
*
* <p>
* Whether compression is enabled or disabled by this property is only one
* factor that determines whether a topic message will be compressed. Other
* factors include:
* <ul>
* <li>Compression must be enabled in the server configuration.
* <li>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. The Java, Android,
* .NET and JavaScript client libraries are capable of zlib compression. A
* JavaScript client must explicitly download the zlib library; it is
* packaged separately to reduce the download size of the core library.
* <li>The message must be sufficiently large. Messages smaller than a few
* tens of bytes are not compressed because the potential savings are
* negligible.
* <li>Future releases may use further heuristics to trade off the cost of
* compression against the potential savings.
* </ul>
*
* @memberof diffusion.topics.TopicSpecification
* @alias COMPRESSION
* @since 6.2
*/
module.exports.COMPRESSION = "COMPRESSION";