<?xml version='1.0' encoding='UTF-8'?>

<!--
  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<simplesect version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
      http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">

    <para>
    Hazelcast provides distributed second level cache for
    your Hibernate entities, collections and queries. Hazelcast has two implementations of Hibernate
    2nd level cache, one for hibernate-pre-3.3 and one for hibernate-3.3.x versions. In your
    Hibernate configuration file (ex: hibernate.cfg.xml), add these properties:
    <itemizedlist>
        <listitem>
            <para>To enable use of second level cache
                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.use_second_level_cache">true</property>
]]></programlisting>
            </para>
        </listitem>
        <listitem>
            <para>To enable use of query cache
                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.use_query_cache">true</property>
]]></programlisting>
            </para>
        </listitem>
        <listitem>
            <para>And to force minimal puts into cache
                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.use_minimal_puts">true</property>
]]></programlisting>
            </para>
        </listitem>
        <listitem>
            <para>To configure Hazelcast for Hibernate, it is enough to put configuration file named
                <literal>hazelcast.xml</literal>
                into root of your classpath. If Hazelcast can
                not find
                <literal>hazelcast.xml</literal>
                then it will use default configuration
                from hazelcast.jar.
            </para>
        </listitem>
        <listitem>
            <para>You can define custom named Hazelcast configuration xml file with one of these
                Hibernate configuration properties.
                <programlisting language="xml">
<![CDATA[<property name="hibernate.cache.provider_configuration_file_resource_path">
     hazelcast-custom-config.xml
</property>]]>
                </programlisting>
                or
                <programlisting language="xml">
<![CDATA[<property name="hibernate.cache.hazelcast.configuration_file_path">
     hazelcast-custom-config.xml
</property>]]>
                </programlisting>
            </para>
        </listitem>
        <listitem>
            <para>You can set up Hazelcast to connect cluster as LiteMember. LiteMember is a
                member of the cluster, it has socket connection to every member in the cluster and
                it knows where the data, but does not contain any data.
                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.hazelcast.use_lite_member">true</property>
]]></programlisting>
            </para>
        </listitem>
        <listitem>
            <para>You can set up Hazelcast to connect cluster as Native Client. Native client is not
                member and it connects to one of the cluster members and delegates all cluster wide
                operations to it. When the relied cluster member dies, client will transparently
                switch to another live member. <emphasis role="italic">(Native Client property takes precedence
                    over LiteMember property.)</emphasis>
                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.hazelcast.use_native_client">true</property>
]]></programlisting>
                To setup Native Client properly, you should add Hazelcast 
                <emphasis role="bold">group-name</emphasis>, 
                <emphasis role="bold">group-password</emphasis> and
                <emphasis role="bold">cluster member address</emphasis> properties. 
                Native Client
                will connect to defined member and will get addresses of all members in the cluster.
                If the connected member will die or leave the cluster, client will automatically
                switch to another member in the cluster.
                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.hazelcast.native_client_address">10.34.22.15</property>
<property name="hibernate.cache.hazelcast.native_client_group">dev</property>
<property name="hibernate.cache.hazelcast.native_client_password">dev-pass</property>
]]></programlisting>
                <emphasis role="italic">To use Native Client you should add
                    <literal>hazelcast-client-&lt;version&gt;.jar</literal>
                    into your
                    classpath.
                </emphasis>
            </para>
            <para>
                <link xlink:href="#NativeClient">Read more about NativeClient &amp; LiteMember</link>
            </para>
        </listitem>
        <listitem>
            <para>If you are using one of Hibernate pre-3.3 version, add following property.
                <programlisting language="xml">
<![CDATA[<property name="hibernate.cache.provider_class">
     com.hazelcast.hibernate.provider.HazelcastCacheProvider
</property>]]>
				</programlisting>
            </para>
        </listitem>
        <listitem>
            <para>If you are using Hibernate 3.3.x (or newer) version, you can choose to use either
                configuration property above (Hibernate has a built-in bridge to use old-style cache
                implementations) or following property.
                <programlisting language="xml">
<![CDATA[<property name="hibernate.cache.region.factory_class">
     com.hazelcast.hibernate.HazelcastCacheRegionFactory
</property>]]>
				</programlisting>

                Or as an alternative you can use <code>HazelcastLocalCacheRegionFactory</code>
                which stores data in local node and sends invalidation messages when an entry is updated on local.
                <programlisting language="xml">
<![CDATA[<property name="hibernate.cache.region.factory_class">
     com.hazelcast.hibernate.HazelcastLocalCacheRegionFactory
</property>]]>
                </programlisting>
            </para>
        </listitem>
    </itemizedlist>
    Hazelcast creates a separate distributed map for each Hibernate cache region. So
    these regions can be configured easily via Hazelcast map configuration. You can define 
    <emphasis role="bold">backup</emphasis>,
    <emphasis role="bold">eviction</emphasis>,
    <emphasis role="bold">TTL</emphasis> and
    <emphasis role="bold">Near Cache</emphasis> properties.
    <itemizedlist>
        <listitem>
            <para>
                <link xlink:href="#MapBackup">Backup Configuration</link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link xlink:href="#MapEviction">Eviction And TTL Configuration</link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link xlink:href="#MapNearCache">Near Cache Configuration</link>
            </para>
        </listitem>
    </itemizedlist>
    Hibernate has four cache concurrency strategies:
    <emphasis>read-only</emphasis>, 
    <emphasis>read-write</emphasis>, 
    <emphasis>nonstrict-read-write</emphasis> and
    <emphasis>transactional</emphasis>. 
    But Hibernate does not forces cache providers to support all strategies. And Hazelcast supports
    first three (<emphasis role="bold">read-only</emphasis>, 
    	<emphasis role="bold">read-write</emphasis>, 
    	<emphasis role="bold">nonstrict-read-write</emphasis>) of these four strategies. 
    	Hazelcast has no support for<emphasis>transactional</emphasis> strategy yet.
    <itemizedlist>
        <listitem>
            <para>If you are using xml based class configurations, you should add a
                <emphasis>cache</emphasis> element into your configuration with
                <emphasis>usage</emphasis> attribute with one of 
                <emphasis>read-only</emphasis>, 
                <emphasis>read-write</emphasis>, 
                <emphasis>nonstrict-read-write</emphasis>.
                <programlisting language="xml"><![CDATA[<class name="eg.Immutable" mutable="false">
    <cache usage="read-only"/>
    .... 
</class>

<class name="eg.Cat" .... >
    <cache usage="read-write"/>
    ....
    <set name="kittens" ... >
        <cache usage="read-write"/>
        ....
    </set>
</class>
]]></programlisting>
            </para>
        </listitem>
        <listitem>
            <para>If you are using Hibernate-Annotations then you can add
                <emphasis>class-cache</emphasis> or
                <emphasis>collection-cache</emphasis> element into your Hibernate configuration file with
                <emphasis>usage</emphasis> attribute with one of 
                <emphasis>read only</emphasis>,
                <emphasis>read/write</emphasis>,
                <emphasis>nonstrict read/write</emphasis>.
                <programlisting language="xml"><![CDATA[<class-cache usage="read-only" class="eg.Immutable"/>
<class-cache usage="read-write" class="eg.Cat"/>
<collection-cache collection="eg.Cat.kittens" usage="read-write"/>
]]></programlisting>
            </para>
        </listitem>
    </itemizedlist>
    OR
    <itemizedlist>
        <listitem>
            <para>Alternatively, you can put Hibernate Annotation's
                <emphasis>@Cache</emphasis>
                annotation on your entities and collections.
                <programlisting language="java"><![CDATA[@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Cat implements Serializable {
     ...
}
]]></programlisting>
            </para>
        </listitem>
    </itemizedlist>
    The last thing you should be aware of is to drop
    hazelcast-hibernate-&lt;version&gt;.jar into your classpath.

    <itemizedlist>
        <title>Additional Properties:</title>
        <listitem>
            <para>
                <emphasis role="bold">Accessing underlying
                    <code>HazelcastInstance</code>
                </emphasis>
            </para>
            <para>Using
                <code>com.hazelcast.hibernate.instance.HazelcastAccessor</code>
                you can access the underlying
                <code>HazelcastInstance</code>
                used by Hibernate SessionFactory.
                <programlisting language="java"><![CDATA[SessionFactory sessionFactory = ...;
HazelcastInstance hazelcastInstance = HazelcastAccessor.getHazelcastInstance(sessionFactory);        
]]></programlisting>
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis role="bold">Changing/setting lock timeout value of
                    <emphasis role="italic">read-write</emphasis>
                    strategy
                </emphasis>
            </para>
            <para>Lock timeout value can be set using
                <literal>hibernate.cache.hazelcast.lock_timeout</literal>
                Hibernate property.
                Value should be in milliseconds and default value is 10000 ms (10 seconds).
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis role="bold">Using named
                    <literal>HazelcastInstance</literal>
                </emphasis>
            </para>
            <para>
            	Instead of creating a new <literal>HazelcastInstance</literal> for each <literal>SessionFactory</literal>,
                an existing instance can be used by setting
                <literal>hibernate.cache.hazelcast.instance_name</literal>
                Hibernate property to <literal>HazelcastInstance</literal>'s name.
                For more information see <link xlink:href="#NamedHazelcastInstance">Named HazelcastInstance</link>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis role="bold">Disabling shutdown during SessionFactory.close()</emphasis>
            </para>
            <para>Shutting down
                <literal>HazelcastInstance</literal>
                can be disabled during
                <code>SessionFactory.close()</code>
                by setting
                <literal>hibernate.cache.hazelcast.shutdown_on_session_factory_close</literal>
                Hibernate property to false.
                <emphasis role="italic">(In this case Hazelcast property
                    <literal>hazelcast.shutdownhook.enabled</literal>
                    should not
                    be set to false.)
                </emphasis>
                Default value is <literal>true</literal>.
            </para>
        </listitem>
    </itemizedlist>
    </para>
</simplesect>