Add README instructions to examples [HZ-5257] (#1395)

ihsandemir · web-flow · commit 9fde6ad9a146 · 2026-01-16T12:05:13.000Z
Add README instructions to examples.
diff --git a/examples/README.md b/examples/README.md
@@ -73,4 +73,27 @@ This folder contains an extensive collection of Hazelcast C++ Client code sample
 
 See reference
 manual [Advanced Installation section](https://docs.hazelcast.com/hazelcast/latest/clients/cplusplus#advanced-installation)
-to build and run the examples.
+to build the examples (Basically, you use the `-DBUILD_EXAMPLES=ON` flag for cmake).
+
+In order to run the examples, you need to have a Hazelcast cluster
+running. You can either use a local Hazelcast cluster or a Hazelcast
+Cloud cluster. For local Hazelcast cluster, you can follow the instructions
+in the [Start a Local Cluster in Docker](https://docs.hazelcast.com/hazelcast/latest/getting-started/get-started-docker)
+to set up a Hazelcast cluster on your local machine.
+
+Some examples may require Enterprise features. In that case, you need to have a Hazelcast
+Enterprise cluster running. For local Hazelcast Enterprise cluster,
+you can follow the instructions in
+the [Get started with Hazelcast Enterprise Edition](https://docs.hazelcast.com/hazelcast/latest/getting-started/get-started-enterprise)
+to set up a Hazelcast Enterprise cluster on your local machine.
+
+Some examples may require additional configuration on the server side. The server configuration xml files are provided
+in the respective example folders. You can use these configuration files when starting the Hazelcast server instances.
+
+Once you have a Hazelcast cluster running, you can run the examples which you already built as described above. The
+built example binaries are located in the `<BUILD_FOLDER_PATH>/examples/` folder. Navigate to the respective example
+folder and run the example binary. You can also see the example binary name in the CMakeLists.txt file located at
+the respective example folder.
+
+In order to run some of the examples, you may need to provide the additional jar files at the server classpath. The
+required jar files are mentioned in the respective example README files.
diff --git a/examples/authentication/README.md b/examples/authentication/README.md
diff --git a/examples/backpressure/README.md b/examples/backpressure/README.md
@@ -1,13 +1,5 @@
 # enableBackPressure
 
-- Start server:
-
-```bash
-java -Dhazelcast.config=examples/backpressure/hazelcast-backpressure.xml -cp hazelcast-enterprise-<SERVER VERSION>.jar:hazelcast-<SERVER VERSION>-tests.jar com.hazelcast.core.server.HazelcastMemberStarter    
-```
-
-- Run client test:
-
-```bash
-./build/examples/backpressure/enableBackPressure 
-```
+Please add the hazelcast test jar into server classpath to run this example. E.g. hazelcast-<SERVER VERSION>-tests.jar
+You can obtain the test jar from the Maven repository:
+https://repo1.maven.org/maven2/com/hazelcast/hazelcast/<SERVER VERSION>/hazelcast-<SERVER VERSION>-tests.jar
diff --git a/examples/client-statistics/README.md b/examples/client-statistics/README.md
@@ -1,19 +1,7 @@
-# Client Statistics Example
+# clientStatistics
 
-- Start server:
-
-```bash
-java -jar hazelcast-<SERVER VERSION>.jar    
-```
-
-- Run client test:
-
-```bash
-./build/examples/client-statistics/clientStatistics 
-```
-
-- Management Center
-- Start MC using the instructions at https://docs.hazelcast.com/management-center/latest/getting-started/install
-- Open MC in your browser at http://localhost:8080
-- Connect to the Hazelcast cluster
-- Go to the "Clients" section and observe the client statistics being reported for the test client.
+You need to start the Hazelcast Management Center to see the client statistics(
+see [Install and start Management Center](https://docs.hazelcast.com/management-center/latest/getting-started/install)).
+You can see the details about
+client statistics
+at [View details about a connected client](https://docs.hazelcast.com/management-center/latest/clusters/clients#view-details-about-a-connected-client)
diff --git a/examples/cp/README.md b/examples/cp/README.md
@@ -0,0 +1,6 @@
+# CP Subsystem Examples
+
+This is an enterprise feature. Make sure you are running Hazelcast Enterprise Edition cluster to use these examples.
+
+You can find the detailed information about Hazelcast CP Subsystem and how to quick start
+at [Quickstart](https://docs.hazelcast.com/hazelcast/latest/cp-subsystem/configuration#quickstart).
diff --git a/examples/distributed-collections/blockingqueue/Consumer.cpp b/examples/distributed-collections/blockingqueue/Consumer.cpp
@@ -34,7 +34,6 @@ main()
         } else {
             std::cout << "Retrieved item is null." << std::endl;
         }
-        std::this_thread::sleep_for(std::chrono::seconds(5));
     }
     std::cout << "Consumer Finished!" << std::endl;
 
diff --git a/examples/distributed-collections/blockingqueue/README.md b/examples/distributed-collections/blockingqueue/README.md
@@ -0,0 +1,3 @@
+# Blocking Queue Example
+
+Make sure you start the consumer first to avoid losing messages.
diff --git a/examples/distributed-collections/itemlisteners/README.md b/examples/distributed-collections/itemlisteners/README.md
@@ -0,0 +1,3 @@
+# Item Listener Example
+
+Make sure that you start the listener first to avoid missing any events.
diff --git a/examples/distributed-map/basic/README.md b/examples/distributed-map/basic/README.md
@@ -0,0 +1,3 @@
+# IMap Basic Example
+
+Make sure you run the `fillmap` first to populate the map before running the printall.
diff --git a/examples/distributed-map/custom-attributes/README.md b/examples/distributed-map/custom-attributes/README.md
@@ -0,0 +1,4 @@
+# Custom Attributes Example
+
+Write the Java class corresponding to the Car class and put that class or jar (`<my_factory>.jar`) into the classpath
+when starting the server and also add a server config for adding the serializer factory to the server.
diff --git a/examples/distributed-map/custom-attributes/hazelcast-attributes.xml b/examples/distributed-map/custom-attributes/hazelcast-attributes.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright (c) 2008-2025, 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.
+  -->
+<hazelcast xmlns="http://www.hazelcast.com/schema/config"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="http://www.hazelcast.com/schema/config
+           http://www.hazelcast.com/schema/config/hazelcast-config-5.6.xsd">
+
+    <serialization>
+        <data-serializable-factories>
+            <data-serializable-factory factory-id="???">
+                com.hazelcast.client.test.MyIdentifiedDataSerializableFactory
+            </data-serializable-factory>
+        </data-serializable-factories>
+    </serialization>
+</hazelcast>
diff --git a/examples/distributed-map/entry-listener/README.md b/examples/distributed-map/entry-listener/README.md
@@ -0,0 +1,3 @@
+# IMap Entry Listener Example
+
+Please make sure to start the listener first to avoid missing any events.
diff --git a/examples/distributed-map/entry-processor/README.md b/examples/distributed-map/entry-processor/README.md
@@ -0,0 +1,4 @@
+# Entry Processor Example
+
+- Write the Java class corresponding to the `employee` class and put that class or jar (`<my_factory>.jar`) into the
+  classpath when starting the server and also add a server config for adding the serializer factory to the server.
diff --git a/examples/distributed-map/entry-processor/hazelcast-entry-processor.xml b/examples/distributed-map/entry-processor/hazelcast-entry-processor.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright (c) 2008-2025, 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.
+  -->
+<hazelcast xmlns="http://www.hazelcast.com/schema/config"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="http://www.hazelcast.com/schema/config
+           http://www.hazelcast.com/schema/config/hazelcast-config-5.6.xsd">
+
+    <serialization>
+        <data-serializable-factories>
+            <data-serializable-factory factory-id="???">
+                com.hazelcast.client.test.MyIdentifiedDataSerializableFactory
+            </data-serializable-factory>
+        </data-serializable-factories>
+    </serialization>
+</hazelcast>
diff --git a/examples/distributed-map/partitionaware/README.md b/examples/distributed-map/partitionaware/README.md
@@ -0,0 +1,5 @@
+# PartitionAware Example
+
+Write the Java class corresponding to the `PartitionAwareString` class and put that class or jar (`<my_factory>.jar`)
+into the classpath when starting the server and also add a server config for adding the serializer factory to the
+server.
diff --git a/examples/distributed-map/query/README.md b/examples/distributed-map/query/README.md
@@ -0,0 +1,5 @@
+# Query Example
+
+Write the Java class corresponding to the `employee`, `person`, `employee_entry_comparator`,
+`employee_entry_key_comparator` classes and put the classes or jar (`<my_factory>.jar`) into the classpath when
+starting the server and also add a server config for adding the serializer factory to the server.
diff --git a/examples/distributed-map/removeAll/README.md b/examples/distributed-map/removeAll/README.md
@@ -0,0 +1,4 @@
+# RemoveAll Example
+
+Write the Java class corresponding to the `Person`, class and put the class or jar (`<my_factory>.jar`) into the
+classpath when starting the server and also add a server config for adding the serializer factory to the server.
diff --git a/examples/distributed-topic/reliabletopic/README.md b/examples/distributed-topic/reliabletopic/README.md
@@ -0,0 +1,3 @@
+# ReliableTopic Example
+
+Make sure that you start the `rtSubscriber` first to avoid missing any events.
diff --git a/examples/replicated-map/entry-listener/README.md b/examples/replicated-map/entry-listener/README.md
@@ -0,0 +1,3 @@
+# ReplicatedMap EntryListener Example
+
+Make sure that you start the `ListeningMember` first to avoid missing any events.
diff --git a/examples/serialization/compact/README.md b/examples/serialization/compact/README.md
@@ -0,0 +1,5 @@
+# Compact Serialization Example
+
+Write the Java class corresponding to the `PersonDTO` class, it's serializer class and put that class or
+jar (`<my_factory>.jar`) into the classpath when starting the server and also add a server config for adding the
+serializer factory to the server.
diff --git a/examples/serialization/custom/README.md b/examples/serialization/custom/README.md
@@ -0,0 +1,5 @@
+# Custom Serialization Example
+
+Write the Java class corresponding to the `Person` class, it's serializer class and put that class or
+jar (`<my_factory>.jar`) into the classpath when starting the server and also add a server config for adding the
+serializer factory to the server.
diff --git a/examples/serialization/globalserializer/README.md b/examples/serialization/globalserializer/README.md
@@ -0,0 +1,5 @@
+# Global Serializer Example
+
+Write the Java class corresponding to the `MyGlobalSerializer` class and put that class or
+jar (`<my_factory>.jar`) into the classpath when starting the server and also add a server config for adding the
+serializer factory to the server.
diff --git a/examples/serialization/identified-data-serializable/README.md b/examples/serialization/identified-data-serializable/README.md
@@ -0,0 +1,5 @@
+# IdentifiedDataSerializable Example
+
+Write the Java class corresponding to the `Person` class, it's serializer class and put that class or
+jar (`<my_factory>.jar`) into the classpath when starting the server and also add a server config for adding the
+serializer factory to the server.
diff --git a/examples/serialization/portable/README.md b/examples/serialization/portable/README.md
@@ -0,0 +1,5 @@
+# Portable Serializer Example
+
+Write the Java class corresponding to the `Person` class, it's serializer class and put that class or
+jar (`<my_factory>.jar`) into the classpath when starting the server and also add a server config for adding the
+serializer factory to the server.
diff --git a/examples/sql/README b/examples/sql/README
@@ -6,3 +6,8 @@ hazelcast config xml file (or similarly with yaml or embedded server configurati
 ```
 
 A sample xml file is shared in this example folder.
+
+In order to run the portable example (`sql_query_with_portable`), you need to
+Write the Java class corresponding to the `Person` class, it's serializer class and put that class or
+jar (`<my_factory>.jar`) into the classpath when starting the server and also add a server config for adding the
+serializer factory to the server.
diff --git a/examples/sql/hazelcast-sql.xml b/examples/sql/hazelcast-sql.xml
@@ -1,4 +1,7 @@
-<hazelcast xmlns="http://www.hazelcast.com/schema/config">
+<hazelcast xmlns="http://www.hazelcast.com/schema/config"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="http://www.hazelcast.com/schema/config
+           http://www.hazelcast.com/schema/config/hazelcast-config-5.6.xsd">
 
     <jet enabled="true" />
 

Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,6 @@ main()`
`34`	`34`	`} else {`
`35`	`35`	`std::cout << "Retrieved item is null." << std::endl;`
`36`	`36`	`}`
`37`		`- std::this_thread::sleep_for(std::chrono::seconds(5));`
`38`	`37`	`}`
`39`	`38`	`std::cout << "Consumer Finished!" << std::endl;`
`40`	`39`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Blocking Queue Example`
	`2`	`+`
	`3`	`+Make sure you start the consumer first to avoid losing messages.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Item Listener Example`
	`2`	`+`
	`3`	`+Make sure that you start the listener first to avoid missing any events.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# IMap Basic Example`
	`2`	`+`
	`3`	+Make sure you run the `fillmap` first to populate the map before running the printall.