Create a new TopicSpecification
the topic type for this specification.
the properties to use for this specification.
A map of the topic properties.
The topic type.
Key of the topic property that allows compression to be disabled on a per-topic basis.
Compression reduces the bandwidth required to broadcast topic updates to subscribed sessions.
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.
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.
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:
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:
offconflateunsubscribealwaysThe 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.
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.
By default, a topic (other than a SLAVE, or ROUTING 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' disables delta streams, regardless of
the 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.
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 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 TIME_SERIES_RETAINED_RANGE property.
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 SELECT_TOPIC 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 name is the name of the principal. Single quotes may be used instead of double quotes and special characters can be escaped using 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 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");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.
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 to publishing the complete new value. Subscribing sessions can use a 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 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 ValueStream); and to disable
delta streams to investigate their performance benefits.
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:
when conditions [remove 'selector']
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. (condition and
condition)).
The remove clause is optional. It provides a 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.
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:
| Condition Type | Format | Usage |
|---|---|---|
| time after | time after absoluteTime |
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) or as a quoted date and time formatted in RFC_1123 date time format. Either single or double quotes may be used. |
| subscriptions less than | subscriptions < n for forPeriod [after afterPeriod] |
Removal should occur when the topic has had less than the specified number (n) of subscriptions for a given period (forPeriod) of time. Optionally, an initial period (afterPeriod) may be specified by which to delay the initial checking of this condition. See below for period formats. |
| no updates for | no updates for forPeriod [after afterPeriod] |
Removal should occur when the topic has had no updates for a given period (forPeriod) of time. Optionally, an initial period (afterPeriod) may be specified by which to delay the initial checking of this condition. See below for period formats. |
| no session has | no session has 'criteria' [for forPeriod] [after afterPeriod] |
Removal should occur when no sessions satisfy certain criteria. Optionally the criteria can be required to be satisfied for a period of time (forPeriod). Optionally, an initial period (afterPeriod) can be specified to delay the initial check of the criteria. Session selection criteria are specified as defined in session filters and must be surrounded by single or double quotes. See below for period formats. |
| `this session closes` | 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. |
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 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 1518780068112The 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 20mThe topic will be removed when it has had no subscriptions for a continuous period of 20 minutes.
when subscriptions < 2 for 20m after 1hThe 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 3hThe topic will be removed when it has had no updates for a continuous period of 3 hours.
when no updates for 15m after 1dThe 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 closesThe 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 10mThe topic will be removed when there have been no sessions with the principal 'Alice' for a continuous period of 10 minutes.
when no session has 'Department is "Accounts"' for 30m after 2hThe 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 30mThe 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 1hThe 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 1hThe 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 on no session has
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.
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.
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.
Key of the topic property that specifies a schema which constrains topic values.
This property is only used by RECORD_V2 topics. The value is converted to a Diffusion record schema using RecordV2DataType.parseSchema.
Key of the topic property that specifies the master topic path for a slave topic.
When creating a slave topic using a topic specification then this must be specified. For all other topic types it is ignored.
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.
Key of the topic property that specifies the event data type for a time series topic.
The value is the type name of a data 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.
The property value is a time series range expression string composed of one or more constraint clauses. Constraints are combined to provide a range of events from the end of the time series.
MS – milliseconds; S – seconds; H – hours.
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.
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 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 Subscription range in the time series feature documentation.
Key of the topic property indicating 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 data type API will not
be invalid anyway.
Returns a new TopicSpecification with the specified property set to the supplied value.
the new property key
the new property value
a new TopicSpecification with the specified property set.
Topic specifications provide the information required to create a topic. Topics can be created from a topic specification using TopicControl.add.
Topic specifications allow an application to introspect the type and capabilities of a topic. Topic specifications are provided to ValueStreams and topic notification listeners.
A topic is specified in terms of its type and a map of optional property settings which can alter the default behavior of the topic.
Topic Properties
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.
JSON
BINARY
INT64
TIME_SERIEStopics have restricted values for theCONFLATIONproperty. They are only allowed to have the valuesofforunsubscribe.ROUTINGandSLAVEtopics are references to other topics, and have no value of their own. Instead, they reflect the value of the appropriate source topic. Observed behavior depends on the values of theDONT_RETAIN_VALUE,PUBLISH_VALUES_ONLY, andVALIDATE_VALUESproperties that are set on the source topic.