/hazelcast-documentation/src/main/docbook/manual/content/HibernateSecondLevelCache.xml
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-<version>.jar</literal> 106 into your 107 classpath. 108 </emphasis> 109 </para> 110 <para> 111 <link xlink:href="#NativeClient">Read more about NativeClient & 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-<version>.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>