Skip to content

Key templates

Garvit Joshi edited this page Nov 14, 2026 · 2 revisions

The key attribute of both annotations is a Spring expression template: literal text with #{...} islands. Only the islands are evaluated.

Template Called with Resolved key
"scheduler:cleanup" anything scheduler:cleanup
"order#42" anything order#42 (a # outside #{...} is plain text)
"user:#{#userId}" userId = "u7" user:u7
"#{'user-' + #id}" id = 7 user-7
"order:#{#order.id}" an order whose id is 42 order:42
"tenant:#{#p0}:#{#a1}" ("t1", "x") tenant:t1:x
"batch:#{#ids.?[#this > 10].size()}" ids = [5, 11, 12] batch:2

Variables

Variables inside an island:

  • a method parameter by name, such as #userId;
  • a parameter by position, #p0, #p1, ... or #a0, #a1, ...;
  • #this, the current element inside a selection or projection such as .?[...] or .![...].

There is no root object and there are no bean references: #root and @myBean are not available, and a template that uses either fails the startup. #root fails also when a parameter is called root; refer to that parameter as #p0. #this outside a selection or projection fails the startup too.

The Redis key

The resolved key is prefixed before it reaches Redis:

  • locks: <prefix>lock:<resolved key>, for example locksmith:lock:user:u7;
  • read and write locks: <prefix>rwlock:<resolved key>;
  • semaphores: <prefix>semaphore:<resolved key>.

<prefix> is locksmith.key-prefix, locksmith: by default.

Checks at startup and at call time

Every template is checked at startup. A variable that is not a parameter of the method fails the startup with a message that ends in compile with -parameters or use #p0. Parameter names are only available when your code is compiled with -parameters; spring-boot-starter-parent and Spring Boot's Gradle plugin set it, a plain javac build does not. Without it, use #p0 or #a0.

A template that resolves to null or a blank string at call time throws LocksmithConfigurationException, and the method does not run. So does a longer template when any one of its islands resolves to null or a blank string: order:#{#id} with id null or "" throws instead of locking order:.

Objects in a key

An island's value is turned into text by Spring's conversion. Strings, numbers, booleans and enums give their value; arrays and collections give their elements joined by commas. Any other object fails at call time with a SpelEvaluationException, except an object whose class can be built from a String (a public constructor, or a public static valueOf, of or from method, taking a String): that one gives its toString(), and so does 'x' + #obj for any object. Without its own toString(), the text is an identity such as Customer@54e12f4c, a new key on every call, so nothing is coordinated and nothing tells you. Use a property of the object instead, such as order:#{#order.id}.

Related limitations

Clone this wiki locally