Reword and clarify the 2LC docs #785
Conversation
| Entity collections need to be individually annotated to be cached: | ||
| When an entity is annotated with `@Cache`, all its field values are cached except for collections and relations to other entities. | ||
|
|
||
| This means the entity can be loaded without querying the database, but be careful as it implies the loaded entity might not reflect recent changes in the database. |
There was a problem hiding this comment.
Is this really true? I mean if you only have a local cache, it should always be up to date, no?
There was a problem hiding this comment.
You'd be right on "traditional Hibernate usage". But not in Protean.. That's precisely why I'm rewording this:
-
we want to allow apps sto scale up on demand / dynamically. There shouldn't be a configuration that changes semantics only when the app is a singleton. (and this 2LC isn't clustered)
-
since we can't guarantee consistency at all, with @galderz we decided to simplify the whole cache implementation by removing some complexity which fights specific race conditions. By removing the code which allows strong consistency levels, we actually lose this safety even if the app is run just in a single node mode.
Hence the need to reword some stuff here.
There was a problem hiding this comment.
And we don't want the people having simple applications in the cloud to use Protean?
That sounds very limitative from my POV.
|
|
||
| All cached queries are by default kept in a single region dedicated to them called `default-query-results-region`. | ||
|
|
||
| All regions are bounded by size and time by default. The defaults are `10000` max entries, and `100` seconds as maximum idle time. |
There was a problem hiding this comment.
Why would we put an idle time by default? I mean the items should be removed from the cache on update, no?
There was a problem hiding this comment.
I haven't added the default, just clarified the text.
There was a problem hiding this comment.
@gsmet But what if the items are not updated, e.g. with read-only entities?
|
|
||
| Also, when running multiple copies of the same application (in a cluster, for example on Kubernetes/OpenShift), caches in separate copies of the application aren't synchronized. | ||
|
|
||
| For these reasons, enabling caching is only suitable when certain assumptions can be made: we strongly recommend that only entities, collections and queries which never change are cached. Or at most, that when indeed such an entity is mutated and allowed to be read out of date (stale) this has no impact on the expectations of the application. |
There was a problem hiding this comment.
Reading that and the sentences below, it seems that you don't consider at all the case where you have only one copy of the application?
This is the case for a lot of applications and IIRC, in this case, the updated entities are updated in the cache and you never get stalled entries? At least this is my recollection that it was the case with the Ehcache implementation.
Maybe having an entirely separate paragraph about consistency and clustering would help to avoid having a negative message when people only have one simple non-clustered application?
There was a problem hiding this comment.
see above explanation: even single copy is bust (and we shouldn't allow people to assume copies are singletons, that doesn't work safely on Openshift)
|
|
||
| All cached queries are by default kept in a single region dedicated to them called `default-query-results-region`. | ||
|
|
||
| All regions are bounded by size and time by default. The defaults are `10000` max entries, and `100` seconds as maximum idle time. |
There was a problem hiding this comment.
@gsmet But what if the items are not updated, e.g. with read-only entities?
|
@Sanne Approved |
I've massaged the wording a bit further to clarify the implications of non-clustered caching.