From e7130605f0bb36bb4c2ac957430cf1ef7c673d60 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Thu, 19 Apr 2018 12:31:41 -0500 Subject: [PATCH] HHH-11356 - Adjust the 2nd-Cache SPIs to better reflect supported uses --- migration-guide.adoc | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/migration-guide.adoc b/migration-guide.adoc index f41f6f27cf..f0e1226ec2 100644 --- a/migration-guide.adoc +++ b/migration-guide.adoc @@ -56,37 +56,39 @@ The relocation pom may be dropped in a future release. ==== -=== 5.3 -> 6.0 compatibility changes +=== Second-level cache provider SPI changes -The original driving force behind these series of changes is an effort to be as proactive as possible -about designing compatibility between 5.3 and 6.0. +Hibernate's second-level cache SPI needed to be redesigned to match with expectations between +Hibernate and the various caching providers. And the SPI did not really clarify the intention. +These mis-matched expectations certainly had the potential to lead to bugs. Although it was +originally slated for 6.0 to delay the SPI changes, we decided to back-port the work to +5.3 to address a number of bugs that could have been avoided with a clarified SPI. + +The changes also allow the caching providers to perform serious optimizations based on +the users configuration of domain data caching in Hibernate. + +Details can be seen on the https://hibernate.atlassian.net/browse/HHH-11356[HHH-11356] Jira issue + +One potential upgrade concern is any custom `org.hibernate.cache.spi.QueryCacheFactory` implementations. +`org.hibernate.cache.spi.QueryCacheFactory` was meant as a means to allow service providers the +ability to define query result caching, generally with more stale-tolerant query result invalidation handling. +However, the contract also bound it to the old second level cache contracts so they had to be +updated. Its responsibilities also changed so we also decided to "rename it" to +`org.hibernate.cache.spi.TimestampsCacheFactory` -==== Second-level cache provider SPI changes - -As a fix for a potentially nasty bug in caching, we needed to redesign the Second-level cache provider -SPI. Details can be seen on the https://hibernate.atlassian.net/browse/HHH-11356[HHH-11356] Jira issue. -Originally slated for 6.0 - to avoid the SPI changes, it was decided to back-port it to 5.3 because the -bug became really important. - -One manifestation of this is the clarification that a single second-level cache region -may not be used to store both query-results and domain-data (entity, collection and natural-id). - -Care was taken to maintain backwards compatibility so that applications could continue unchanged, -although the older access methods have been deprecated as described above. - - -==== Statistics changes +=== Statistics changes The change for HHH-11356 required changes in its consumers. One such consumer is the Hibernate Statistics system.... -==== Cache regionName expectations in API and SPI calls -prefixed v. un-prefixed +=== 5.3 -> 6.0 compatibility changes +The original driving force behind these series of changes is an effort to be as proactive as possible +about designing compatibility between 5.3 and 6.0. ==== Type system changes -Use of NavigableRole, back-ported from 6.0 \ No newline at end of file +Use of NavigableRole, back-ported from 6.0 rather than plain String \ No newline at end of file