Subscriptions

Subscriptions

A maximum of 16 subscriptions are allowed per forwarder. The Bridge makes a subscription for each topic filter in the topic list. The quality of service (QoS) for all subscriptions is specified by SourceQoS and defaults to 2.

As there is a single topic map and single key map for the forwarder, the subscriptions that are used in a single forwarder must use a common topic space. If different mappings are required, then separate forwarders can be used.

If the source sever does not allow the specified QoS, the Bridge requests a lower QoS. The server can also return a lower QoS than requested.

If the destination is Event Streams, the Bridge only requests QoS=0 or QoS=1 from the source, because the Event Streams destination does not participate in the QoS=2 protocol. If a destination does not allow a publish at the QoS of the message received, the QoS of the message is decreased to a level which is supported by the destination.

Instances

In some cases, the message rate is too high to process with a single forwarder. You can create multiple forwarders with the same definition by defining a prototype forwarder and setting the Instances count to greater than zero. Up to 100 instances can be created. When the Bridge starts, it creates the number of forwarders that are requested and appends an instance number starting with 00 and going up to 99 to the forwarder name. Each of the forwarder instances will appear to be a separately defined forwarder.

Usually a multi-instance forwarder only works when using shared subscription. If you use a non-shared subscription, each instance sends a copy of all messages to the destination. Shared subscriptions are defined in MQTTv5.0 and start with the topic filter $share/ . Eclipse Amlen allows connections to use the MQTTv5.0 shared subscriptions. In addition, it allows an older form of shared subscription with topic filters starting with $SharedSubscription/ to be use in all versions. IBM Watson™ IoT Platform allows shared subscriptions to be created using an ‘A’ client class.

Replacement variables and properties

TopicMap, Selector, KeyMap, and PartitionRule forwarder properties all allow replacement variables. When a message has properties as defined in MQTTversion 5, these properties can be used as replacement variables.

In a Selector, literal text is quoted and replacement variables are not quoted. In the other forwarder properties, literal text is not quoted, and replacement variables are represented by ${varname} where varname is the name of the replacement variable.

The following replacement variables are defined:

In addition, the name of any MQTTv5 user property is available as a replacement value.

Support for creating JSON strings is provided to allow JSON named items to be inserted into the output, and for strings to be correctly JSON escaped. A JSON replacement variable must be in the format ${JSON:name:repl} , where JSON is a constant value, name is the name of the item, and repl is a replacement variable. The three parts are separated by colons. For instance, ${JSON:Event:Topic3} creates a JSON encoded value with a name of Event and the value for ${Topic3} correctly encoded as a JSON string. This support is primarily designed for creating JSON encoded key maps.

Message Selection

A message selector allows a forwarder to select messages by using parts of the topic and properties of the message. Only messages that match the selector are forwarded. Message selectors cannot use the content in the message body to select messages.

A selector is an expression which is evaluated. A message is forwarded if the selector returns true, and is not forwarded if the selector returns false or unknown. selector is a string, with a syntax which is a subset of the SQL92 conditional expression syntax. An empty selector, or having no selector is the same as returning true.

The order of evaluation of a message selector is from left to right within precedence level. Parentheses can be used to change this order. Predefined selector literals and operator names are shown in uppercase in the following example, but are case insensitive. The routing rules used with an Event Streams destination also use this message selection syntax.

A selector can contain the following information:

Literals:

• A string literal is enclosed in single quotes, with a single quote represented by doubled single quote, for example, 'literal' and 'literal''s'.
• An exact numeric literal is a numeric value without a decimal point, for example, 57, -957, and +62; numbers in the range of long are supported.
• An approximate numeric literal is a numeric value in scientific notation, for example, 7E3 and -57.9E2, or a numeric value with a decimal, for example, 7.,-95.7, and +6.2. Numbers in the range of double are supported.
• The boolean literals TRUE and FALSE.

Identifiers:

• An identifier is a sequence of letters and digits, the first of which must be a letter. The characters underscore (_) and dollar ($) count as letters for this purpose.
• Identifiers cannot be the names NULL, TRUE, and FALSE in any case.
• Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, IS, or ESCAPE in any case.
• Identifiers are either replacement field references or property references. If an identifier that does not exist is referenced, its value is UNKNOWN.
• The type of the identifier is not modified by the evaluation. Strings can only take string operations, boolean can only take boolean operators, and numbers can only take numeric operator.

Expressions:

• Arithmetic expressions are composed of themselves, arithmetic operations, identifiers where their value is treated as a numeric literal, and numeric literals.
• Conditional expressions are composed of themselves, comparison operations, and logical operations.
• Standard bracketing () for ordering expression evaluation is supported.
• Expressions process logical operators in precedence order: NOT, AND, OR.
• Expressions can use comparison operators: =, >, >=, <, <=, <> (not equal).
• Only like type values can be compared.
• String and boolean comparison is restricted to = and <>. Two strings are equal only if they contain the same sequence of characters.
• Arithmetic operators are processed in the following precedence order:
  1. +, - (unary)
  2. *, / (multiplication and division)
  3. +, - (addition and subtraction)
• arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 AND arithmetic-expr3 comparison operator
• identifier [NOT] IN (string-literal1, string-literal2,...) comparison operator where identifier has a String or NULL value. If identifier of an IN or NOT IN operation is NULL, the value of the operation is UNKNOWN.
• identifier [NOT] LIKE pattern-value [ESCAPE escape-character] comparison operator, where identifier has a String value; pattern-value is a string literal where '_' stands for any single character; '%' stands for any sequence of characters, including the empty sequence; and all other characters stand for themselves. The optional escape-character is a single-character string literal whose character is used to escape the special meaning of the '_' and '%' in pattern-value.
• identifier IS NULL (comparison operator which changes UNKNOWN into TRUE)
• identifier IS NOT NULL (comparison operator that changes FALSE into TRUE)
• identifier IS NOT TRUE comparison operator that makes FALSE or UNKNOWN into TRUE, and TRUE into FALSE) This can also be done with the unary operator ! identifier.
• identifier IS NOT FALSE comparison operator that make UNKNOWN into TRUE. This can also be done with the unary operator !! identifier.

Unknown Values

• Comparison or arithmetic with an unknown value always yields an UNKNOWN value.
• The IS NULL, IS NOT NULL, IS NOT TRUE, and IS NOT FALSE operators can convert an UNKNOWN value into the respective TRUE and FALSE values.
• The IS NOT TRUE and IS NOT FALSE operators can be used to convert UNKNOWN into a known value. The unary form of these (! and !!) can also be used.
• The boolean operators use three-valued logic as defined by the following tables:

Examples:

Do not select messages where the path component after the second slash contains “test”.

Select only messages at QoS=1 and QoS=2 where the sixth topic part is “warning”, “error”, or “alert”.