How It Works

How It Works

Most of the caching frameworks have the not up-to-date issue, they just limiting to cache a result for a given period of time. So if you have to invalidate the cache, you must do it manually.

That's the not ordinary part of CacheAware, it does that magically. The purpose of this document is to explaining how the magic is done.

Overview

CacheAware works intercepting calls each @CacheAwareFactory annotated method and collects all entities used inside its execution. Then assumes that all those collected entities are involved (or part) of that method result.
So if any of them changes, there is no warranty the cached result is up-to-date and therefore is invalidated.

A couple of questions arise from the above statement:

• What is consider an entity?
• What means a entity changes?
• How entities are collected?

That will be answered soon, but lets introduce a few concepts first.

Basic Concepts

CacheAware distinguishes between tree kind on objects:

1. entities: basically, they are any object that implements the interface Cacheable.
   Entities are by definition mutable, they have a state and it can be changed.
   Think in a Client entity, and a function to change it's name. Think now in an other function that returns all Clients names, and that function is cached. If you change a Client's name, you will want to the cached names list to be updated. This exactly what CacheAware does.
2. immutables: refers to particular kind of objects (classes to be specific) that are not entities, but participates in the construction of the result (the one to be cached).
   A good example will be the java.util.Locale class. Imagine you want to cache the result of a method which produces a localized result. Obviously, the English version must to be different from the Spanish version, so the Locale takes part on the construction of the response. But Locale could not be an entity because it cannot change it's state (en_US will be always en_US).
   So, it's not an entity, its a inmutable, and influences the result, just like entities does.
3. The last kind are the ignored ones: that exactly what the name suggest. They are ignored. This mean they won't be collected, nor took as a part the method response. CacheAware will just ignore that object, event if it's a Cacheable. You can declare an ignored object by adding the @CacheAwareIgnore annotation to a parameter of a @CacheAwareFactory annotated method

So... what's the difference between immutables and ignored objects?
Basically immutable means that they are not entities, but they current value matters. In the localized example above, a en_US value for Locale should produce a different result than es_ES, and both result should be cached.
ignored objects means that regardless the actual value given, the result should be the same. In the localized example above, if Locale parameter is marked as ignored, then only one result will be cached and returned the same on every call, regardless the actual value for Locale.

One last conclusion: Yes, entities and immutables, can be at the same time ignored (rarely you will need to do that). entities and immutables are definitions for a class-level, ignored are for a particular method's parameter.

Not egough? Check the [Behind The Magic] section