[Java programming language only]

Configuring the Hibernate cache plug-in

You can enable the cache to use the Hibernate cache plug-in by specifying properties files.

Before you begin

Procedure

  1. 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.

  2. 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"/>
    • hibernate.cache.region.factory_class: The value of the region.factory_class property is the com.ibm.websphere.objectgrid.hibernate.cache.WXSRegionFactory 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.
    • To enable write-behind caching, use the following write-behind attributes on the PROPERTY_WRITE_BEHIND property. When write-behind caching is enabled, updates are temporarily stored in a JVM scope data storage until either the wxs.write_behind_interval or wxs.write_behind_max_batch_size conditions are met, when the data is flushed to the cache.
      wxs.write_behind=true, wxs.write_behind_interval=5000, wxs.write_behind_Pool_Size=10, wxs.write_behind_max_batch_size=1000
      Attention: Unless wxs.write_behind is enabled, the other write behind configuration settings are disregarded.
  3. 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.

  4. 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