Hazelcast Documentation version 3.6.7 Dec 08, 2016 2 In-Memory Data Grid - Hazelcast | Documentation: version 3.6.7 Publication date Dec 08, 2016 Copyright c 2016 Hazelcast, Inc. Permission to use, copy, modify and distribute this document for any purpose and without fee is hereby granted in perpetuity, provided that the above copyright notice and this paragraph appear in all copies. Contents 1 Preface 19 1.1 Hazelcast Editions............................................. 19 1.2 Hazelcast Architecture........................................... 19 1.3 Hazelcast Plugins.............................................. 19 1.4 Licensing.................................................. 19 1.5 Trademarks................................................. 20 1.6 Customer Support............................................. 20 1.7 Release Notes................................................ 20 1.8 Contributing to Hazelcast......................................... 20 1.9 Phone Home................................................ 20 1.10 Typographical Conventions........................................ 21 2 Document Revision History 23 3 Getting Started 25 3.1 Installation................................................. 25 3.1.1 Hazelcast.............................................. 25 3.1.2 Hazelcast Enterprise........................................ 25 3.1.3 Setting the License Key...................................... 26 3.1.4 Upgrading from 3.x........................................ 27 3.1.5 Upgrading from 2.x........................................ 28 3.2 Starting the Member and Client..................................... 30 3.3 Using the Scripts In The Package..................................... 31 3.4 Deploying On Amazon EC2........................................ 31 3.5 Deploying using Docker.......................................... 32 4 Hazelcast Overview 33 4.1 Sharding in Hazelcast........................................... 34 4.2 Hazelcast Topology............................................. 34 4.3 Why Hazelcast?............................................... 35 4.4 Data Partitioning.............................................. 36 4.4.1 How the Data is Partitioned.................................... 38 3 4 CONTENTS 4.4.2 Partition Table........................................... 38 4.4.3 Repartitioning........................................... 39 4.5 Use Cases.................................................. 39 4.6 Resources.................................................. 40 5 Understanding Configuration 41 5.1 Configuring Declaratively......................................... 41 5.1.1 Composing Declarative Configuration.............................. 42 5.2 Configuring Programmatically....................................... 43 5.3 Configuring with System Properties................................... 44 5.4 Configuring within Spring Context.................................... 45 5.5 Checking Configuration.......................................... 45 5.6 Using Wildcards.............................................. 45 5.7 Using Variables............................................... 46 6 Setting Up Clusters 49 6.1 Discovering Cluster Members....................................... 49 6.1.1 Discovering Members by Multicast................................ 49 6.1.2 Discovering Members by TCP................................... 50 6.1.3 Discovering Members within EC2 Cloud............................. 51 6.1.4 Discovering Members with jclouds................................ 52 6.2 Creating Cluster Groups.......................................... 55 6.3 Partition Group Configuration...................................... 56 6.4 Logging Configuration........................................... 57 6.5 Other Network Configurations....................................... 58 6.5.1 Public Address........................................... 59 6.5.2 Port................................................. 59 6.5.3 Outbound Ports.......................................... 60 6.5.4 Reuse Address........................................... 60 6.5.5 Join................................................. 61 6.5.6 Interfaces.............................................. 63 6.5.7 IPv6 Support............................................ 64 7 Distributed Data Structures 65 7.1 Map..................................................... 66 7.1.1 Getting a Map and Putting an Entry.............................. 66 7.1.2 Backing Up Maps......................................... 70 7.1.3 Evicting Map Entries....................................... 71 7.1.4 Setting In Memory Format.................................... 75 7.1.5 Using High-Density Memory Store with Map.......................... 75 7.1.6 Loading and Storing Persistent Data............................... 77 CONTENTS 5 7.1.7 Creating Near Cache for Map................................... 83 7.1.8 Locking Maps............................................ 85 7.1.9 Accessing Entry Statistics..................................... 88 7.1.10 Map Listener............................................ 88 7.1.11 Listening to Map Entries with Predicates............................ 88 7.1.12 Adding Interceptors........................................ 90 7.1.13 Preventing Out of Memory Exceptions.............................. 93 7.2 Queue.................................................... 95 7.2.1 Getting a Queue and Putting Items............................... 95 7.2.2 Creating an Example Queue.................................... 95 7.2.3 Setting a Bounded Queue..................................... 97 7.2.4 Queueing with Persistent Datastore............................... 98 7.2.5 Configuring Queue......................................... 99 7.3 MultiMap.................................................. 100 7.3.1 Getting a MultiMap and Putting an Entry........................... 100 7.3.2 Configuring MultiMap....................................... 101 7.4 Set...................................................... 102 7.4.1 Getting a Set and Putting Items................................. 102 7.4.2 Configuring Set........................................... 103 7.5 List..................................................... 103 7.5.1 Getting a List and Putting Items................................. 103 7.5.2 Configuring List.......................................... 104 7.6 Ringbuffer.................................................. 105 7.6.1 Getting a Ringbuffer and Reading Items............................. 105 7.6.2 Adding Items to a Ringbuffer................................... 105 7.6.3 IQueue vs. Ringbuffer....................................... 105 7.6.4 Configuring Ringbuffer Capacity................................. 106 7.6.5 Backing Up Ringbuffer....................................... 106 7.6.6 Configuring Ringbuffer Time To Live............................... 106 7.6.7 Setting Ringbuffer Overflow Policy................................ 106 7.6.8 Configuring Ringbuffer In-Memory Format........................... 107 7.6.9 Adding Batched Items....................................... 107 7.6.10 Reading Batched Items...................................... 107 7.6.11 Using Async Methods....................................... 108 7.6.12 Ringbuffer Configuration Examples................................ 109 7.7 Topic..................................................... 109 7.7.1 Getting a Topic and Publishing Messages............................ 109 7.7.2 Getting Topic Statistics...................................... 110 7.7.3 Understanding Topic Behavior.................................. 110 6 CONTENTS 7.7.4 Configuring Topic......................................... 111 7.8 Reliable Topic................................................ 112 7.8.1 Sample Reliable ITopic Code................................... 113 7.8.2 Slow Consumers.......................................... 113 7.8.3 Configuring Reliable Topic.................................... 113 7.9 Lock..................................................... 114 7.9.1 Using Try-Catch Blocks with Locks............................... 114 7.9.2 Releasing Locks with tryLock Timeout.............................. 114 7.9.3 Avoiding Waiting Threads with Lease Time........................... 115 7.9.4 Understanding Lock Behavior................................... 115 7.9.5 Synchronizing Threads with ICondition............................. 116 7.10 IAtomicLong................................................ 116 7.10.1 Sending Functions to IAtomicLong................................ 117 7.10.2 Executing Functions on IAtomicLong.............................. 117 7.10.3 Reasons to Use Functions with IAtomic............................. 118 7.11 ISemaphore................................................. 118 7.11.1 Controlling Thread Counts with Semaphore Permits...................... 118 7.11.2 Example Semaphore Code..................................... 118 7.11.3 Configuring Semaphore...................................... 119 7.12 IAtomicReference.............................................. 120 7.12.1 Sending Functions to IAtomicReference............................. 120 7.12.2 Using IAtomicReference...................................... 121 7.13 ICountDownLatch............................................. 121 7.13.1 Gate-Keeping Concurrent Activities............................... 121 7.13.2 Recovering From Failure...................................... 122 7.13.3 Using ICountDownLatch...................................... 122 7.14 IdGenerator................................................. 122 7.14.1