You can enable the cache to use the Hibernate cache plug-in
by specifying properties files.
Before you begin
- You must determine the JPA cache plug-in topology that you want
to use. See JPA level 2 (L2) cache plug-in for more information
about the different configurations.
- You must have an application that uses the JPA APIs. If you want
to use WebSphere eXtreme Scale APIs to
access data with JPA, use the JPA loader. For more information, see Configuring JPA loaders.
Procedure
- If you are using WebSphere Application Server,
place the Java Archive (JAR) files in the appropriate locations for
your configuration.
The
Hibernate cache plug-in is packaged in the oghibernate-cache.jar file
and is installed in the was_root/optionalLibraries/ObjectGrid directory.
To use the Hibernate cache plug-in, you have to include the oghibernate-cache.jar file
in the Hibernate library. For example, if you include the Hibernate
library in your application, also must include the oghibernate-cache.jar file.
If you define a shared library to include Hibernate library, you must
add the oghibernate-cache.jar file into the shared
library directory.
eXtreme Scale does not
install the cglib.jar file in the WebSphere Application Server environment.
If you have existing applications or shared libraries, such as hibernate,
which depend on the cglib.jar, locate the cglib.jar file
and include it in the classpath. For example, if your application
includes all hibernate library JAR files, but excludes the cglib.jar file
available with hibernate, you must include the cglib.jar file
that comes from Hibernate in your application.
- Set properties in your persistence.xml file
to configure the Hibernate cache plug-in
The syntax
for setting properties in the persistence.xml file
follows:
<property name="hibernate.cache.provider_class"
value="com.ibm.websphere.objectgrid.hibernate.cache.ObjectGridHibernateCacheProvider" />
<property name="hibernate.cache.use_query_cache" value="true"/>
<property name="objectgrid.configuration" value="<property>=<value>,..." />
<property name="objectgrid.hibernate.regionNames" value="<regionName>,.." />
- hibernate.cache.provider_class :
The value of the provider_class property
is the com.ibm.websphere.objectgrid.hibernate.cache.ObjectGridHibernateCacheProvider class.
- hibernate.cache.use_query_cache: To enable
query cache, set the value to true on the use_query_cache property.
Note: You
can enable the query cache for embedded and embedded-intradomain topologies
only.
- objectgrid.configuration:
Use the objectgrid.configuration property to specify eXtreme Scale cache configuration
properties, including the ObjectGridType attribute that specifies
how to place the shards on the data grid.
You must specify a unique
ObjectGridName property value to avoid potential naming conflicts.
The other eXtreme Scale cache
configuration properties are optional.
To enable write-behind
caching, use the following write-behind attributes on the objectgrid.configuration
property. When write-behind caching is enabled, updates are temporarily
stored in a JVM scope data storage until either the writeBehindInterval
or writeBehindMaxBatchSize conditions are met, when the data is flushed
to the cache.
writeBehind=true, writeBehindInterval=5000, writeBehindPoolSize=10, writeBehindMaxBatchSize=1000
Attention: Unless writeBehind is enabled, the other write behind
configuration settings are disregarded.
For more information
about the values that you can set in the objectgrid.configuration property,
see JPA cache configuration properties for both OpenJPA and Hibernate Version 3.0.
- objectgrid.hibernate.regionNames:
The objectgrid.hibernate.regionNames property is optional and should
be specified when the regionNames values are defined after the eXtreme Scale cache is
initialized. Consider the example of an entity class that is mapped
to a regionName with the entity class unspecified in the persistence.xml file
or not included in the Hibernate mapping file. Further, say it does
have Entity annotation. Then, the regionName for this entity class
is resolved at class loading time when the eXtreme Scale cache is
initialized. Another example is the Query.setCacheRegion(String
regionName) method that runs after the eXtreme Scale cache initialization.
In these situations, include all possible dynamic determined regionNames
in the objectgrid.hibernate.regionNames property so that the eXtreme Scale cache can
prepare BackingMaps for all regionNames.
- Optional: To further customize the data grid
used by the cache, you can provide additional settings with XML files.
For most scenarios, setting cache properties should be sufficient.
To further customize the ObjectGrid used by the cache, you can provide
Hibernate ObjectGrid configuration XML files in the META-INF directory
similarly to the persistence.xml file. During
initialization, the cache tries to locate these XML files and process
them if found.
There are three types of Hibernate ObjectGrid
configuration XML files:
- hibernate-objectGrid.xml (ObjectGrid configuration)
File
path: META-INF/hibernate-objectGrid.xml
By
default, each entity class has an associated regionName (default to
entity class name) that is mapped to a BackingMap configuration named
as regionName within the ObjectGrid configuration. For example, the
com.mycompany.Employee entity class has an associated regionName default
to com.mycompany.Employee BackingMap. The default BackingMap configuration
is readOnly="false", copyKey="false", lockStrategy="NONE", and copyMode="NO_COPY".
You can customize some BackingMaps with a chosen configuration. The
reserved key word "ALL_ENTITY_MAPS" can be used to represent all maps
excluding other customized maps listed in the hibernate-objectGrid.xmlfile.
BackingMaps that are not listed in this hibernate-objectGrid.xml file
use the default configuration.
- hibernate-objectGridDeployment.xml (deployment
policy)
File path: META-INF/hibernate-objectGridDeployment.xml
This
file is used to customize deployment policy. When you are customizing
deployment policy, if the hibernate-objectGridDeployment.xml is
provided, the default deployment policy is discarded. All deployment
policy attribute values will come from the provided hibernate-objectGridDeployment.xml file.
- hibernate-objectGrid-client-override.xml (client
ObjectGrid override configuration)
File path: META-INF/hibernate-objectGrid-client-override.xml
This
file is used to customize a client-side ObjectGrid. By default, the
ObjectGrid cache applies a default client override configuration that
disables the near cache. You can enable the near cache by providing
the hibernate-objectGrid-client-override.xml file
that overrides this configuration. For more information about the
settings to change in this file to enable near cache, see Configuring the near cache. The way that the hibernate-objectGrid-client-override.xml file
works is similar to the hibernate-objectGrid.xml file.
It overrides or extends the default client ObjectGrid override configuration.
Depending on the configured
eXtreme Scale topology,
you can provide any one of these three XML files to customize that
topology.
For both the EMBEDDED and EMBEDDED_PARTITION type,
you can provide any one of the three XML files to customize the ObjectGrid,
deployment policy, and client ObjectGrid override configuration.
For
a REMOTE ObjectGrid, the cache does not create a dynamic ObjectGrid.
The cache only obtains a client-side ObjectGrid from the catalog service.
You can only provide a hibernate-objectGrid-client-override.xml file
to customize client ObjectGrid override configuration.
- Optional: (Remote configurations only) Set
up an external eXtreme Scale system
if you want to configure a cache with a REMOTE ObjectGrid type. You
also need to specify the libraries and their dependencies in the classpath
for the eXtreme Scale container
servers.
You must set up
an external eXtreme Scale system
if you want to configure a cache with a REMOTE ObjectGrid type. You
need both ObjectGrid and ObjectGridDeployment configuration XML files
that are based on the persistence.xml file to
set up an external system. For examples of these configuration files,
seeExample: Hibernate ObjectGrid XML files.
Results
EMBEDDED or EMBEDDED_PARTITION configuration:
When
an application starts, the plug-in automatically detects or starts
a catalog service, starts a container server, and connect the container
servers to the catalog service. The plug-in then communicates with
the ObjectGrid container and its peers that are running in other application
server processes using the client connection.
Each JPA entity
has an independent backing map assigned using the class name of the
entity. Each BackingMap has the following attributes.
- readOnly="false"
- copyKey="false"
- lockStrategy="NONE"
- copyMode="NO_COPY"
REMOTE configuration:
The deployment policy
is specified separately from the JPA application. An external ObjectGrid
system has both catalog service and container server processes. You
must start a catalog service before starting container servers. See Starting stand-alone servers and Starting container servers for
more information.
What to do next
- Develop a Hibernate application that uses the configuration. For
more information, see Example: Using the Hibernate plug-in to preload data into the ObjectGrid cache.
- In a production environment, create catalog service domains for
your automatically created processes for your EMBEDDED or EMBEDDED_PARTITION
configuration.
- Stand-alone environment:
If you are not running your servers
inside a WebSphere Application Server process,
the catalog service domain hosts and ports are specified using properties
file named objectGridServer.properties. This
file must be stored in the class path of the application and have
the catalogServiceEndPoints property defined. The catalog service
domain is started independently from the application processes and
must be started before the application processes are started.
The
format of the objectGridServer.properties file
follows:
catalogServiceEndPoints=<hostname1>:<port1>,<hostname2>:<port2>
- WebSphere Application Server environment:
If
you are running inside a WebSphere Application Server process,
the JPA cache plug-in automatically connects to the catalog service
or catalog service domain that is defined for the WebSphere Application Server cell.
However, using an objectGridServer.properties file
with defined catalogServiceEndPoints will cause problems
because it will try to establish a connection to that catalog server
instead of the one in WebSphere Application Server.
- When you are using the EMBEDDED or EMBEDDED_PARTITION ObjectGridType
value in a Java SE environment,
use the System.exit(0) method at the end of the
program to stop the embedded eXtreme Scale server. Otherwise,
the program can become unresponsive.