HHH-10770 JCache provider documentation

This commit is contained in:
Louis Jacomet 2016-05-25 11:05:06 +02:00 committed by Steve Ebersole
parent 2ddefd615b
commit cab099c59a
2 changed files with 62 additions and 1 deletions

View File

@ -14,6 +14,8 @@ hibernate-osgi:: Hibernate support for running in OSGi containers.
hibernate-c3p0:: Integrates the link:$$http://www.mchange.com/projects/c3p0/$$[C3P0] connection pooling library into Hibernate
hibernate-hikaricp:: Integrates the link:$$http://brettwooldridge.github.io/HikariCP/$$[HikariCP] connection pooling library into Hibernate
hibernate-proxool:: Integrates the link:$$http://proxool.sourceforge.net/$$[Proxool] connection pooling library into Hibernate
hibernate-jcache:: Integrates the link:$$https://jcp.org/en/jsr/detail?id=107$$[JCache] caching specification into Hibernate,
enabling any compliant implementation to become a second-level cache provider.
hibernate-ehcache:: Integrates the link:$$http://ehcache.org/$$[Ehcache] caching library into Hibernate as a second-level cache provider.
hibernate-infinispan:: Integrates the link:$$http://infinispan.org/$$[Infinispan] caching library into Hibernate as a second-level cache provider.

View File

@ -25,7 +25,8 @@ This section defines the settings which control this behavior.
`org.hibernate.cache.spi.RegionFactory` defines the integration between Hibernate and a pluggable caching provider.
`hibernate.cache.region.factory_class` is used to declare the provider to use.
Hibernate comes with built-in support for two popular caching libraries: <<caching-provider-ehcache,Ehcache>> and <<caching-provider-infinispan,Infinispan>>.
Hibernate comes with built-in support for the Java caching standard <<caching-provider-jcache,JCache>>
and also two popular caching libraries: <<caching-provider-ehcache,Ehcache>> and <<caching-provider-infinispan,Infinispan>>.
Detailed information is provided later in this chapter.
[[caching-config-properties]]
@ -462,10 +463,68 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-statistics-example]
----
====
[[caching-provider-jcache]]
=== JCache
[NOTE]
====
Use of the build-in integration for https://jcp.org/en/jsr/detail?id=107[JCache] requires that the `hibernate-jcache` module jar (and all of its dependencies) are on the classpath.
In addition a JCache implementation needs to be added as well.
A list of compatible implementations can be found https://jcp.org/aboutJava/communityprocess/implementations/jsr107/index.html[on the JCP website].
An alternative source of compatible implementations can be found through https://github.com/cruftex/jsr107-test-zoo[the JSR-107 test zoo].
====
[[caching-provider-jcache-region-factory]]
==== RegionFactory
The `hibernate-jcache` module defines the following region factory: `JCacheRegionFactory`.
To use the `JCacheRegionFactory`, you need to specify the following configuration property:
[[caching-provider-jcache-region-factory-example]]
.`JCacheRegionFactory` configuration
====
[source, XML, indent=0]
----
<property
name="hibernate.cache.region.factory_class"
value="org.hibernate.cache.jcache.JCacheRegionFactory"/>
----
====
The `JCacheRegionFactory` configures a `javax.cache.CacheManager`.
[[caching-provider-jcache-cache-manager]]
==== JCache `CacheManager`
JCache mandates that `CacheManager`{empty}s sharing the same URI and class loader be unique in JVM.
If you do not specify additional properties, the `JCacheRegionFactory` will load the default JCache provider and create the default `CacheManager`.
Also, `Cache`{empty}s will be created using the default `javax.cache.configuration.MutableConfiguration`.
In order to control which provider to use and specify configuration for the `CacheManager` and `Cache`{empty}s you can use the following two properties:
[[caching-provider-jcache-region-factory-config-example]]
.JCache configuration
====
[source, XML, indent=0]
----
<property
name="hibernate.javax.cache.provider"
value="org.ehcache.jsr107.EhcacheCachingProvider"/>
<property
name="hibernate.javax.cache.uri"
value="file:/path/to/ehcache.xml"/>
----
====
Only by specifying the second property `hibernate.javax.cache.uri` will you be able to have a `CacheManager` per `SessionFactory`.
[[caching-provider-ehcache]]
=== Ehcache
This integration covers Ehcache 2.x, in order to use Ehcache 3.x as second level cache, refer to the <<caching-provider-jcache,JCache integration>>.
[NOTE]
====
Use of the build-in integration for http://www.ehcache.org/[Ehcache] requires that the `hibernate-ehcache` module jar (and all of its dependencies) are on the classpath.