Spring 3.1 Caching and @Cacheable

@Cacheable(value = "employee")
public class EmployeeDAO {

  public Person findEmployee(String firstName, String surname, int age) {

    return new Person(firstName, surname, age);
  }

  public Person findAnotherEmployee(String firstName, String surname, int age) {

    return new Person(firstName, surname, age);
  }
}

The Cacheable annotation takes three arguments: value, which is mandatory, together with key and condition. The first of these, value, is used to specify the name of the cache (or caches) in which the a method’s return value is stored.

 @Cacheable(value = "employee")
  public Person findEmployee(String firstName, String surname, int age) {

    return new Person(firstName, surname, age);
  }

 The code above ensures that the new Person object is stored in the “employee” cache.

Any data stored in a cache requires a key for its speedy retrieval. Spring, by default, creates caching keys using the annotated method’s signature as demonstrated by the code above. You can override this using @Cacheable’s second parameter: key. To define a custom key you use a SpEL expression.

@Cacheable(value = "employee", key = "#surname")
  public Person findEmployeeBySurname(String firstName, String surname, int age) {

    return new Person(firstName, surname, age);
  }

In the findEmployeeBySurname(...) code, the ‘#surname’ string is a SpEL expression that means ‘go and create a key using the surname argument of the findEmployeeBySurname(...) method’.

The final @Cacheable argument is the optional condition argument. Again, this references a SpEL expression, but this time it’s specifies a condition that’s used to determine whether or not your method’s return value is added to the cache.

 @Cacheable(value = "employee", condition = "#age < 25")
  public Person findEmployeeByAge(String firstName, String surname, int age) {

    return new Person(firstName, surname, age);
  }

In the code above, I’ve applied the ludicrous business rule of only caching Person objects if the employee is less than 25 years old.

Having quickly demonstrated how to apply some caching, the next thing to do is to take a look at what it all means. 

@Test
  public void testCache() {

    Person employee1 = instance.findEmployee("John", "Smith", 22);
    Person employee2 = instance.findEmployee("John", "Smith", 22);

    assertEquals(employee1, employee2);
  }

The above test demonstrates caching at its simplest. The first call to findEmployee(...), the result isn’t yet cached so my code will be called and Spring will store its return value in the cache. In the second call to findEmployee(...) my code isn’t called and Spring returns the cached value; hence the local variable employee1 refers to the same object reference a

 @Test
  public void testCacheWithAgeAsCondition() {

    Person employee1 = instance.findEmployeeByAge("John", "Smith", 22);
    Person employee2 = instance.findEmployeeByAge("John", "Smith", 22);

    assertEquals(employee1, employee2);
  }

s employee2, which means that the following is true:

    assertEquals(employee1, employee2);

But, things aren’t always so clear cut. Remember that in findEmployeeBySurname I’ve modified the caching key so that the surname argument is used to create the key and the thing to watch out for when creating your own keying algorithm is to ensure that any key refers to a unique object. 

 @Test
  public void testCacheOnSurnameAsKey() {

    Person employee1 = instance.findEmployeeBySurname("John", "Smith", 22);
    Person employee2 = instance.findEmployeeBySurname("Jack", "Smith", 55);

    assertEquals(employee1, employee2);
  }

The code above finds two Person instances which are clearly refer to different employees; however, because I’m caching on surname only, Spring will return a reference to the object that’s created during my first call to findEmployeeBySurname(...). This isn’t a problem with Spring, but with my poor cache key definition.

Similar care has to be taken when referring to objects created by methods that have a condition applied to the @Cachable annotation. In my sample code I’ve applied the arbitrary condition of only caching Person instances where the employee is under 25 years old.

@Test
  public void testCacheWithAgeAsCondition() {

    Person employee1 = instance.findEmployeeByAge("John", "Smith", 22);
    Person employee2 = instance.findEmployeeByAge("John", "Smith", 22);

    assertEquals(employee1, employee2);
  }

In the above code, the references to employee1 and employee2 are equal because in the second call to findEmployeeByAge(...) Spring returns its cached instance.

 @Test
  public void testCacheWithAgeAsCondition2() {

    Person employee1 = instance.findEmployeeByAge("John", "Smith", 30);
    Person employee2 = instance.findEmployeeByAge("John", "Smith", 30);

    assertFalse(employee1 == employee2);
  }

Similarly, in the unit test code above, the references to employee1 and employee2 refer to different objects as, in this case, John Smith is over 25.

That just about covers @Cacheable, but what about @CacheEvict and clearing items form the cache? Also, there’s the question adding caching to your Spring config and choosing a suitable caching implementation. However, more on that later....