CachePut class final

Marks a method whose result should always be stored (or updated) in the cache.

Unlike Cacheable, which checks if the result already exists before caching, @CachePut forces the method to execute and updates the cache with the returned value — ensuring that the cache entry stays fresh and consistent with the latest computation.

CachePut works with the Interceptable mixin that provides when method, and it is required, else caching cannot intercept the method call.

Example

@Service()
final class UserService with Interceptable {
  @CachePut({'users'}, condition: WhenExpr('#args[0] != null'), unless: WhenExpr('#result == null'))
  Future<User> updateUser(User user) async {
    return when(() async => userRepository.save(user));
  }
}

Behavior

  • The annotated method is always executed, unlike Cacheable.
  • After execution, if the condition evaluates to true and unless evaluates to false, the result is stored in the specified caches.
  • The cache key is generated using the default key generator or a custom one specified via keyGenerator.

Parameters

  • cacheNames — The set of cache identifiers to update or replace.
  • condition — A ResourceCondition that must evaluate to true for cache updating to occur. Defaults to WhenAlways.
  • unless — A ResourceCondition that prevents cache updating if it evaluates to true. Defaults to WhenNever.
  • keyGenerator — An optional reference to a custom key generator name customKeyGenerator. Must be registered in the PodFactory context.
  • cacheManager — An optional reference to a custom cache manager name customCacheManager. Must be registered in the PodFactory context.
  • cacheResolver — An optional reference to a custom cache resolver name cacheResolverType. Must be registered in the PodFactory context.

Notes

  • Typically used for methods that modify underlying data sources (e.g., update or insert).
  • Can be combined with CacheEvict to synchronize multiple caches.
  • Both condition and unless support expression-based evaluation through WhenExpr.
Inheritance
Annotations
  • @Target.new({TargetKind.method})

Constructors

CachePut(Set<String> cacheNames, {ResourceCondition condition = const WhenAlways(), ResourceCondition unless = const WhenNever(), String? keyGenerator, String? cacheManager, String? cacheResolver, Duration? ttl})
Creates a new CachePut annotation for cache-update methods.
const

Properties

annotationType → Type
Returns the annotation _type of this annotation.
no setteroverride
cacheManager → String?
Optional custom cache manager name
finalinherited
cacheNames → Set<String>
The names of the caches to use for this operation.
finalinherited
cacheResolver → String?
Optional custom cache resolver name
finalinherited
condition → ResourceCondition
The condition that must be satisfied for caching to occur.
finalinherited
hashCode → int
Returns a hash code consistent with equality definition.
no setterinherited
keyGenerator → String?
Optional custom key generator name
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
ttl → Duration?
The time-to-live (TTL) duration for this cache entry.
finalinherited
unless → ResourceCondition
The condition that, if true, prevents caching.
finalinherited

Methods

equals(Object other) → bool
Checks whether the given object is logically equivalent to this annotation.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
Returns a string representation of this annotation.
inherited

Operators

operator ==(Object other) → bool
Checks if this annotation is equal to another object.
inherited