declareKeyExpr method

KeyExpr declareKeyExpr(Object keyExpr)

Declares keyExpr on this session and returns an owned KeyExpr.

keyExpr is a String or an existing KeyExpr; a KeyExpr argument is loaned, not consumed, and remains the caller's to dispose.

Declaring reduces the key expression to a numerical id in the session's routing tables, which saves bandwidth when the expression is passed between Zenoh entities. The returned handle is accepted by every operation that takes a key expression, and reads back through KeyExpr's value as the expression it was declared from.

The handle is usable in an operation driven from another session — measured: it routes correctly and observers receive the right key expression — but it can only be undeclared on the session that declared it (see undeclareKeyExpr).

Release it with undeclareKeyExpr to unregister it, or with KeyExpr.dispose to drop the handle and leave the registration to the session's own lifetime.

Throws ArgumentError if keyExpr is neither a String nor a KeyExpr. Throws ZenohException if the expression is invalid or the declaration fails. Throws StateError if the session has been closed.

Implementation

KeyExpr declareKeyExpr(Object keyExpr) => _withKeyExprArg(
  keyExpr,
  'keyExpr',
  KeyExpr.declareOn,
);