KeyExpr

Address space

Zenoh's address space is designed around keys which serve as the names of resources.

Keys are slash-separated lists of non-empty UTF8 strings. They may not contain the following characters: $*#?.

Zenoh's operations are executed on key expressions, a small language that allows the definition of sets of keys via the use of wildcards:

  • * is the single-chunk wildcard, and will match any chunk: a/*/c will match a/b/c, a/hello/c, etc...

  • ** is the 0 or more chunks wildcard: a/**/c matches a/c, a/b/c, a/b/hello/c, etc...

  • $* is the sub-chunk wildcard, it will match any amount of non-/ characters: a/b$* matches a/b, a/because, a/blue... but not a/c nor a/blue/c

To allow for better performance and gain the property that two key expressions define the same set if and only if they are the same string, the rules of canon form are mandatory for a key expression to be propagated by a Zenoh network:

  • **/** may not exist, as it could always be replaced by the shorter **,

  • ** /* may not exist, and must be written as its equivalent */** instead,

  • $* may not exist alone in a chunk, as it must be written * instead.

The KeyExpr.autocanonize constructor exists to correct eventual infringements of the canonization rules.

A KeyExpr is a string that has been validated to be a valid Key Expression.

Memory

Valid KeyExpr instances have associated an underlying native key expression, therefore we must be careful to properly call close before the KeyExpr loses any of its references and becomes a phantom reference. As a precautionary measure, this class overrides the finalize method which invokes close when the garbage collector attempts to remove the instance. However, we should not fully rely on the finalize method, as per to the JVM specification we don't know when the GC is going to be triggered, and even worse there is no guarantee it will be called at all. Alternatively, we can use the key expression using a try with resources statement (use in Kotlin), since it will automatically invoke the close function after using it.

Parameters

jniKeyExpr

A JNIKeyExpr instance which delegates all the operations associated to this KeyExpr (intersects, includes, etc.) which are done natively. It keeps track of the underlying key expression instance. Once it is freed, the KeyExpr instance is considered to not be valid anymore.

Types

Link copied to clipboard
object Companion

Functions

Link copied to clipboard
open override fun close()

Closes the key expression. Operations performed on this key expression won't be valid anymore after this call.

Link copied to clipboard
open operator override fun equals(other: Any?): Boolean
Link copied to clipboard
open override fun hashCode(): Int
Link copied to clipboard
fun includes(other: KeyExpr): Boolean

Includes operation. This method returns true when all the keys defined by other also belong to the set defined by this. Will return false as well if the key expression is not valid anymore.

Link copied to clipboard

Intersects operation. This method returns True if there exists at least one key that belongs to both sets defined by this and other. Will return false as well if the key expression is not valid anymore.

Link copied to clipboard

Returns true if the KeyExpr has still associated a native key expression allowing it to perform operations.

Link copied to clipboard
open override fun toString(): String
Link copied to clipboard

Undeclare the key expression if it was previously declared on the specified session.