CacheableOperation class final

Represents the execution logic for a @Cacheable method within the JetLeaf resource management framework.

A cacheable operation determines whether a method invocation should be served from cache or executed normally, based on the declarative rules defined in the `Cacheable` annotation and the associated runtime CacheOperationContext.

Overview

This operation forms the foundation of JetLeaf’s transparent caching layer. It follows a reactive, non-blocking contract that integrates seamlessly with asynchronous or synchronous methods.

When invoked, it performs the following sequence:

  1. Evaluate exclusion (unless) condition — if this evaluates to true, caching is completely bypassed for the current invocation.
  2. Evaluate eligibility (condition) expression — if this evaluates to false, the method execution proceeds without cache interaction.
  3. Resolve cache instances from the context (typically via the CacheResolver or PodFactory lookup).
  4. Generate a unique cache key using the configured CustomKeyGenerator, method parameters, and context metadata.
  5. Attempt cache retrieval — if a matching entry is found, it is applied directly as the method result, marking a cache hit.
  6. Mark cache miss — if no cache contains the requested entry, the context flags the invocation for standard method execution (after which a CachePut or similar operation may populate it).

Error Handling

  • Cache lookup failures (I/O, serialization, or resolver errors) are captured via CacheErrorType.GET and reported to the CacheOperationContext.
  • A failure in one cache does not terminate the chain; the next cache is attempted automatically.

Thread-Safety and Concurrency

Implementations are stateless and safe for concurrent access. The contextual state is isolated in the provided CacheOperationContext.

Example

@Cacheable(cacheNames: {'users'}, condition: WhenExpr('#args[0] != null'))
Future<User?> findUserById(String id) async {
  return await database.findUser(id);
}

Behavior Summary

Step Description Outcome
1 Evaluate unless Skip caching if true
2 Evaluate condition Skip caching if false
3 Resolve caches May throw if unavailable
4 Generate key Delegates to key generator
5 Attempt get() Apply result if hit
6 Cache miss Proceed with method execution
Implemented types

Constructors

CacheableOperation(Cacheable annotation)
Creates a new CacheableOperation bound to a specific annotation instance.
const

Properties

annotation → Cacheable
The @Cacheable annotation that defines cache metadata and behavior.
final
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

execute<T>(CacheOperationContext<T> context) → FutureOr<void>
Represents the execution logic for a @Cacheable method within the JetLeaf resource management framework.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited