Removing topics automatically
You can specify an automatic removal policy that specifies under what conditions that topic and/or other topics will be removed automatically.
Specifying automatic removal policies
The automatic removal policy for a topic is specified using the REMOVAL topic property. The property is specified as an expression which defines one or more conditions that are to be satisfied before automatic removal occurs, and an optional clause that specifies which topics to remove.
The format of the expression is:
when conditions [remove "selector"]
- conditions is one or more of the condition types in the table below, separated by and or or logical operators.
- the remove clause is optional. If not added, only the topic with the removal policy will be removed.
- selector is a TopicSelector expression representing a set of 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.
| 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 00:00:00 on 1 January 1970 UTC, or as a quoted date and time formatted in RFC_1123 ("Sun, 3 Jun 2018 11:05:30 GMT") 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. |
| local subscriptions less than | local subscriptions < n for forPeriod [after afterPeriod] | Behaves the same as subscriptions less than, but excludes subscriptions via fan-out connections. |
| 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 there are no sessions satisfying the specified 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 filtering and must be surrounded by single or double quotes. See below for period formats. Can have multiple no session has clauses in a policy. |
| no local session has | no local session has "criteria" [for forPeriod] [after afterPeriod] | Behaves the same as no session has, but excludes sessions via fan-out connections. |
| 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. Can have multiple this session closes clauses in a policy. |
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.
If quotes or backslashes (\) are required within quoted values such as selectors or session criteria then they may be escaped by preceding with \.
Time period format
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.
Counting subscriptions and sessions
The number of subscriptions to a topic includes subscriptions to reference topics created by a topic view (including remote topic views) that has the monitored topic as a source.
When monitoring across a cluster or using fan-out, the 'subscriptions less than' condition is first checked on the server that owns the topic and if satisfied, each cluster member and downstream fan-out server is queried to check if the condition has also been satisfied there. The topic will only be removed if the total number of subscriptions across the cluster and at fan-out servers is less than that specified in the condition.
A 'no session has' condition will consider all sessions hosted across a cluster and at downstream fan-out servers.
If a reference topic created by a topic view is then replicated by a remote topic view or by fan-out, it is not counted for the purposes of evaluating 'subscriptions less than' and 'no session has' clauses.
To avoid counting subscriptions or sessions through fan-out links, you can use the local keyword.
