Package io.zenoh.keyexpr

Class KeyExpr

  • All Implemented Interfaces:
    io.zenoh.query.IntoSelector , io.zenoh.session.SessionDeclaration , java.lang.AutoCloseable 
    
public final class KeyExpr
 implements AutoCloseable, IntoSelector, SessionDeclaration

    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.

    A KeyExpr acts as a container for the string representation of a key expression. Operations like intersects, includes, and equals are processed at the native layer using this string representation. For improved performance, consider initializing a KeyExpr through Session.declareKeyExpr. This method associates the KeyExpr with a native instance, thereby optimizing operation execution. However, it is crucial to manually invoke close on each KeyExpr instance before it is garbage collected to prevent memory leaks.

    As an alternative, employing a try-with-resources pattern using Kotlin's use block is recommended. This approach ensures that close is automatically called, safely managing the lifecycle of the KeyExpr instance.

    • Constructor Detail

    • Method Detail

      • intersects

         final Boolean intersects(KeyExpr other)

        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.

      • includes

         final Boolean includes(KeyExpr other)

        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.

      • join

         final KeyExpr join(String other)

        Joins both sides, inserting a / in between them. This should be your preferred method when concatenating path segments.

      • concat

         final KeyExpr concat(String other)

        Performs string concatenation and returns the result as a KeyExpr if possible. You should probably prefer join as Zenoh may then take advantage of the hierarchical separation it inserts.

      • close

         Unit close()

        Equivalent to undeclare. This function is automatically called when using try with resources.

      • undeclare

         Unit undeclare()

        If the key expression was declared from a Session, then undeclare frees the native key expression associated to this instance. The KeyExpr instance is downgraded into a normal KeyExpr, which still allows performing operations on it, but without the inner optimizations.