hazelcast · amandalindsay · Jan 30, 2025 · Jan 7, 2025 · Jan 8, 2025 · Jan 9, 2025
@@ -467,22 +467,6 @@
 ** xref:osgi:design.adoc[]
 ** xref:osgi:using-osgi-service.adoc[]
 
-.Clients and APIs
-// Clients
-* xref:clients:java.adoc[]
-* xref:clients:dotnet.adoc[]
-* xref:clients:python.adoc[]
-* xref:clients:cplusplus.adoc[]
-* xref:clients:go.adoc[]
-* xref:clients:nodejs.adoc[]
-* xref:clients:memcache.adoc[]
-// REST API
-* xref:maintain-cluster:enterprise-rest-api.adoc[]
-** xref:getting-started:get-started-rest-api-with-docker.adoc[Get started using Docker]
-** xref:getting-started:get-started-rest-api-with-java.adoc[Get started using Java]
-** xref:maintain-cluster:rest-api-swagger.adoc[]
-** xref:maintain-cluster:dynamic-config-via-rest.adoc[Dynamic configuration tutorial]
-
 .Connectors
 // Connectors overview
 * xref:integrate:connectors.adoc[Overview]
@@ -521,6 +505,23 @@
 ** xref:integrate:http-connector.adoc[]
 ** xref:integrate:influxdb-connector.adoc[]
 
+.Clients and APIs
+* xref:clients:client-overview.adoc[Overview]
+* Clients
+** xref:clients:java.adoc[]
+** xref:clients:dotnet.adoc[]
+** xref:clients:python.adoc[]
+** xref:clients:cplusplus.adoc[]
+** xref:clients:go.adoc[]
+** xref:clients:nodejs.adoc[]
+* APIs
+** xref:maintain-cluster:enterprise-rest-api.adoc[]
+*** xref:getting-started:get-started-rest-api-with-docker.adoc[Get started using Docker]
+*** xref:getting-started:get-started-rest-api-with-java.adoc[Get started using Java]
+*** xref:maintain-cluster:rest-api-swagger.adoc[]
+*** xref:maintain-cluster:dynamic-config-via-rest.adoc[Dynamic configuration tutorial]
+** xref:clients:memcache.adoc[Memcache]
+
 .Frameworks and plugins
 // Spring
 * xref:spring:overview.adoc[]

@@ -0,0 +1,82 @@
+= Overview
+:description: Overview of the main Hazelcast clients and APIs
+
+Hazelcast clients and programming language APIs allow you to extend the benefits of operational in-memory computing to applications in these languages.
+
+This topic explains how we use these terms and discusses the pros and cons of using clients or APIs.
+
+NOTE: Not all features are available in every client. For an overview of what each client offers, 
+see the link:https://hazelcast.com/developers/clients/?utm_source=docs-website[clients page].
+
+== Use a Client or API?
+
+Hazelcast provides clients and programming language APIs to interact with Hazelcast clusters and leverage their distributed computing capabilities. The choice between using a client or an API depends on your specific use case, performance requirements, and the programming languages you're using in your project. The following examines the key differences and considerations.
+
+NOTE: *Clients* refer to the Hazelcast _libraries_ used to connect to a Hazelcast cluster and exchange data. Clients use a binary protocol for communication with the cluster and encode the data in various formats such as Compact, JSON, etc. Clients are available in various programming languages. 
+*APIs*, by comparison, are the _interfaces_ with the Hazelcast platform. These do not require the use of specific libraries to connect and are generally text based — for example, the REST interface.
+
+=== Clients
+
+Hazelcast clients must be installed locally to communicate with the server.
+
+==== Benefits of using Hazelcast clients
+
+* Language flexibility: Hazelcast offers clients in multiple programming languages, allowing you to use Hazelcast in various environments. 
+Clients are available for xref:java.adoc[Java], xref:dotnet.adoc[.NET], xref:python.adoc[Python], xref:cplusplus.adoc[C++], xref:go.adoc[Go], and xref:nodejs.adoc[Node.js]
+* Independent scaling: in client/server mode, you can scale the Hazelcast cluster independently from your application. For details, see: https://docs.hazelcast.com/hazelcast/latest/deploy/choosing-a-deployment-option[Choosing an Application Topology]
+* Polyglot applications: client/server mode allows you to write polyglot applications that can all connect to the same cache cluster
+* Decoupling application from data: the application and cached data are separated, which can be beneficial for management and security purposes
+
+==== Disadvantages
+
+* More complex setup: client/server mode requires setting up and managing a separate Hazelcast cluster, which can be more complex than embedding Hazelcast directly in your application
+
+==== Maximum number of client connections per member
+
+The maximum recommended number of clients per member is 100.
+By default, members have `core count * 20` threads that handle all the requests.
+For example, if a member has 4 cores, it will have 80 threads available to handle requests.
+
+==== Serialization in client/server mode
+
+In xref:deploy:choosing-a-deployment-option.adoc[client/server topologies], you can serialize your data
+on the client side before sending it to a member. For example, you can serialize data in
+Kryo and add it to a map. This option is useful if you plan on using Hazelcast to store your
+data in binary. The serialization can be handled on the client-side without the members needing to know how to do so.
+
+For details about why you need to serialize data and the options for doing so, see xref:serialization:serialization.adoc[Serialization].
+
+=== APIs
+
+If you do not want to use a client, you can use APIs to configure Hazelcast in embedded mode, where Hazelcast members run in the same Java process as your application. 
+
+APIs are server-side and do not require to be installed. Instead, you simply enable the API on the cluster, and this allows you to be serverless.
+
+==== Benefits of using APIs
+
+* Lower latency: for data kept in the embedded member, embedded mode offers faster data access because applications do not need to send requests to the cache cluster over the network
+* Simplicity: for Java applications, embedded mode is simpler to set up and use, because you only need to add the Hazelcast JAR to your classpath
+
+==== Disadvantages
+
+* Permissions (such as for IMap read/write) cannot be enforced so the embedded member has access to everything
+* Limited to Java: embedded mode is only available for Java applications, limiting its use in other programming environments
+* Coupled scaling: in embedded mode, the application and the cluster must be scaled together, which may not be ideal for all use cases
+* Less flexibility: each instance of your application starts a Hazelcast member, which may lead to unnecessary cluster members if you don't need them. 
+However, you can avoid this by creating a member only when necessary
+
+NOTE: Hazelcast offers a xref:clients:java.adoc#configuring-client-near-cache[Near Cache] feature for clients which can reduce latency in client/server mode by storing frequently used data in the client's local memory.
+
+== Next steps
+
+For detailed information and code samples for each client, see:
+
+* xref:java.adoc[Java]
+* xref:dotnet.adoc[.NET]
+* xref:python.adoc[Python]
+* xref:cplusplus.adoc[C++]
+* xref:go.adoc[Go]
+* xref:nodejs.adoc[Node.js]
+
+For details about using Memcache to communicate directly with a Hazelcast cluster, see xref:memcache.adoc[Memcache].
+For information about using the REST API for simple operations, see: xref:rest.adoc[REST].
@@ -6,8 +6,8 @@ TIP: For the latest {cpp} API documentation, see http://hazelcast.github.io/haze
 
 The Hazelcast native {cpp} client is an official library that allows {cpp} applications to connect to and interact with Hazelcast clusters. The key features and benefits include:
 
-* Distributed Data Structures: The client offers access to various distributed data structures such as Map, Queue, Set, List, MultiMap, and RingBuffer. It also gives access to transactional distributed data structures such as transactional_map, transactional_queue, etc.
-* Near Cache Support: The Near Cache feature allows frequently read data to be stored for faster read speeds compared to traditional caches
+* Distributed Data Structures: the client offers access to various distributed data structures such as Map, Queue, Set, List, MultiMap, and RingBuffer. It also gives access to transactional distributed data structures such as transactional_map, transactional_queue, etc.
+* Near Cache Support: the Near Cache feature allows frequently read data to be stored for faster read speeds compared to traditional caches
 * Enterprise-Level security: the client provides SSL support for enhanced security requirements
 * Distributed synchronization: the client offers distributed synchronization mechanisms through the CP Subsystem, including fenced_lock, counting_semaphore and latch
 * Smart Client functionality: by default, it operates as a smart client, meaning it knows the data location within the cluster and can directly request the correct member (note that you can disable this feature using the `client_config::set_smart_routing` method if you do not want the clients to connect to every member)

@@ -7,13 +7,13 @@ TIP: For the latest .NET API documentation, see http://hazelcast.github.io/hazel
 
 The Hazelcast native .NET client is an official library that allows .NET applications to connect to and interact with Hazelcast clusters. The key features and benefits include:
 
-* Distributed Data Structures: It provides access to Hazelcast's distributed data structures such as maps, queues, topics, and more
-* SQL Support: The client allows running SQL queries over distributed data
-* Near Cache: It supports Near Cache for faster read speeds. Eventual consistency is also supported
-* Security Features: The client offers SSL support and Mutual Authentication for enterprise-level security needs
-* JSON Object Support: It allows using and querying JSON objects
+* Distributed Data Structures: it provides access to Hazelcast's distributed data structures such as maps, queues, topics, and more
+* SQL Support: ihe client allows running SQL queries over distributed data
+* Near Cache: it supports Near Cache for faster read speeds. Eventual consistency is also supported
+* Security Features: the client offers SSL support and Mutual Authentication for enterprise-level security needs
+* JSON Object Support: it allows using and querying JSON objects
 * Zero Downtime Upgrades: Blue/Green failover for zero downtime during upgrades is supported
-* Scalability: The Hazelcast .NET Client is designed to scale up to hundreds of members and thousands of clients, making it suitable for large-scale applications
+* Scalability: the Hazelcast .NET Client is designed to scale up to hundreds of members and thousands of clients, making it suitable for large-scale applications
 
 These features make the Hazelcast .NET Client ideal for .NET applications requiring high-performance, scalable, and distributed data processing capabilities.
 

@@ -5,12 +5,12 @@ TIP: For the latest Go API documentation, see https://pkg.go.dev/github.com/haze
 
 The Hazelcast native Go client is an official library that allows Go applications to connect to and interact with Hazelcast clusters. It is implemented using the Hazelcast Open Binary Client Protocol. The key features and benefits include:
 
-* Distributed Data Structures: Supports various distributed implementations like Map, Queue, Set, List, MultiMap, and Replicated Map, mimicking natural interfaces of these structures in Go
-* SQL Support: Allows running SQL queries on Hazelcast 5.x clusters, enhancing data querying capabilities
-* JSON Support: Declarative configuration support via JSON
-* High Performance: Offers high-performance aggregation functions such as sum, average, max, and min, for Hazelcast Map entries. They can run in parallel for each partition and are highly optimized for speed and low-memory consumption
-* Near Cache: Improves read performance for frequently accessed data, optimizing application speed
-* External Smart Client Discovery: Allows for dynamic discovery of cluster members, enhancing scalability and fault tolerance
+* Distributed Data Structures: supports various distributed implementations like Map, Queue, Set, List, MultiMap, and Replicated Map, mimicking natural interfaces of these structures in Go
+* SQL Support: allows running SQL queries on Hazelcast 5.x clusters, enhancing data querying capabilities
+* JSON Support: declarative configuration support via JSON
+* High Performance: offers high-performance aggregation functions such as sum, average, max, and min, for Hazelcast Map entries. They can run in parallel for each partition and are highly optimized for speed and low-memory consumption
+* Near Cache: improves read performance for frequently accessed data, optimizing application speed
+* External Smart Client Discovery: allows for dynamic discovery of cluster members, enhancing scalability and fault tolerance
 
 The Hazelcast Go client provides a robust, efficient, and Go-friendly way to work with Hazelcast clusters, enabling developers to build scalable and distributed applications with ease.
 

@@ -1,9 +1,9 @@
 = Getting Started with a Hazelcast Client
-:description: Hazelcast has clients in Java, .NET, Python, C++, Go, Node.js and Memcache. You can use these clients to communicate with cluster members.
-:page-aliases: clc.adoc, ROOT:management-center.adoc
+:description: Hazelcast has clients in Java, .NET, Python, C++, Go, and Node.js. You can use these clients to communicate with cluster members.
 
 {description}
 
+For an overview of available clients, see xref:client-overview.adoc[].   
 For documentation and code samples for each client, see the following:
 
 * xref:java.adoc[Java]
@@ -12,38 +12,11 @@ For documentation and code samples for each client, see the following:
 * xref:cplusplus.adoc[C++]
 * xref:go.adoc[Go]
 * xref:nodejs.adoc[Node.js]
-* xref:memcache.adoc[Memcache]
 
-You can also check out the REST API for simple operations:
-
-* xref:rest.adoc[REST]
+Alternatively, you can use xref:memcache.adoc[Memcache] to communicate directly with a Hazelcast cluster, or use the xref:rest.adoc[REST] API for simple operations. 
 
 Additional tools are available to help operate and manage Hazelcast Platform clusters:
+
 * link:https://docs.hazelcast.com/management-center/latest/getting-started/overview[Management Center]
 * link:https://docs.hazelcast.com/operator/latest/[Platform Operator]
 * link:https://docs.hazelcast.com/clc/latest/overview[Command Line Client (CLC)]
-
-== Feature Comparison for Hazelcast Clients
-
-Not all features are available in all clients.
-
-To find out which features are available in each client,
-see the link:https://hazelcast.com/developers/clients/?utm_source=docs-website[clients page].
-
-After selecting the language you need, you can find the table showing supported features on the selected language.
-
-== Maximum Number of Client Connections Per Member
-
-The maximum recommended number of clients per member is 100.
-By default, members have `core count * 20` threads that handle all the requests.
-For example, if a member has 4 cores, it will have 80 threads available to handle requests.
-
-== Serialization in Client/Server Mode
-
-In xref:deploy:choosing-a-deployment-option.adoc[client/server topologies], you can serialize your data
-on the client side before sending it to a member. For example, you can serialize data in
-JSON and add it to a map. This option is useful if you plan on using Hazelcast to store your
-data in binary. Clients can handle serialization without the members needing to know how to do so.
-
-For details about why you need to serialize data and the options for doing so, see xref:serialization:serialization.adoc[Serialization].
-
@@ -7,15 +7,17 @@
 
 == Overview
 
-Hazelcast provides a {java-client} which you can use to connect to a Hazelcast cluster. `hazelcast-<VERSION>.jar` is bundled in the Hazelcast standard package, so just add `hazelcast-<VERSION>.jar` to your classpath and you can start using this client as if you are using the Hazelcast API.
+This topic is aimed at developers and describes basic usage, configuration, and advanced features.
 
-If you are interested in using a standalone or lightweight Java client, you can try the {java-client-new}. This client is currently available as Beta functionality but can interact with a Hazelcast cluster without being a full member. Please note that the {java-client-new} doesn't have full feature parity with the {java-client} yet and is not recommended for production environments. For more info, see xref:java#java-client-standalone-beta[].
+Hazelcast provides a {java-client} which you can use to connect to a Hazelcast cluster. `hazelcast-<VERSION>.jar` is bundled in the Hazelcast standard package, so you simply add this file to your classpath to begin using the client as if you are using the Hazelcast API.
 
-NOTE: Where there are specific differences between {java-client} and {java-client-new}, this documentation will specify the appropriate client. Otherwise you can assume that generic references to client refer to both versions of the Java client.
+Alternatively, if you want to use a standalone or lightweight Java client, you can try the {java-client-new}. This client is currently available as Beta functionality but can interact with a Hazelcast cluster without being a full member. Note that the {java-client-new} doesn't have full feature parity with the {java-client} yet and is not recommended for production environments. For more information, see xref:java#java-client-standalone-beta[].
+
+NOTE: Where there are differences between {java-client} and {java-client-new}, this documentation will specify the appropriate client. Otherwise, assume that generic references to client refer to both versions of the Java client.
 
 // check production recommendation
 
-Both clients enable you to use the Hazelcast API, with this page explaining any differences or technical details that affect usage. This page should be read alongside the respective Javadoc-generated API documentation available from within your IDE and the following links:
+Both clients enable you to use the Hazelcast API — this topic explains any differences or technical details that affect usage. Read this alongside the respective Javadoc-generated API documentation available from within your IDE together with the following:
 
 * https://docs.hazelcast.org/docs/{page-latest-supported-java-client}/javadoc[Hazelcast {java-client} API documentation]
 * https://docs.hazelcast.org/hazelcast-java-client/{page-latest-supported-java-client-new}/javadoc[Hazelcast {java-client-new} API documentation]
@@ -27,8 +29,7 @@ Both clients enable you to use the Hazelcast API, with this page explaining any
 
 === Get started with {java-client}
 
-To get started using the {java-client}, you need to include the `hazelcast.jar` dependency in your classpath. You can then start using this client as if
-you are using the Hazelcast API. 
+To get started using the {java-client}, you need to include the `hazelcast.jar` dependency in your classpath. You can then start using this client as if you are using the Hazelcast API. 
 
 NOTE: If you have a Hazelcast {enterprise-product-name} license, you don't need to set the license key in your Hazelcast Java clients to use the xref:getting-started:editions.adoc#features-in-hazelcast-enterprise[{enterprise-product-name} features]. You only have to set it on the member side, and include the `hazelcast-enterprise-<VERSION>.jar` dependency in your classpath.