PageRenderTime 27ms CodeModel.GetById 15ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/hazelcast-documentation/src/main/docbook/manual/content/HibernateSecondLevelCache.xml

https://bitbucket.org/gabral6_gmailcom/hazelcast
XML | 301 lines | 277 code | 9 blank | 15 comment | 0 complexity | 04c474eb4cc9de0531f29a7940d41e83 MD5 | raw file
  1<?xml version='1.0' encoding='UTF-8'?>
  2
  3<!--
  4  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  5  ~
  6  ~ Licensed under the Apache License, Version 2.0 (the "License");
  7  ~ you may not use this file except in compliance with the License.
  8  ~ You may obtain a copy of the License at
  9  ~
 10  ~ http://www.apache.org/licenses/LICENSE-2.0
 11  ~
 12  ~ Unless required by applicable law or agreed to in writing, software
 13  ~ distributed under the License is distributed on an "AS IS" BASIS,
 14  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 15  ~ See the License for the specific language governing permissions and
 16  ~ limitations under the License.
 17  -->
 18
 19<simplesect version="5.0" xmlns="http://docbook.org/ns/docbook"
 20      xmlns:xi="http://www.w3.org/2001/XInclude"
 21      xmlns:xlink="http://www.w3.org/1999/xlink"
 22      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 23      xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
 24      http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">
 25
 26    <para>
 27    Hazelcast provides distributed second level cache for
 28    your Hibernate entities, collections and queries. Hazelcast has two implementations of Hibernate
 29    2nd level cache, one for hibernate-pre-3.3 and one for hibernate-3.3.x versions. In your
 30    Hibernate configuration file (ex: hibernate.cfg.xml), add these properties:
 31    <itemizedlist>
 32        <listitem>
 33            <para>To enable use of second level cache
 34                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.use_second_level_cache">true</property>
 35]]></programlisting>
 36            </para>
 37        </listitem>
 38        <listitem>
 39            <para>To enable use of query cache
 40                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.use_query_cache">true</property>
 41]]></programlisting>
 42            </para>
 43        </listitem>
 44        <listitem>
 45            <para>And to force minimal puts into cache
 46                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.use_minimal_puts">true</property>
 47]]></programlisting>
 48            </para>
 49        </listitem>
 50        <listitem>
 51            <para>To configure Hazelcast for Hibernate, it is enough to put configuration file named
 52                <literal>hazelcast.xml</literal>
 53                into root of your classpath. If Hazelcast can
 54                not find
 55                <literal>hazelcast.xml</literal>
 56                then it will use default configuration
 57                from hazelcast.jar.
 58            </para>
 59        </listitem>
 60        <listitem>
 61            <para>You can define custom named Hazelcast configuration xml file with one of these
 62                Hibernate configuration properties.
 63                <programlisting language="xml">
 64<![CDATA[<property name="hibernate.cache.provider_configuration_file_resource_path">
 65     hazelcast-custom-config.xml
 66</property>]]>
 67                </programlisting>
 68                or
 69                <programlisting language="xml">
 70<![CDATA[<property name="hibernate.cache.hazelcast.configuration_file_path">
 71     hazelcast-custom-config.xml
 72</property>]]>
 73                </programlisting>
 74            </para>
 75        </listitem>
 76        <listitem>
 77            <para>You can set up Hazelcast to connect cluster as LiteMember. LiteMember is a
 78                member of the cluster, it has socket connection to every member in the cluster and
 79                it knows where the data, but does not contain any data.
 80                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.hazelcast.use_lite_member">true</property>
 81]]></programlisting>
 82            </para>
 83        </listitem>
 84        <listitem>
 85            <para>You can set up Hazelcast to connect cluster as Native Client. Native client is not
 86                member and it connects to one of the cluster members and delegates all cluster wide
 87                operations to it. When the relied cluster member dies, client will transparently
 88                switch to another live member. <emphasis role="italic">(Native Client property takes precedence
 89                    over LiteMember property.)</emphasis>
 90                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.hazelcast.use_native_client">true</property>
 91]]></programlisting>
 92                To setup Native Client properly, you should add Hazelcast 
 93                <emphasis role="bold">group-name</emphasis>, 
 94                <emphasis role="bold">group-password</emphasis> and
 95                <emphasis role="bold">cluster member address</emphasis> properties. 
 96                Native Client
 97                will connect to defined member and will get addresses of all members in the cluster.
 98                If the connected member will die or leave the cluster, client will automatically
 99                switch to another member in the cluster.
100                <programlisting language="xml"><![CDATA[<property name="hibernate.cache.hazelcast.native_client_address">10.34.22.15</property>
101<property name="hibernate.cache.hazelcast.native_client_group">dev</property>
102<property name="hibernate.cache.hazelcast.native_client_password">dev-pass</property>
103]]></programlisting>
104                <emphasis role="italic">To use Native Client you should add
105                    <literal>hazelcast-client-&lt;version&gt;.jar</literal>
106                    into your
107                    classpath.
108                </emphasis>
109            </para>
110            <para>
111                <link xlink:href="#NativeClient">Read more about NativeClient &amp; LiteMember</link>
112            </para>
113        </listitem>
114        <listitem>
115            <para>If you are using one of Hibernate pre-3.3 version, add following property.
116                <programlisting language="xml">
117<![CDATA[<property name="hibernate.cache.provider_class">
118     com.hazelcast.hibernate.provider.HazelcastCacheProvider
119</property>]]>
120				</programlisting>
121            </para>
122        </listitem>
123        <listitem>
124            <para>If you are using Hibernate 3.3.x (or newer) version, you can choose to use either
125                configuration property above (Hibernate has a built-in bridge to use old-style cache
126                implementations) or following property.
127                <programlisting language="xml">
128<![CDATA[<property name="hibernate.cache.region.factory_class">
129     com.hazelcast.hibernate.HazelcastCacheRegionFactory
130</property>]]>
131				</programlisting>
132
133                Or as an alternative you can use <code>HazelcastLocalCacheRegionFactory</code>
134                which stores data in local node and sends invalidation messages when an entry is updated on local.
135                <programlisting language="xml">
136<![CDATA[<property name="hibernate.cache.region.factory_class">
137     com.hazelcast.hibernate.HazelcastLocalCacheRegionFactory
138</property>]]>
139                </programlisting>
140            </para>
141        </listitem>
142    </itemizedlist>
143    Hazelcast creates a separate distributed map for each Hibernate cache region. So
144    these regions can be configured easily via Hazelcast map configuration. You can define 
145    <emphasis role="bold">backup</emphasis>,
146    <emphasis role="bold">eviction</emphasis>,
147    <emphasis role="bold">TTL</emphasis> and
148    <emphasis role="bold">Near Cache</emphasis> properties.
149    <itemizedlist>
150        <listitem>
151            <para>
152                <link xlink:href="#MapBackup">Backup Configuration</link>
153            </para>
154        </listitem>
155        <listitem>
156            <para>
157                <link xlink:href="#MapEviction">Eviction And TTL Configuration</link>
158            </para>
159        </listitem>
160        <listitem>
161            <para>
162                <link xlink:href="#MapNearCache">Near Cache Configuration</link>
163            </para>
164        </listitem>
165    </itemizedlist>
166    Hibernate has four cache concurrency strategies:
167    <emphasis>read-only</emphasis>, 
168    <emphasis>read-write</emphasis>, 
169    <emphasis>nonstrict-read-write</emphasis> and
170    <emphasis>transactional</emphasis>. 
171    But Hibernate does not forces cache providers to support all strategies. And Hazelcast supports
172    first three (<emphasis role="bold">read-only</emphasis>, 
173    	<emphasis role="bold">read-write</emphasis>, 
174    	<emphasis role="bold">nonstrict-read-write</emphasis>) of these four strategies. 
175    	Hazelcast has no support for<emphasis>transactional</emphasis> strategy yet.
176    <itemizedlist>
177        <listitem>
178            <para>If you are using xml based class configurations, you should add a
179                <emphasis>cache</emphasis> element into your configuration with
180                <emphasis>usage</emphasis> attribute with one of 
181                <emphasis>read-only</emphasis>, 
182                <emphasis>read-write</emphasis>, 
183                <emphasis>nonstrict-read-write</emphasis>.
184                <programlisting language="xml"><![CDATA[<class name="eg.Immutable" mutable="false">
185    <cache usage="read-only"/>
186    .... 
187</class>
188
189<class name="eg.Cat" .... >
190    <cache usage="read-write"/>
191    ....
192    <set name="kittens" ... >
193        <cache usage="read-write"/>
194        ....
195    </set>
196</class>
197]]></programlisting>
198            </para>
199        </listitem>
200        <listitem>
201            <para>If you are using Hibernate-Annotations then you can add
202                <emphasis>class-cache</emphasis> or
203                <emphasis>collection-cache</emphasis> element into your Hibernate configuration file with
204                <emphasis>usage</emphasis> attribute with one of 
205                <emphasis>read only</emphasis>,
206                <emphasis>read/write</emphasis>,
207                <emphasis>nonstrict read/write</emphasis>.
208                <programlisting language="xml"><![CDATA[<class-cache usage="read-only" class="eg.Immutable"/>
209<class-cache usage="read-write" class="eg.Cat"/>
210<collection-cache collection="eg.Cat.kittens" usage="read-write"/>
211]]></programlisting>
212            </para>
213        </listitem>
214    </itemizedlist>
215    OR
216    <itemizedlist>
217        <listitem>
218            <para>Alternatively, you can put Hibernate Annotation's
219                <emphasis>@Cache</emphasis>
220                annotation on your entities and collections.
221                <programlisting language="java"><![CDATA[@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
222public class Cat implements Serializable {
223     ...
224}
225]]></programlisting>
226            </para>
227        </listitem>
228    </itemizedlist>
229    The last thing you should be aware of is to drop
230    hazelcast-hibernate-&lt;version&gt;.jar into your classpath.
231
232    <itemizedlist>
233        <title>Additional Properties:</title>
234        <listitem>
235            <para>
236                <emphasis role="bold">Accessing underlying
237                    <code>HazelcastInstance</code>
238                </emphasis>
239            </para>
240            <para>Using
241                <code>com.hazelcast.hibernate.instance.HazelcastAccessor</code>
242                you can access the underlying
243                <code>HazelcastInstance</code>
244                used by Hibernate SessionFactory.
245                <programlisting language="java"><![CDATA[SessionFactory sessionFactory = ...;
246HazelcastInstance hazelcastInstance = HazelcastAccessor.getHazelcastInstance(sessionFactory);        
247]]></programlisting>
248            </para>
249        </listitem>
250
251        <listitem>
252            <para>
253                <emphasis role="bold">Changing/setting lock timeout value of
254                    <emphasis role="italic">read-write</emphasis>
255                    strategy
256                </emphasis>
257            </para>
258            <para>Lock timeout value can be set using
259                <literal>hibernate.cache.hazelcast.lock_timeout</literal>
260                Hibernate property.
261                Value should be in milliseconds and default value is 10000 ms (10 seconds).
262            </para>
263        </listitem>
264
265        <listitem>
266            <para>
267                <emphasis role="bold">Using named
268                    <literal>HazelcastInstance</literal>
269                </emphasis>
270            </para>
271            <para>
272            	Instead of creating a new <literal>HazelcastInstance</literal> for each <literal>SessionFactory</literal>,
273                an existing instance can be used by setting
274                <literal>hibernate.cache.hazelcast.instance_name</literal>
275                Hibernate property to <literal>HazelcastInstance</literal>'s name.
276                For more information see <link xlink:href="#NamedHazelcastInstance">Named HazelcastInstance</link>.
277            </para>
278        </listitem>
279
280        <listitem>
281            <para>
282                <emphasis role="bold">Disabling shutdown during SessionFactory.close()</emphasis>
283            </para>
284            <para>Shutting down
285                <literal>HazelcastInstance</literal>
286                can be disabled during
287                <code>SessionFactory.close()</code>
288                by setting
289                <literal>hibernate.cache.hazelcast.shutdown_on_session_factory_close</literal>
290                Hibernate property to false.
291                <emphasis role="italic">(In this case Hazelcast property
292                    <literal>hazelcast.shutdownhook.enabled</literal>
293                    should not
294                    be set to false.)
295                </emphasis>
296                Default value is <literal>true</literal>.
297            </para>
298        </listitem>
299    </itemizedlist>
300    </para>
301</simplesect>