You can enable the cache to use the Hibernate cache plug-in
by specifying properties files.
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 wxshibernate.jar file and is installed
in the wxs_install_root/opt/IBM/eXtremeScale/ObjectGrid directory.
In an integrated WebSphere Application Server environment,
the plug-in is installed in thewas_root/optionalLibraries/ObjectGrid directory.
To use the Hibernate cache plug-in, you have to include the wxshibernate.jar file
in the Hibernate library. For example, if you include the Hibernate
library in your application, also must include the wxshibernate.jar file.
If you define a shared library to include Hibernate library, you must
add the wxshibernate.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.region.factory_class"
value="com.ibm.ws.objectgrid.hibernate.cache.WXSRegionFactory"/>
<property name="hibernate.cache.use_second_level_cache" value="true"/>
<property name="hibernate.cache.use_query_cache" value="true"/>
- 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. For more information on how to add JARs to a classpath, see startXsServer script (XIO) and startOgServer script (ORB).
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 that use the ORB transport and Starting container servers that use the ORB transport 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.