Repository navigation
Caching by annotation
Every entity cached via the persistence caching framework, i.e. via the annotations described in this document, is placed into one or both of two distinct 'virtual' caches (virtual in that they may or may not exist independently based upon the actual underlying cache implementation). These are the Instance cache, which holds individual entity instances, and the Vector cache, which holds a list of similar entity references bound by some relationship. The references in the vector cache are references to the entities held in the instance cache. In this way, the same entity may appear in many different relationships, without copying that entity over-and-over again (and having to deal with the complexity of all those copies). The relationship which binds the lists of entities in the vector cache together is defined by you, in the finder methods of your Dao implementations.
By way of example, take a look at this Dao (see The Dao Framework)...
@DataSource("mydatasource")
@StatisticsStopwatch
@CachedWith(updates = @Update(@Vector(namespace="listByManagerAndTitle", value={@Key("manager.id"), @Key("title")})))
public class EmployeeHibernateDao extends HibernateDao<Long, Employee> {
public EmployeeHibernateDao (HibernateProxySession proxySession, VectoredDao<Long, Employee> vectoredDao) {
super(proxySession, vectoredDao);
}
@Override
public Employee persist (Employee durable) {
return super.persist(durable);
}
@Override
public Employee delete (Employee durable) {
return super.delete(durable);
}
@CacheAs(@Vector(@Key("ssn")))
public Employee findBySocialSecurityNumber (final String ssn) {
return findByCriteria(new CriteriaDetails() {
@Override
public Criteria completeCriteria (Criteria criteria) {
return criteria.add(Restrictions.eq("ssn", ssn));
}
});
}
@CacheAs(@Vector({@Key("manager.id"), @Key("title")}))
public List<Employee> listByManagerAndTitle (final Manager manager, final String title) {
return findByCriteria(new CriteriaDetails() {
@Override
public Criteria completeCriteria (Criteria criteria) {
return criteria.add(Restrictions.in("manager", manager)).add(Restrictions.in("title", title));
}
});
}
}First, note the @StatisticsStopwatch annotation on the Dao class itself. This is a marker annotation which tells the framework to keep and track usage statistics on this Dao. Later, the number of times each method has been called, where the data was found (in the cache, or in the backing data store), and the amount of time spent on retrieval, can be extracted from the framework, at runtime.
None of the annotations you see added to this class are manipulating the instance cache. That cache is handled for you simply by extending an ORM-based Dao (like Hibernate, JDO, or JPA). Each of the finder methods above (findBySocialSecurityNumber() and listByManagerAndTitle()) are annotated by @CacheAs, which tells the system to cache the results of the annotated method in the vector cache. The relationship which binds those entity instances together is defined by the finder method itself, and the results are placed in the cache under a unique key defined by the @CacheAs annotation. In order to guarantee that uniqueness, the annotation makes use of the parameters of the finder method it's annotating, as well as a namespace declared by each @Vector. We've taken some care to try and keep each of the cache keys used both human readable and self-documenting.
Lastly, have a look at the @CachedWith annotation, once again on the Dao class itself. This annotation indicates to the framework that some of the cached vectors should be kept in synch (live and fresh) with any changes made by this Dao, as entities are inserted, updated, or deleted. Note the use of the namespace and keys, which must match those of the @CacheAs annotation whose vectors are being updated. The annotation further indicates to the framework the methodology by which the synchronization should occur, on a vector-by-vector basis. The options can be complex, so see the complete documentation below, but we hope the basic use cases have been properly simplified, while the complex ones have been kept elegant.
Each of the vectors manipulated by the cache annotations is pinned to a unique key by the class of the Durable entity being stored, and the @Key annotations on each @Vector. Each @Key has 1 basic properties...
- value (defaults to 'id') - In a @CacheAs annotation, this refers literally to one of the properties of the finder method being annotated. When used in a @CachedWith annotation, this is the name of a field on the Durable instance being persisted or deleted. Either way, the value property may be dot-notated as a java bean, and the framework will attempt to follow the object's getter methods to acquire the final value.
The resulting key will take the form of...
ManagedClass:namespace[value=???, value=???, ...]
...or, given the listByManagerAndTitle() method in the example above, one possible result might be...
Employee:listByManagerAndTitle[manager.id=72738,title=Engineer Level 2]
Now, that 'manager.id' bit is a touch awkward, but we could have corrected that by adding an alias property on the @Key annoation, which would have looked like...
@Key(value="manager.id", alias = "id")
...and would have yielded a key in the form of...
Employee:listByManagerAndTitle[id=72738,title=Engineer Level 2]
...as alias substitutes for the value property in the final key only (the lookup of the value is still based solely on the value property). Remember to correct the alias of any matching vectors in the @CachedWith annotation, as necessary, so the final keys will match, otherwise the @CachedWith will never find the correct vector to synch with.
The framework of annotations being described here is ultimately made use of by a handful of AOP aspects. The aspect code is woven into your Dao classes at compilation time. In order to properly 'advise' (byte-code enhance) your Dao's persist() and delete() methods, when using an @CachedWith annotation, your Dao has to override persist() and/or delete() respectively. You need do no more than simply call the super-class versions of the methods, although you can, of course, alter their behavior as well (if you know what you're doing). If your Dao class has no @CachedWith annotation, you can ignore this requirement.
It's assumed that you're using one ORM or another to access your database as the backing store for the cache. Fact is, you can't hide the database. It has transactions. It has its own query language. That's why you're using a database. If it weren't for the query language, you'd use a NoSql system, which is essentially a big fancy hash map (a cache optimized for very large data sets). The implementation of this framework you're using almost certainly uses a NoSql system as its cache. This framework is the glue between the database and that system, allowing the database to act as the backing store and feeder, gaining the Sql capabilities of the database, and the scalability of the cache. The best of both worlds.
So we can't hide the database, but this framework is an attempt to hide the intricacies of the cache implementation, to abstract its relationship to the database, and to take on as much of that burden as we can. To make that work, you have to think a little differently about how you design your entities for your ORM, and the finder methods in your Daos.
One of the main uses of an ORM is to transparently handle orthogonal persistence for object relationships and collections. However, allowing the ORM to do this is not a good notion when mixed with caching. The purpose of holding object instantiations in the instance cache, and holding only references in the vector cache, is to allow the system to keep all usages of each instance, even across many vectors in which any instance may appear, seamlessly in synch. All the framework need do is update the instance cache and handle specific vector changes marked by the @CachedWith annotation. When allowing the ORM to manage relationships, any reference to another entity within a cached object will yield either a copy of that external entity (when non-lazy), which can't be accounted for, and will become out-of-synch when changes are next persisted, or will yield a dead reference (when lazy), which will not be in session scope upon next usage (and will generate an error or a false null value). This whole problem is compounded when attempting to deal with collections. The solution is to severe all object relationships, holding row id references instead, and refactor all collections into their own entities.
Holding a row id instead of an object relationship is really quite natural. It's what the ORM is doing behind the scenes anyway. You're just making that explicit. The ORM will go and fetch the external object by that id upon access to its field, either via a join for a non-lazy relationship, or on a separate select operation for a lazy one. For the database, the non-lazy join is often more efficient. For the cache, we always want a lazy access, which allows each entity to live separately, in its own instance bucket, making up for the extra accesses with the scalability of the cache. That doesn't mean you need to give up the illusion of holding a referenced object, you just need to add virtual access methods, like this...
public class Foo extends Durable<Long> {
private Long barId;
public synchronized Long getBarId () {
return barId;
}
public synchronized void setBarId (Long barId) {
this.barId = barId;
}
public Bar getBar () {
if (barId == null) {
return null;
}
Bar bar;
if ((bar = DaoManager.get(Bar.class).get(barId)) == null) {
throw new DataIntegrityException("Can't locate bar(%d)", barId);
}
return bar;
}
public void setBar (Bar bar) {
setBarId((bar == null) ? null : bar.getId());
}
}Every collection is a way of defining a relationship amongst entities. Your ORM converts this object representation into separate references and/or tables within the database, and a series of joins and/or select operations to fulfill the collection contract. Each collection can be replaced with either a reference to a parent object on the entity, or a separate mapping entity (with its own table and Dao implementation), or some combination of the two. The finder methods in the mapping entity's Dao implementation now substitute for the more automated work the ORM was doing, but this Dao can be properly annotated for storage within the cache. If desired, you can add synthetic getter and setter methods which return or operate upon appropriate collections, but as your finder methods are already returning collections of entities, this is usually not needed in practice.
For purely database operations, it's almost always more efficient to traverse object relationships via joins, especially when the intermediate entities are never needed in their own right, are are merely selection filters. However, those joins can make it hard to form appropriate cache keys, because the information may not be present upon object persist or delete, if the resulting cached vectors need updates, and if the relationships composed by the join are not reflected by some direct getter chain from the persisted/deleted entity. If this sounds confusing, its is, but still real, and if you try working out the cache for some of these Dao methods, you may find yourself facing this dilemma. The solution is, once again, to do the counter-intuitive thing from the database perspective, and break the join up into separate look-up operations. Sub-optimal for the database, these look-ups can be properly cached, and, in aggregate, will be much more efficient across many cache accesses.
The Dao/Cache framework will track runtime statistics (data source, number of times a finder method is called, average time spent in each finder, etc.) if it's been configured to do so. Any Dao that's going to emit statistics should be annotated with @StatisticsStopwatch. Tracking the runtime usage this way is not a particularly worrisome overhead, but in a system meant to scale, it's best to be explicit about any strictly unnecessary processing. The @StatisticsStopwatch annotation will take a boolean parameter to allow you to turn off statsitics tracking without deleting the annotation.
There's one other option to note, which is @ApplyStatistics. You can use this annotation on methods in a Dao marked as an @StatisticsStopwatch which otherwise lack any annotation. Use of @ApplyStatistics forces the framework to track the runtime usage of the annotated method, even though the method is not cache involved.
Annotating a finder method with @CacheCoherent will force that method to use the instance cache, but not the vector cache. The result is that any entities returned, whether as single instances, or in relationships of lists or iterables, will be placed into the instance cache, if otherwise missing, where they will be used by any other annotated methods, but any resulting vectors will *not* be cached. The reasons you might want to do this are arcane, and probably not within the scope of most projects, but if you find yourself in a situation where this behavior is useful, you have a way to access it.
To reiterate, the purpose of @CacheAs annotations is to tell the framework how to cache the results of finder methods in your Daos into the vector cache. The purpose of the @CachedWith annotation is to tell the framework how to keep those cached vectors fresh and lively in the face of runtime changes to the set of entity instances in those relationships. This is because @CachdWith specifies information that allows the framework to keep vectors fresh based on changes to their component instances. If a vector will not change either the entities which are referenced (due to adds or deletes), or the order of those entities (if the vector has been marked as ordered), then it does not require inclusion within a @CachedWith annotation. If no vectors require @CachedWith driven updating, then you can skip the @CachedWith annotation on that Dao.
Now. let's go through all the options on each of these annotations, and their various sub-elements.
A description of all the information necessary to allow the framework to cache the results of a Dao finder method.
- vector (default value) - A description of how a cache key should be constructed, allowing the framework to find and update information within the vector cache (see below).
- max (defaults to '0', meaning no limit) - the maximum number of elements allowed within the cached vector. If the max is exceeded, the last elements in the vector will be removed until the size of the vector is no more than the max.
- ordered (defaults to 'false') - Whether the elements of this vector should be kept ordered by the framework (even as elements are inserted, deleted, or altered via persist() or delete() calls). If no comparator (see below) is defined, then the natural ordering of the vector elements will be used.
- comparator - The class of a comparator which may be instantiated (requires a no-arg constructor) to order the elements of this vector (see ordered above).
- time (defaults to @Time(0), meaning no time limit) - If defined, then the framework (as opposed to the underlying cache implementation) will invalidate any vector which has exceeded this time to live (see below). It's preferable to use the capability of the underlying cache to handle this functionality, if available (see the specific CacheDomain and PersistentCache implementations in use within your framework configuration).
Defines a time to live for a vector within the underlying cache.
- time (default value) - A long value defining a quantity of time units, defined by the unit parameter (see below).
- unit (defaults to TimeUnit.SECONDS) - The TimeUnit constant used to calculate this time to live.
- stochastic (defaults to '0', meaning none) - If defined as a value greater than '0', then this parameter defines a random value, between '0' and this parameter's actual value, in a quantity determined by the unit parameter, which will be added to the time to live of this vector, such that the final value of the time to live will be within a range, but otherwise randomly determined. This is useful in keeping large numbers of vectors from all being invalidated and consequently re-constructed at the same time, due to large numbers of relatively simultaneous cache accesses, for example, at start-up or restart.
Contains the information describing a single cached vector, including the array of key elements (order matters) used to construct the final key used within the actual cache implementation.
- namespace - Usually, the name of the method being annotated, but any name producing a namespace unique to the managed class will do (in case differing vectors are based on the same parameters).
- value - An array of key elements in the final vector (see below).
- classifier (defaults to '' empty) - A constant string value which will be appended to the final vector key. This parameter is useful in disambiguating two otherwise identical key constructions for the same managed class (key constructions for different managed entity types will always be unique).
- asParameter (defaults to 'false') - When a classifier is in use, setting this parameter to 'true' tells the framework to view the classifier as a reference to a named parameter of the method being annotated, when used within a @CacheAs annotation. The value of the classifier will be taken from the value of this incoming method parameter. Attempting to do this within a @CachedWith annotation will result in an exception (the classifier* reference will need to be a simple constant in that case).
The @Key annotation describes one element of the map key under which the vector being described will be cached. All the keys, taken together, will be joined to form the actual cache key.
- value (defaults to 'id') - The field from which the value of this key will be derived. It's important to understand how this value will be acquired when used in a @CacheAs vs. a @CachedWith annotation. When used in @CachedAs, the value parameter must be a reference to a named parameter of the method being annotated. The value of the parameter to the annotated method becomes the value of this key element. When used in @CachedWith, the value parameter is a reference to a field of the entity being persisted or deleted. The value of the value parameter can be specified as a dot notated value, and the framework will attempt to follow the chain of getters to acquire the final value for this key. The necessity of following the reference chain from an incoming parameter in the case of @CacheAs, and a field value of the entity being acted upon in the case of @CachedWith, may lead to two different key constructions in each case (see Keys above), although they are meant to lead to the same vector. To rectify this, you can use the alias parameter (see below).
- constant (defaults to '') - If not empty, this key should be viewed as a constant value, in which case no attempt to derive a value from either a method parameter (@CacheAs) or an entity field (@CachedWith) will be made. Instead, the value of this key will be the literal string of the constant parameter itself.
- alias - Will replace the literal string used in the value parameter (see above) in the final key construction, allowing two different reference chains used in @CacheAs and @CachwedWith annotations, which are intended to produce the same key (pointing to the same vector), to actually produce the same key.
- nullable (defaults to 'false') - Whether the value for this key is allowed to be 'null'. Normally, the attempt to use a 'null' value should probably result in an exception, which leaving this parameter at the default 'false' will do.
Entities manages by a Dao will probably undergo changes as the system operates. New entity instances are created, or changes made, or current instances may be deleted. These alterations are registered with the framework via usage of the persist() or delete() methods of an annotated Dao class. Proper results from the framework, i.e. that the cache accurately reflects the data within the underlying data store (usually a relational database), then hinge upon the use of persist() and delete() when inserting, changing, or deleting managed entities. Changes made directly, via the query language (sql, jdoql, hql, or criteria), can not be tracked by the framework. If such changes are necessary, any cached instances or vectors thrown out of synchronization with the underlying data store must be invalidated manually (well, in-code, with calls to the VectoredDao itself). We would suggest avoiding use of the automated cache system in this circumstance. One final proviso is that the appropriate persist() method should be called for all changes made to a managed entity, even if the ORM in use will track such changes without the persist() call, because the entity being altered is already in a persistent state, and within session. The ORM has enhanced the entity in question, so it has this information, but the cache framework operates on the Dao alone (so as not to get involved in dueling AOP annotations), and requires the call to persist() as notification of changes. In general, the extra persist() call will represent no additional overhead for the ORM.
- updates - Each @Update (see below) element provides the required information to insure that a vector is reactive to entity changes made via this Dao's persist() or delete() methods.
- invalidates - Each @Invalidate (see below) element provides the required information to invalidate a vector in response to changes made via this Dao's persist() or delete() methods.
Defines a vector to be updated upon entity alterations, where the vector keys will be calculated based upon the following...
- vector (default value) - The vector which will be updated (see above).
- filter (defaults to '', meaning no filter) - The name of a method found within this Dao with signature (Durable) => boolean. If present, the method is passed the managed instance being persisted or deleted, and the vector referenced by this annotation is updated only if the filter method returns 'true'.
- onPersist (defaults to '', meaning normal update rules) - The name of a method found within this Dao with signature (Durable) => OnPersist. If present, on a persist() call, the method is passed the managed instance being persisted, and the instance is inserted and/or re-ordered within the vector on a return value of OnPersist.INSERT, and is removed from the vector on a return value of OnPersist.REMOVE.
- finder (defaults to @Finder(), meaning no finder) - If present, describes a way to retrieve set of managed instances (<? extends Iterable<? extends Durable>>, see below) which will be used, each in turn, to calculate the vector key of a vector, which will then be updated with the managed entity that was persisted or deleted.
- proxy (defaults to @Proxy(), meaning no proxy) - If present, describes a way to retrieve a managed entity (see below) that will be used to calculate the vector key of a vector, which will then be updated with the managed entity that was persisted or deleted. The entity passed to the proxy locating method will be the entity that was persisted or deleted, unless a finder (see finder above) was defined, in which case it will be the found instance, each in turn.
Defines a vector to be invalidated upon entity alterations, where the vector keys will be calculated based upon the following...
- vector (default value) - The vector which will be invalidated (see above).
- filter (defaults to '', meaning no filter) - The name of a method found within this Dao with signature (Durable) => boolean. If present, the method is passed the managed instance being persisted or deleted, and the vector referenced by this annotation is invalidated only if the filter method returns 'true'.
- finder (defaults to @Finder(), meaning no finder) - If present, describes a way to retrieve set of managed instances (<? extends Iterable<? extends Durable>>, see below) which will be used, each in turn, to calculate the vector key of a vector, which will then be invalidated.
- proxy (defaults to @Proxy(), meaning no proxy) - If present, describes a way to retrieve a managed entity (see below) that will be used to calculate the vector key of a vector, which will then be invalidated. The entity passed to the proxy locating method will be the entity that was persisted or deleted, unless a finder (see finder above) was defined, in which case it will be the found instance, each in turn.
Contains the information to obtain an Iterable (<? extends Iterable<? extends Durable>>) of managed entities that will be used, each in turn, to generate a vector key in place of the entity which initiated this action, and update operations will then be performed against those vector targets.
- with - The type of the Durable managed entities which will be used to generate the vector keys.
- method - If present, is the name of a method found within this Dao with signature (Durable) => Iterable<? extends Durable>. The method is passed the managed instance being persisted or deleted, and returns an iteration of entities to be used in generating a set of vector keys.
Contains the information to obtain a managed entity that should be used to calculate the updating vector key, in place of the entity which initiated this action, via this Dao's persist() or delete() method.
- with - The type of the Durable managed entity which will be swapped into the vector key calculation.
- method - If present, is the name of a method found within this Dao with signature (Durable) => Durable. The method is passed the managed instance being persisted or deleted (or returned by the current iteration of a finder, see above), and returns the proxy to be used in vector key calculations.