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

<sect1 xml:id="CommonGotchas" 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">
    <title>Common Gotchas</title>
    <para>Hazelcast is the distributed implementation of several structures that exist in Java.
        Most of the time it behaves as you expect. However there are some design choices in
        Hazelcast that violate some contracts. This page will list those violations.
        <orderedlist>
            <listitem>
                <para>
                    <emphasis role="bold">equals() and hashCode() methods for the objects stored
                        in Hazelcast
                    </emphasis>
                </para>
                <para>When you store a key, value in a distributed Map, Hazelcast serializes the key
                    and value and stores the byte array version of them in local ConcurrentHashMaps.
                    And this ConcurrentHashMap uses the equals and hashCode methods of byte array
                    version of your key. So it does not take into account the actual equals and
                    hashCode implementations of your objects. So it is important that you choose
                    your keys in a proper way. Implementing the equals and hashCode is not enough,
                    it is also important that the object is always serialized into the same byte
                    array. All primitive types, like; String, Long, Integer and etc. are good
                    candidates for keys to use in Hazelcast. An unsorted Set is an example of a very
                    bad candidate because Java Serialization may serialize the same unsorted set in
                    two different byte arrays.
                </para>
                <para>Note that the distributed Set and List stores its entries as the keys in a
                    distributed Map. So the notes above apply to the objects you store in Set and
                    List.
                </para>
            </listitem>

            <listitem>
                <para>
                    Hazelcast always return a clone copy of a value. Modifying the returned value does not change
                    the actual value in the map (or multimap or list or set).
                    You should put modified value back to make changes visible to all nodes.
                    <programlisting language="java"><![CDATA[
V value = map.get(key);
value.updateSomeProperty();
map.put(key, value);
]]></programlisting>
                    If <code>cache-value</code> is true (default is true), Hazelcast caches that returned value
                    for fast access in local node. Modifications done to this cached value without
                    putting it back to map will be visible to only local node, successive <code>get</code> calls will
                    return the same cached value.
                    To reflect modifications to distributed map, you should put modified value back into map.
                </para>
            </listitem>

            <listitem>
                <para>
                    Collections which return values of methods such as <code>IMap.keySet</code>, <code>IMap.values</code>,
                    <code>IMap.entrySet</code>, <code>MultiMap.get</code>, <code>MultiMap.remove</code>,
                    <code>IMap.keySet</code>, <code>IMap.values</code>, contain cloned values. These collections are NOT
                    backup by related Hazelcast objects.
                    So changes to the these are <emphasis role="bold">NOT</emphasis> reflected in the originals, and vice-versa.
                </para>
            </listitem>
            <listitem>
                <para>
                    Most of the Hazelcast operations throw an <code>RuntimeInterruptedException</code>
                    (which is unchecked version of <code>InterruptedException</code>)
                    if a user thread is interrupted while waiting a response.
                    Hazelcast uses RuntimeInterruptedException to pass InterruptedException up through interfaces
                    that don't have InterruptedException in their signatures. Users should be able to catch and handle
                    <code>RuntimeInterruptedException</code> in such cases as if their threads are interrupted on
                    a blocking operation.
                </para>
            </listitem>
            <listitem>
                <para>
                    Some of Hazelcast operations can throw <code>ConcurrentModificationException</code> under transaction
                    while trying to acquire a resource, although operation signatures don't define such an exception.
                    Exception is thrown if resource can not be acquired in a specific time. Users should be able to catch
                    and handle <code>ConcurrentModificationException</code> while they are using Hazelcast transactions.
                </para>
            </listitem>
        </orderedlist>
    </para>
</sect1>