HHH-12200 - Docs mention outdated APIs
This commit is contained in:
Vlad Mihalcea
parent
35806c9dcb
commit
f708a75c4f
|
|
@ -17,8 +17,6 @@ hibernate-proxool:: Integrates the http://proxool.sourceforge.net/[Proxool] conn
|
||||||
hibernate-jcache:: Integrates the https://jcp.org/en/jsr/detail?id=107$$[JCache] caching specification into Hibernate,
|
hibernate-jcache:: Integrates the https://jcp.org/en/jsr/detail?id=107$$[JCache] caching specification into Hibernate,
|
||||||
enabling any compliant implementation to become a second-level cache provider.
|
enabling any compliant implementation to become a second-level cache provider.
|
||||||
hibernate-ehcache:: Integrates the http://ehcache.org/[Ehcache] caching library into Hibernate as a second-level cache provider.
|
hibernate-ehcache:: Integrates the http://ehcache.org/[Ehcache] caching library into Hibernate as a second-level cache provider.
|
||||||
hibernate-infinispan:: Integrates the http://infinispan.org/[Infinispan] caching library into Hibernate as a second-level cache provider.
|
|
||||||
|
|
||||||
|
|
||||||
=== Release Bundle Downloads
|
=== Release Bundle Downloads
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -610,12 +610,12 @@ The default value of this setting is determined by the value for `hibernate.gene
|
||||||
[[configurations-cache]]
|
[[configurations-cache]]
|
||||||
=== Cache Properties
|
=== Cache Properties
|
||||||
|
|
||||||
`*hibernate.cache.region.factory_class*` (e.g. `org.hibernate.cache.infinispan.InfinispanRegionFactory`)::
|
`*hibernate.cache.region.factory_class*` (e.g. `jcache`)::
|
||||||
The fully-qualified name of the `RegionFactory` implementation class.
|
Either a shortcut name (e.g. `jcache`, `ehcache`) or the fully-qualified name of the `RegionFactory` implementation class.
|
||||||
|
|
||||||
`*hibernate.cache.default_cache_concurrency_strategy*`::
|
`*hibernate.cache.default_cache_concurrency_strategy*`::
|
||||||
Setting used to give the name of the default https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/CacheConcurrencyStrategy.html[`CacheConcurrencyStrategy`] to use
|
Setting used to give the name of the default https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/CacheConcurrencyStrategy.html[`CacheConcurrencyStrategy`] to use
|
||||||
when either `@javax.persistence.Cacheable` or `@org.hibernate.annotations.Cache`. `@org.hibernate.annotations.Cache` is used to override the global setting.
|
when either `@javax.persistence.Cacheable` or `@org.hibernate.annotations.Cache`. `@org.hibernate.annotations.Cache` is used to override the global setting.
|
||||||
|
|
||||||
`*hibernate.cache.use_minimal_puts*` (e.g. `true` (default value) or `false`)::
|
`*hibernate.cache.use_minimal_puts*` (e.g. `true` (default value) or `false`)::
|
||||||
Optimizes second-level cache operation to minimize writes, at the cost of more frequent reads. This is most useful for clustered caches and is enabled by default for clustered cache implementations.
|
Optimizes second-level cache operation to minimize writes, at the cost of more frequent reads. This is most useful for clustered caches and is enabled by default for clustered cache implementations.
|
||||||
|
|
@ -650,17 +650,8 @@ Sets the associated collection cache concurrency strategy for the designated reg
|
||||||
[[configurations-infinispan]]
|
[[configurations-infinispan]]
|
||||||
=== Infinispan properties
|
=== Infinispan properties
|
||||||
|
|
||||||
`*hibernate.cache.infinispan.cfg*` (e.g. `org/hibernate/cache/infinispan/builder/infinispan-configs.xml`)::
|
For more details about how to customize the Infinispan second-level cache provider, check out the
|
||||||
Classpath or filesystem resource containing the Infinispan configuration settings.
|
http://infinispan.org/docs/stable/user_guide/user_guide.html#configuration_properties[Infinispan User Guide]
|
||||||
|
|
||||||
`*hibernate.cache.infinispan.statistics*`::
|
|
||||||
Property name that controls whether Infinispan statistics are enabled. The property value is expected to be a boolean true or false, and it overrides statistic configuration in base Infinispan configuration, if provided.
|
|
||||||
|
|
||||||
`*hibernate.cache.infinispan.use_synchronization*`::
|
|
||||||
Deprecated setting because Infinispan is designed to always register a `Synchronization` for `TRANSACTIONAL` caches.
|
|
||||||
|
|
||||||
`*hibernate.cache.infinispan.cachemanager*` (e.g. There is no default value, the user must specify the property.)::
|
|
||||||
Specifies the JNDI name under which the `EmbeddedCacheManager` is bound.
|
|
||||||
|
|
||||||
[[configurations-transactions]]
|
[[configurations-transactions]]
|
||||||
=== Transactions properties
|
=== Transactions properties
|
||||||
|
|
|
||||||
|
|
@ -280,7 +280,6 @@ Hibernate generates a value automatically.
|
||||||
Automatic generation is only available if you use ID generators which operate on the database.
|
Automatic generation is only available if you use ID generators which operate on the database.
|
||||||
Otherwise, Hibernate throws an exception during parsing.
|
Otherwise, Hibernate throws an exception during parsing.
|
||||||
Available in-database generators are `org.hibernate.id.SequenceGenerator` and its subclasses, and objects which implement `org.hibernate.id.PostInsertIdentifierGenerator`.
|
Available in-database generators are `org.hibernate.id.SequenceGenerator` and its subclasses, and objects which implement `org.hibernate.id.PostInsertIdentifierGenerator`.
|
||||||
The most notable exception is `org.hibernate.id.TableHiLoGenerator`, which does not expose a selectable way to get its values.
|
|
||||||
|
|
||||||
For properties mapped as either version or timestamp, the insert statement gives you two options.
|
For properties mapped as either version or timestamp, the insert statement gives you two options.
|
||||||
You can either specify the property in the properties_list, in which case its value is taken from the corresponding select expressions, or omit it from the properties_list,
|
You can either specify the property in the properties_list, in which case its value is taken from the corresponding select expressions, or omit it from the properties_list,
|
||||||
|
|
|
||||||
|
|
@ -677,401 +677,9 @@ unless an appropriate `<defaultCache>` entry is added to the Ehcache configurati
|
||||||
[[caching-provider-infinispan]]
|
[[caching-provider-infinispan]]
|
||||||
=== Infinispan
|
=== Infinispan
|
||||||
|
|
||||||
[NOTE]
|
Infinispan is a distributed in-memory key/value data store, available as a cache or data grid, which can be used as a Hibernate 2nd-level cache provider as well.
|
||||||
====
|
|
||||||
Use of the build-in integration for http://infinispan.org/[Infinispan] requires that the `hibernate-infinispan module` jar (and all of its dependencies) are on the classpath.
|
|
||||||
====
|
|
||||||
|
|
||||||
How to configure Infinispan to be the second level cache provider varies slightly depending on the deployment scenario:
|
It supports advanced functionality such as transactions, events, querying, distributed processing, off-heap and geographical failover.
|
||||||
|
|
||||||
==== Single Node Local
|
|
||||||
|
|
||||||
In standalone library mode, a JPA/Hibernate application runs inside a Java SE application or inside containers that don't offer Infinispan integration.
|
|
||||||
|
|
||||||
Enabling Infinispan second level cache provider inside a JPA/Hibernate application that runs in single node is very straightforward.
|
|
||||||
First, make sure the Hibernate Infinispan cache provider (and its dependencies) are available in the classpath, then modify the persistence.xml to include these properties:
|
|
||||||
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<!-- Use Infinispan second level cache provider -->
|
|
||||||
<property name="hibernate.cache.region.factory_class"
|
|
||||||
value="org.hibernate.cache.infinispan.InfinispanRegionFactory"/>
|
|
||||||
|
|
||||||
<!-- Optional: Force using local configuration when only using a single node.
|
|
||||||
Otherwise a clustered configuration is loaded. -->
|
|
||||||
<property name="hibernate.cache.infinispan.cfg"
|
|
||||||
value="org/hibernate/cache/infinispan/builder/infinispan-configs-local.xml"/>
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
Plugging in Infinispan as second-level cache provider requires at the bare minimum that `hibernate.cache.region.factory_class` is set to an Infinispan region factory implementation.
|
|
||||||
Normally, this is `org.hibernate.cache.infinispan.InfinispanRegionFactory` but other region factories are possible in alternative scenarios (see <<caching-provider-infinispan-region-factory, Alternative Region Factory>> section for more info).
|
|
||||||
|
|
||||||
By default, the Infinispan second-level cache provider uses an Infinispan configuration that's designed for clustered environments.
|
|
||||||
However, since this section is focused on running Infinispan second-level cache provider in a single node, an Infinispan configuration designed for local environments is recommended.
|
|
||||||
To enable that configuration, set `hibernate.cache.infinispan.cfg` to `org/hibernate/cache/infinispan/builder/infinispan-configs-local.xml` value.
|
|
||||||
|
|
||||||
The next section focuses on analysing how the default local configuration works.
|
|
||||||
Changing Infinispan configuration options can be done following the instructions in <<caching-provider-infinispan-config, Configuration Properties>> section.
|
|
||||||
|
|
||||||
===== Default Local Configuration
|
|
||||||
|
|
||||||
Infinispan second-level cache provider comes with a configuration designed for local, single node, environments.
|
|
||||||
These are the characteristics of such configuration:
|
|
||||||
|
|
||||||
* Entities, collections, queries and timestamps are stored in non-transactional local caches.
|
|
||||||
|
|
||||||
* Entities and collections query caches are configured with the following eviction settings.
|
|
||||||
You can change these settings on a per entity or collection basis or per individual entity or collection type.
|
|
||||||
More information in the <<integrations:infinispan-2lc-advanced,Advanced Configuration>> section below.
|
|
||||||
- Eviction wake up interval is 5 seconds.
|
|
||||||
- Max number of entries are 10,000
|
|
||||||
- Max idle time before expiration is 100 seconds
|
|
||||||
- Default eviction algorithm is LRU, least recently used.
|
|
||||||
|
|
||||||
* _No eviction/expiration is configured for timestamp caches_, nor it's allowed.
|
|
||||||
|
|
||||||
===== Local Cache Strategies
|
|
||||||
|
|
||||||
Before version 5.0, Infinispan only supported `transactional` and `read-only` strategies.
|
|
||||||
|
|
||||||
Starting with version 5.0, all cache strategies are supported: `transactional`, `read-write`, `nonstrict-read-write` and `read-only`.
|
|
||||||
|
|
||||||
==== Multi Node Cluster
|
|
||||||
|
|
||||||
When running a JPA/Hibernate in a multi-node environment and enabling Infinispan second-level cache, it is necessary to cluster the second-level cache so that cache consistency can be guaranteed.
|
|
||||||
Clustering the Infinispan second-level cache provider is as simple as adding the following properties:
|
|
||||||
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<!-- Use Infinispan second level cache provider -->
|
|
||||||
<property name="hibernate.cache.region.factory_class"
|
|
||||||
value="org.hibernate.cache.infinispan.InfinispanRegionFactory"/>
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
As with the standalone local mode, at the bare minimum the region factory has to be configured to point to an Infinispan region factory implementation.
|
|
||||||
|
|
||||||
However, the default Infinispan configuration used by the second-level cache provider is already configured to work in a cluster environment, so no need to add any extra properties.
|
|
||||||
|
|
||||||
The next section focuses on analysing how the default cluster configuration works.
|
|
||||||
Changing Infinispan configuration options can be done following the instructions in <<caching-provider-infinispan-config, Configuration Properties>> section.
|
|
||||||
|
|
||||||
===== Default Cluster Configuration [[integrations:infinispan-2lc-cluster-configuration]]
|
|
||||||
|
|
||||||
Infinispan second-level cache provider default configuration is designed for multi-node clustered environments.
|
|
||||||
The aim of this section is to explain the default settings for each of the different global data type caches (entity, collection, query and timestamps), why these were chosen and what are the available alternatives.
|
|
||||||
These are the characteristics of such configuration:
|
|
||||||
|
|
||||||
* For all entities and collections, whenever a new _entity or collection is read from database_ and needs to be cached, _it's only cached locally_ in order to reduce intra-cluster traffic.
|
|
||||||
This option can be changed so that entities/collections are cached cluster wide, by switching the entity/collection cache to be replicated or distributed.
|
|
||||||
How to change this option is explained in the <<caching-provider-infinispan-config, Configuration Properties>> section.
|
|
||||||
|
|
||||||
* All _entities and collections are configured to use a synchronous invalidation_ as clustering mode.
|
|
||||||
This means that when an entity is updated, the updated cache will send a message to the other members of the cluster telling them that the entity has been modified.
|
|
||||||
Upon receipt of this message, the other nodes will remove this data from their local cache, if it was stored there.
|
|
||||||
This option can be changed so that both local and remote nodes contain the updates by configuring entities or collections to use a replicated or distributed cache.
|
|
||||||
With replicated caches all nodes would contain the update, whereas with distributed caches only a subset of the nodes.
|
|
||||||
How to change this option is explained in the <<caching-provider-infinispan-config, Configuration Properties>> section.
|
|
||||||
|
|
||||||
* All _entities and collections have initial state transfer disabled_ since there's no need for it.
|
|
||||||
|
|
||||||
* Entities and collections are configured with the following eviction settings.
|
|
||||||
You can change these settings on a per entity or collection basis or per individual entity or collection type.
|
|
||||||
More information in the <<caching-provider-infinispan-config, Configuration Properties>> section below.
|
|
||||||
- Eviction wake up interval is 5 seconds.
|
|
||||||
- Max number of entries are 10,000
|
|
||||||
- Max idle time before expiration is 100 seconds
|
|
||||||
- Default eviction algorithm is LRU, least recently used.
|
|
||||||
|
|
||||||
* Assuming that query caching has been enabled for the persistence unit (see <<caching-query, query cache section>>), the query cache is configured so that _queries are only cached locally_.
|
|
||||||
Alternatively, you can configure query caching to use replication by selecting the `replicated-query` as query cache name.
|
|
||||||
However, replication for query cache only makes sense if, and only if, all of this conditions are true:
|
|
||||||
- Performing the query is quite expensive.
|
|
||||||
- The same query is very likely to be repeatedly executed on different cluster nodes.
|
|
||||||
- The query is unlikely to be invalidated out of the cache (Note: Hibernate must aggressively invalidate query results from the cache any time any instance of one of the entity types targeted by the query. All such query results are invalidated, even if the change made to the specific entity instance would not have affected the query result)
|
|
||||||
|
|
||||||
* _query cache_ uses the _same eviction/expiration settings as for entities/collections_.
|
|
||||||
|
|
||||||
* _query cache has initial state transfer disabled_ . It is not recommended that this is enabled.
|
|
||||||
|
|
||||||
* The _timestamps cache is configured with asynchronous replication_ as clustering mode.
|
|
||||||
Local or invalidated cluster modes are not allowed, since all cluster nodes must store all timestamps.
|
|
||||||
As a result, _no eviction/expiration is allowed for timestamp caches either_.
|
|
||||||
|
|
||||||
[IMPORTANT]
|
|
||||||
====
|
|
||||||
Asynchronous replication was selected as default for timestamps cache for performance reasons.
|
|
||||||
A side effect of this choice is that when an entity/collection is updated, for a very brief period of time stale queries might be returned.
|
|
||||||
It's important to note that due to how Infinispan deals with asynchronous replication, stale queries might be found even query is done right after an entity/collection update on same node.
|
|
||||||
The reason why asynchronous replication works this way is because there's a single node that's owner for a given key, and that enables changes to be applied in the same order in all nodes.
|
|
||||||
Without it, it could happen that an older value could replace a newer value in certain nodes.
|
|
||||||
====
|
|
||||||
|
|
||||||
[NOTE]
|
|
||||||
====
|
|
||||||
Hibernate must aggressively invalidate query results from the cache any time any instance of one of the entity types is modified. All cached query results referencing given entity type are invalidated, even if the change made to the specific entity instance would not have affected the query result.
|
|
||||||
The timestamps cache plays here an important role - it contains last modification timestamp for each entity type. After a cached query results is loaded, its timestamp is compared to all timestamps of the entity types that are referenced in the query and if any of these is higher, the cached query result is discarded and the query is executed against DB.
|
|
||||||
====
|
|
||||||
|
|
||||||
===== Cluster Cache Strategies
|
|
||||||
|
|
||||||
Before version 5.0, Infinispan only supported `transactional` and `read-only` strategies on top of _transactional invalidation_ caches.
|
|
||||||
|
|
||||||
Since version 5.0, Infinispan currently supports all cache concurrency modes in cluster mode, although not all combinations of configurations are compatible:
|
|
||||||
|
|
||||||
* _non-transactional invalidation_ caches are supported as well with `read-write` strategy. The actual setting of cache concurrency mode (`read-write` vs. `transactional`) is not honored, the appropriate strategy is selected based on the cache configuration (_non-transactional_ vs. _transactional_).
|
|
||||||
* `read-write` mode is supported on _non-transactional distributed/replicated_ caches, however, eviction should not be used in this configuration. Use of eviction can lead to consistency issues. Expiration (with reasonably long max-idle times) can be used.
|
|
||||||
* `nonstrict-read-write` mode is supported on _non-transactional distributed/replicated_ caches, but the eviction should be turned off as well. In addition to that, the entities must use versioning. This mode mildly relaxes the consistency - between DB commit and end of transaction commit a stale read (see <<caching-provider-infinispan-stale-read-example,example>>) may occur in another transaction. However this strategy uses less RPCs and can be more performant than the other ones.
|
|
||||||
* `read-only` mode is supported on both _transactional_ and _non-transactional_ _invalidation_ caches and _non-transactional distributed/replicated_ caches, but use of this mode currently does not bring any performance gains.
|
|
||||||
|
|
||||||
The available combinations are summarized in table below:
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-compatibility-table]]
|
|
||||||
.Cache concurrency strategy/cache mode compatibility table
|
|
||||||
[options="header"]
|
|
||||||
|===
|
|
||||||
|Concurrency strategy|Cache transactions|Cache mode |Eviction
|
|
||||||
|transactional |transactional |invalidation |yes
|
|
||||||
|read-write |non-transactional |invalidation |yes
|
|
||||||
|read-write |non-transactional |distributed/replicated |no
|
|
||||||
|nonstrict-read-write|non-transactional |distributed/replicated |no
|
|
||||||
|===
|
|
||||||
|
|
||||||
Changing caches to behave different to the default behaviour explained in previous section is explained in <<caching-provider-infinispan-config, Configuration Properties>> section.
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-stale-read-example]]
|
|
||||||
.Stale read with `nonstrict-read-write` strategy
|
|
||||||
====
|
|
||||||
[source, indent=0]
|
|
||||||
----
|
|
||||||
A=0 (non-cached), B=0 (cached in 2LC)
|
|
||||||
TX1: write A = 1, write B = 1
|
|
||||||
TX1: start commit
|
|
||||||
TX1: commit A, B in DB
|
|
||||||
TX2: read A = 1 (from DB), read B = 0 (from 2LC) // breaks transactional atomicity
|
|
||||||
TX1: update A, B in 2LC
|
|
||||||
TX1: end commit
|
|
||||||
Tx3: read A = 1, B = 1 // reads after TX1 commit completes are consistent again
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-region-factory]]
|
|
||||||
==== Alternative RegionFactory
|
|
||||||
|
|
||||||
In standalone environments or managed environments with no Infinispan integration, `org.hibernate.cache.infinispan.InfinispanRegionFactory` should be the choice for region factory implementation.
|
|
||||||
However, it might be sometimes desirable for the Infinispan cache manager to be shared between different JPA/Hibernate applications, for example to share intra-cluster communications channels.
|
|
||||||
In this case, the Infinispan cache manager could be bound into JNDI and the JPA/Hibernate applications could use an alternative region factory implementation:
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-region-factory-jndi-example]]
|
|
||||||
.`JndiInfinispanRegionFactory` configuration
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.region.factory_class"
|
|
||||||
value="org.hibernate.cache.infinispan.JndiInfinispanRegionFactory" />
|
|
||||||
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan.cachemanager"
|
|
||||||
value="java:CacheManager" />
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
==== Inside Wildfly
|
|
||||||
|
|
||||||
In WildFly, Infinispan is the default second level cache provider for JPA/Hibernate.
|
|
||||||
When using JPA in WildFly, region factory is automatically set upon configuring `hibernate.cache.use_second_level_cache=true` (by default second-level cache is not used).
|
|
||||||
|
|
||||||
You can find details about its configuration in link:{wildflydocroot}/JPA%20Reference%20Guide[the JPA reference guide], in particular, in the link:{wildflydocroot}/JPA%20Reference%20Guide#JPAReferenceGuide-UsingtheInfinispansecondlevelcache[second level cache] section.
|
|
||||||
|
|
||||||
The default second-level cache configurations used by Wildfly match the configurations explained above both for local and clustered environments.
|
|
||||||
So, an Infinispan based second-level cache should behave exactly the same standalone and within containers that provide Infinispan second-level cache as default for JPA/Hibernate.
|
|
||||||
|
|
||||||
[IMPORTANT]
|
|
||||||
====
|
|
||||||
Remember that if deploying to Wildfly or Application Server, the way some Infinispan second level cache provider configuration is defined changes slightly because the properties must include deployment and persistence information.
|
|
||||||
Check the <<caching-provider-infinispan-config,Configuration>> section for more details.
|
|
||||||
====
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-config]]
|
|
||||||
==== Configuration properties
|
|
||||||
|
|
||||||
As explained above, Infinispan second-level cache provider comes with default configuration in `infinispan-config.xml` that is suited for clustered use.
|
|
||||||
If there's only single JVM accessing the DB, you can use more performant `infinispan-config-local.xml` by setting the `hibernate.cache.infinispan.cfg` property.
|
|
||||||
If you require further tuning of the cache, you can provide your own configuration.
|
|
||||||
Caches that are not specified in the provided configuration will default to `infinispan-config.xml` (if the provided configuration uses clustering) or `infinispan-config-local.xml`.
|
|
||||||
|
|
||||||
[WARNING]
|
|
||||||
====
|
|
||||||
It is not possible to specify the configuration this way in WildFly.
|
|
||||||
Cache configuration changes in Wildfly should be done either modifying the cache configurations inside the application server configuration, or creating new caches with the desired tweaks and plugging them accordingly.
|
|
||||||
See examples below on how entity/collection specific configurations can be applied.
|
|
||||||
====
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-config-example]]
|
|
||||||
.Use custom Infinispan configuration
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan.cfg"
|
|
||||||
value="my-infinispan-configuration.xml" />
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
[NOTE]
|
|
||||||
====
|
|
||||||
If the cache is configured as transactional, InfinispanRegionFactory automatically sets transaction manager so that the TM used by Infinispan is the same as TM used by Hibernate.
|
|
||||||
====
|
|
||||||
|
|
||||||
Cache configuration can differ for each type of data stored in the cache. In order to override the cache configuration template, use property `hibernate.cache.infinispan._data-type_.cfg` where `_data-type_` can be one of:
|
|
||||||
|
|
||||||
`entity`:: Entities indexed by `@Id` or `@EmbeddedId` attribute.
|
|
||||||
`immutable-entity`:: Entities tagged with `@Immutable` annotation or set as `mutable=false` in mapping file.
|
|
||||||
`naturalid`:: Entities indexed by their `@NaturalId` attribute.
|
|
||||||
`collection`:: All collections.
|
|
||||||
`timestamps`:: Mapping _entity type_ -> _last modification timestamp_. Used for query caching.
|
|
||||||
`query`:: Mapping _query_ -> _query result_.
|
|
||||||
`pending-puts`:: Auxiliary caches for regions using invalidation mode caches.
|
|
||||||
|
|
||||||
For specifying cache template for specific region, use region name instead of the `_data-type_`:
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-config-cache-example]]
|
|
||||||
.Use custom cache template
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan.entities.cfg"
|
|
||||||
value="custom-entities" />
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan.query.cfg"
|
|
||||||
value="custom-query-cache" />
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan.com.example.MyEntity.cfg"
|
|
||||||
value="my-entities" />
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan.com.example.MyEntity.someCollection.cfg"
|
|
||||||
value="my-entities-some-collection" />
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
.Use custom cache template in Wildfly
|
|
||||||
When applying entity/collection level changes inside JPA applications deployed in Wildfly, it is necessary to specify deployment name and persistence unit name:
|
|
||||||
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan._war_or_ear_name_._unit_name_.com.example.MyEntity.cfg"
|
|
||||||
value="my-entities" />
|
|
||||||
<property
|
|
||||||
name="hibernate.cache.infinispan._war_or_ear_name_._unit_name_.com.example.MyEntity.someCollection.cfg"
|
|
||||||
value="my-entities-some-collection" />
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
[IMPORTANT]
|
|
||||||
====
|
|
||||||
Cache configurations are used only as a template for the cache created for given region (usually each entity hierarchy or collection has its own region). It is not possible to use the same cache for different regions.
|
|
||||||
====
|
|
||||||
|
|
||||||
Some options in the cache configuration can also be overridden directly through properties. These are:
|
|
||||||
|
|
||||||
`hibernate.cache.infinispan._something_.eviction.strategy`:: Available options are `NONE`, `LRU` and `LIRS`.
|
|
||||||
`hibernate.cache.infinispan._something_.eviction.max_entries`:: Maximum number of entries in the cache.
|
|
||||||
`hibernate.cache.infinispan._something_.expiration.lifespan`:: Lifespan of entry from insert into cache (in milliseconds)
|
|
||||||
`hibernate.cache.infinispan._something_.expiration.max_idle`:: Lifespan of entry from last read/modification (in milliseconds)
|
|
||||||
`hibernate.cache.infinispan._something_.expiration.wake_up_interval`:: Period of thread checking expired entries.
|
|
||||||
`hibernate.cache.infinispan.statistics`:: Globally enables/disable Infinispan statistics collection, and their exposure via JMX.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
====
|
|
||||||
[source, XML, indent=0]
|
|
||||||
----
|
|
||||||
<property name="hibernate.cache.infinispan.entity.eviction.strategy"
|
|
||||||
value= "LRU"/>
|
|
||||||
<property name="hibernate.cache.infinispan.entity.eviction.wake_up_interval"
|
|
||||||
value= "2000"/>
|
|
||||||
<property name="hibernate.cache.infinispan.entity.eviction.max_entries"
|
|
||||||
value= "5000"/>
|
|
||||||
<property name="hibernate.cache.infinispan.entity.expiration.lifespan"
|
|
||||||
value= "60000"/>
|
|
||||||
<property name="hibernate.cache.infinispan.entity.expiration.max_idle"
|
|
||||||
value= "30000"/>
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
With the above configuration, you're overriding whatever eviction/expiration settings were defined for the default entity cache name in the Infinispan cache configuration used, regardless of whether it's the default one or user defined.
|
|
||||||
More specifically, we're defining the following:
|
|
||||||
|
|
||||||
* All entities to use LRU eviction strategy
|
|
||||||
* The eviction thread to wake up every 2 seconds (2000 milliseconds)
|
|
||||||
* The maximum number of entities for each entity type to be 5000 entries
|
|
||||||
* The lifespan of each entity instance to be 1 minute (600000 milliseconds).
|
|
||||||
* The maximum idle time for each entity instance to be 30 seconds (30000 milliseconds).
|
|
||||||
|
|
||||||
You can also override eviction/expiration settings on a per entity/collection type basis in such way that the overriden settings only afftect that particular entity (i.e. `com.acme.Person`) or collection type (i.e. `com.acme.Person.addresses`).
|
|
||||||
Example:
|
|
||||||
|
|
||||||
[source,xml]
|
|
||||||
----
|
|
||||||
<property name="hibernate.cache.infinispan.com.acme.Person.eviction.strategy"
|
|
||||||
value= "LIRS"/>
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
Inside of Wildfly, same as with the entity/collection configuration override, eviction/expiration settings would also require deployment name and persistence unit information:
|
|
||||||
|
|
||||||
[source,xml]
|
|
||||||
----
|
|
||||||
<property name="hibernate.cache.infinispan._war_or_ear_name_._unit_name_.com.acme.Person.eviction.strategy"
|
|
||||||
value= "LIRS"/>
|
|
||||||
<property name="hibernate.cache.infinispan._war_or_ear_name_._unit_name_.com.acme.Person.expiration.lifespan"
|
|
||||||
value= "65000"/>
|
|
||||||
----
|
|
||||||
====
|
|
||||||
|
|
||||||
[NOTE]
|
|
||||||
====
|
|
||||||
In versions prior to 5.1, `hibernate.cache.infinispan._something_.expiration.wake_up_interval` was called `hibernate.cache.infinispan._something_.eviction.wake_up_interval`.
|
|
||||||
Eviction settings are checked upon each cache insert, it is expiration that needs to be triggered periodically.
|
|
||||||
The old property still works, but its use is deprecated.
|
|
||||||
====
|
|
||||||
|
|
||||||
[NOTE]
|
|
||||||
====
|
|
||||||
Property `hibernate.cache.infinispan.use_synchronization` that allowed to register Infinispan as XA resource in the transaction has been deprecated in 5.0 and is not honored anymore. Infinispan 2LC must register as synchronizations on transactional caches. Also, non-transactional cache modes hook into the current JTA/JDBC transaction as synchronizations.
|
|
||||||
====
|
|
||||||
|
|
||||||
[[caching-provider-infinispan-remote]]
|
|
||||||
==== Remote Infinispan Caching
|
|
||||||
|
|
||||||
Lately, several questions ( link:http://community.jboss.org/message/575814#575814[here] and link:http://community.jboss.org/message/585841#585841[here] ) have appeared in the Infinispan user forums asking whether it'd be possible to have an Infinispan second level cache that instead of living in the same JVM as the Hibernate code, it resides in a remote server, i.e. an Infinispan Hot Rod server.
|
|
||||||
It's important to understand that trying to set up second level cache in this way is generally not a good idea for the following reasons:
|
|
||||||
|
|
||||||
* The purpose of a JPA/Hibernate second level cache is to store entities/collections recently retrieved from database or to maintain results of recent queries.
|
|
||||||
So, part of the aim of the second level cache is to have data accessible locally rather than having to go to the database to retrieve it everytime this is needed.
|
|
||||||
Hence, if you decide to set the second level cache to be remote as well, you're losing one of the key advantages of the second level cache: the fact that the cache is local to the code that requires it.
|
|
||||||
* Setting a remote second level cache can have a negative impact in the overall performance of your application because it means that cache misses require accessing a remote location to verify whether a particular entity/collection/query is cached.
|
|
||||||
With a local second level cache however, these misses are resolved locally and so they are much faster to execute than with a remote second level cache.
|
|
||||||
|
|
||||||
There are however some edge cases where it might make sense to have a remote second level cache, for example:
|
|
||||||
|
|
||||||
* You are having memory issues in the JVM where JPA/Hibernate code and the second level cache is running.
|
|
||||||
Off loading the second level cache to remote Hot Rod servers could be an interesting way to separate systems and allow you find the culprit of the memory issues more easily.
|
|
||||||
* Your application layer cannot be clustered but you still want to run multiple application layer nodes.
|
|
||||||
In this case, you can't have multiple local second level cache instances running because they won't be able to invalidate each other for example when data in the second level cache is updated.
|
|
||||||
In this case, having a remote second level cache could be a way out to make sure your second level cache is always in a consistent state, will all nodes in the application layer pointing to it.
|
|
||||||
* Rather than having the second level cache in a remote server, you want to simply keep the cache in a separate VM still within the same machine.
|
|
||||||
In this case you would still have the additional overhead of talking across to another JVM, but it wouldn't have the latency of across a network.
|
|
||||||
+
|
|
||||||
The benefit of doing this is that:
|
|
||||||
+
|
|
||||||
** Size the cache separate from the application, since the cache and the application server have very different memory profiles.
|
|
||||||
One has lots of short lived objects, and the other could have lots of long lived objects.
|
|
||||||
** To pin the cache and the application server onto different CPU cores (using _numactl_ ), and even pin them to different physically memory based on the NUMA nodes.
|
|
||||||
|
|
||||||
|
For more details, check out the
|
||||||
|
http://infinispan.org/docs/stable/user_guide/user_guide.html#jpa_hibernate_2l_cache[Infinispan User Guide].
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue