PageRenderTime 24ms CodeModel.GetById 18ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/hazelcast-documentation/src/main/docbook/manual/content/misc/CommonGotchas.xml

https://bitbucket.org/gabral6_gmailcom/hazelcast
XML | 101 lines | 83 code | 3 blank | 15 comment | 0 complexity | 01ddae41f1d0b45056e5ceb2bc9146d6 MD5 | raw file
  1<?xml version='1.0' encoding='UTF-8'?>
  2<!--
  3  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  4  ~
  5  ~ Licensed under the Apache License, Version 2.0 (the "License");
  6  ~ you may not use this file except in compliance with the License.
  7  ~ You may obtain a copy of the License at
  8  ~
  9  ~ http://www.apache.org/licenses/LICENSE-2.0
 10  ~
 11  ~ Unless required by applicable law or agreed to in writing, software
 12  ~ distributed under the License is distributed on an "AS IS" BASIS,
 13  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  ~ See the License for the specific language governing permissions and
 15  ~ limitations under the License.
 16  -->
 17
 18<sect1 xml:id="CommonGotchas" version='5.0' xmlns='http://docbook.org/ns/docbook'
 19       xmlns:xi="http://www.w3.org/2001/XInclude"
 20       xmlns:xlink="http://www.w3.org/1999/xlink"
 21       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 22       xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
 23       http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">
 24    <title>Common Gotchas</title>
 25    <para>Hazelcast is the distributed implementation of several structures that exist in Java.
 26        Most of the time it behaves as you expect. However there are some design choices in
 27        Hazelcast that violate some contracts. This page will list those violations.
 28        <orderedlist>
 29            <listitem>
 30                <para>
 31                    <emphasis role="bold">equals() and hashCode() methods for the objects stored
 32                        in Hazelcast
 33                    </emphasis>
 34                </para>
 35                <para>When you store a key, value in a distributed Map, Hazelcast serializes the key
 36                    and value and stores the byte array version of them in local ConcurrentHashMaps.
 37                    And this ConcurrentHashMap uses the equals and hashCode methods of byte array
 38                    version of your key. So it does not take into account the actual equals and
 39                    hashCode implementations of your objects. So it is important that you choose
 40                    your keys in a proper way. Implementing the equals and hashCode is not enough,
 41                    it is also important that the object is always serialized into the same byte
 42                    array. All primitive types, like; String, Long, Integer and etc. are good
 43                    candidates for keys to use in Hazelcast. An unsorted Set is an example of a very
 44                    bad candidate because Java Serialization may serialize the same unsorted set in
 45                    two different byte arrays.
 46                </para>
 47                <para>Note that the distributed Set and List stores its entries as the keys in a
 48                    distributed Map. So the notes above apply to the objects you store in Set and
 49                    List.
 50                </para>
 51            </listitem>
 52
 53            <listitem>
 54                <para>
 55                    Hazelcast always return a clone copy of a value. Modifying the returned value does not change
 56                    the actual value in the map (or multimap or list or set).
 57                    You should put modified value back to make changes visible to all nodes.
 58                    <programlisting language="java"><![CDATA[
 59V value = map.get(key);
 60value.updateSomeProperty();
 61map.put(key, value);
 62]]></programlisting>
 63                    If <code>cache-value</code> is true (default is true), Hazelcast caches that returned value
 64                    for fast access in local node. Modifications done to this cached value without
 65                    putting it back to map will be visible to only local node, successive <code>get</code> calls will
 66                    return the same cached value.
 67                    To reflect modifications to distributed map, you should put modified value back into map.
 68                </para>
 69            </listitem>
 70
 71            <listitem>
 72                <para>
 73                    Collections which return values of methods such as <code>IMap.keySet</code>, <code>IMap.values</code>,
 74                    <code>IMap.entrySet</code>, <code>MultiMap.get</code>, <code>MultiMap.remove</code>,
 75                    <code>IMap.keySet</code>, <code>IMap.values</code>, contain cloned values. These collections are NOT
 76                    backup by related Hazelcast objects.
 77                    So changes to the these are <emphasis role="bold">NOT</emphasis> reflected in the originals, and vice-versa.
 78                </para>
 79            </listitem>
 80            <listitem>
 81                <para>
 82                    Most of the Hazelcast operations throw an <code>RuntimeInterruptedException</code>
 83                    (which is unchecked version of <code>InterruptedException</code>)
 84                    if a user thread is interrupted while waiting a response.
 85                    Hazelcast uses RuntimeInterruptedException to pass InterruptedException up through interfaces
 86                    that don't have InterruptedException in their signatures. Users should be able to catch and handle
 87                    <code>RuntimeInterruptedException</code> in such cases as if their threads are interrupted on
 88                    a blocking operation.
 89                </para>
 90            </listitem>
 91            <listitem>
 92                <para>
 93                    Some of Hazelcast operations can throw <code>ConcurrentModificationException</code> under transaction
 94                    while trying to acquire a resource, although operation signatures don't define such an exception.
 95                    Exception is thrown if resource can not be acquired in a specific time. Users should be able to catch
 96                    and handle <code>ConcurrentModificationException</code> while they are using Hazelcast transactions.
 97                </para>
 98            </listitem>
 99        </orderedlist>
100    </para>
101</sect1>