Introduce new client classes (#4355)

* Relax type checking for ClusterClientBuilder

* Add new classes

* Use INIT_NO_ERROR_PROPERTY constant from new class

* Deprecate old classes

* Deprecate public constructors in UnifiedJedis

* Add migration tests for JedisCluster constructors used by SDR, Conductor and other OSS projects

* Fix formatting and imports

* Replace usages of JedisPooled with RedisClient

* Rename "pooled" tests

* Deprecate JedisPool and JedisSentinelPool

Provide clear guidance which client class should be used instead.

* Replace JedisCluster with RedisClusterClient in tests

* Fix javadocs and enable formatter exclusion tags

* Fix modifiers order

* Fix cluster tests

* Update docs

* Use RedisClient in doctests

* resolve conflict after rebase

* Update src/main/java/redis/clients/jedis/RedisClient.java

Co-authored-by: Ivo Gaydazhiev <ivo.gaydazhiev@redis.com>

* Use RedisClient in PingStrategy

* Reformat

* Use lettuce-style factory methods

* Update examples

---------

Co-authored-by: ggivo <ivo.gaydazhiev@redis.com>

Author: uglide

README.md

@@ -66,10 +66,10 @@ Next, you'll need to connect to Redis. Consider installing a redis server with d
 docker run -p 6379:6379 -it redis:latest
 ```
 
-For many applications, it's best to use a connection pool. You can instantiate a JedisPooled like so:
+You can instantiate a RedisClient like so:
 
 ```java
-JedisPooled jedis = new JedisPooled("localhost", 6379);
+RedisClient jedis = RedisClient.builder().hostAndPort("localhost", 6379).build();
 ```
 
 Now you can send commands:
@@ -81,16 +81,16 @@ jedis.sadd("planets", "Venus");
 ## Connecting to a Redis cluster
 
 Jedis lets you connect to Redis Clusters, supporting the [Redis Cluster Specification](https://redis.io/topics/cluster-spec).
-To do this, you'll need to connect using `JedisCluster`. See the example below:
+To do this, you'll need to connect using `RedisClusterClient`. See the example below:
 
 ```java
 Set<HostAndPort> jedisClusterNodes = new HashSet<HostAndPort>();
 jedisClusterNodes.add(new HostAndPort("127.0.0.1", 7379));
 jedisClusterNodes.add(new HostAndPort("127.0.0.1", 7380));
-JedisCluster jedis = new JedisCluster(jedisClusterNodes);
+RedisClusterClient jedis = RedisClusterClient.builder().nodes(jedisClusterNodes).build();
 ```
 
-Now you can use the `JedisCluster` instance and send commands like you would with a standard pooled connection:
+Now you can use the `RedisClusterClient` instance and send commands like you would with a standard pooled connection:
 
 ```java
 jedis.sadd("planets", "Mars");

docs/advanced-usage.md

@@ -255,16 +255,16 @@ public class DockerNATMapper implements HostAndPortMapper {
 }
 ```
 
-Then, instantiate this class and pass it to the JedisCluster constructor:
+Then, instantiate this class and pass it to the RedisClusterClient builder:
 
 ```java
 Map<HostAndPort, HostAndPort> nodeMapping = new HashMap<>();
-nodeMapping.put(new HostAndPort("172.18.0.2", 6379), new HostAndPort("my-redis.example.com", 7001));  
+nodeMapping.put(new HostAndPort("172.18.0.2", 6379), new HostAndPort("my-redis.example.com", 7001));
 nodeMapping.put(new HostAndPort("172.18.0.3", 6379), new HostAndPort("my-redis.example.com", 7002));
 nodeMapping.put(new HostAndPort("172.18.0.4", 6379), new HostAndPort("my-redis.example.com", 7002));
 
 Set<HostAndPort> initialNodes = new HashSet<>();
-// seed node 
+// seed node
 initialNodes.add(new HostAndPort("my-redis.example.com", 7001));
 
 HostAndPortMapper mapper = new DockerNATMapper(nodeMapping);
@@ -275,10 +275,13 @@ JedisClientConfig jedisClientConfig = DefaultJedisClientConfig.builder()
         .hostAndPortMapper(mapper)
         .build();
 
-JedisCluster jedisCluster = new JedisCluster(initialNodes, jedisClientConfig);
+RedisClusterClient jedisCluster = RedisClusterClient.builder()
+        .nodes(initialNodes)
+        .clientConfig(jedisClientConfig)
+        .build();
 ```
 
-Now, when JedisCluster discovers a node at "172.18.0.2:6379", the mapper will translate it to "localhost:7001" before attempting to connect.
+Now, when RedisClusterClient discovers a node at "172.18.0.2:6379", the mapper will translate it to "localhost:7001" before attempting to connect.
 
 ### Implementing with a Lambda Expression
 Since HostAndPortMapper is a functional interface (it has only one abstract method), you can also provide the implementation more concisely using a lambda expression. This is often preferred for simpler, inline mapping logic.
@@ -300,7 +303,10 @@ JedisClientConfig jedisClientConfig = DefaultJedisClientConfig.builder()
         .hostAndPortMapper(mapper)
         .build();
 
-JedisCluster jedisCluster = new JedisCluster(initialNodes, jedisClientConfig);
+RedisClusterClient jedisCluster = RedisClusterClient.builder()
+        .nodes(initialNodes)
+        .clientConfig(jedisClientConfig)
+        .build();
 ```
 
 ## Miscellaneous 

docs/redisearch.md

@@ -4,20 +4,20 @@ To use RediSearch features with Jedis, you'll need to use an implementation of R
 
 ## Creating the RediSearch client
 
-Initializing the client with JedisPooled:
+Initializing the client with RedisClient:
 
 ```java
-JedisPooled client = new JedisPooled("localhost", 6379);
+RedisClient client = RedisClient.builder().hostAndPort("localhost", 6379).build();
 ```
 
-Initializing the client with JedisCluster:
+Initializing the client with RedisClusterClient:
 
 ```java
 Set<HostAndPort> nodes = new HashSet<>();
 nodes.add(new HostAndPort("127.0.0.1", 7379));
 nodes.add(new HostAndPort("127.0.0.1", 7380));
 
-JedisCluster client = new JedisCluster(nodes);
+RedisClusterClient client = RedisClusterClient.builder().nodes(nodes).build();
 ```
 
 ## Indexing and querying

docs/redisjson.md

@@ -9,20 +9,20 @@ Let's see how this works.
 
 ## Creating with RedisJSON client
 
-First, let's create a `JedisPooled` client instance:
+First, let's create a `RedisClient` client instance:
 
 ```java
-JedisPooled client = new JedisPooled("localhost", 6479);
+RedisClient client = RedisClient.builder().hostAndPort("localhost", 6479).build();
 ```
 
-Or, a `JedisCluster` client instance:
+Or, a `RedisClusterClient` client instance:
 
 ```java
 Set<HostAndPort> nodes = new HashSet<>();
 nodes.add(new HostAndPort("127.0.0.1", 7379));
 nodes.add(new HostAndPort("127.0.0.1", 7380));
 
-JedisCluster client = new JedisCluster(nodes);
+RedisClusterClient client = RedisClusterClient.builder().nodes(nodes).build();
 ```
 
 Now we can start working with JSON. For these examples, we'll be using [GSON](https://github.com/google/gson)

hbase-formatter.xml

@@ -16,7 +16,7 @@
 <setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_annotation" value="do not insert"/>
 <setting id="org.eclipse.jdt.core.formatter.blank_lines_before_field" value="0"/>
 <setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
-<setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="true"/>
 <setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_annotation_type_member_declaration" value="do not insert"/>
 <setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
 <setting id="org.eclipse.jdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>

src/main/java/redis/clients/jedis/Jedis.java

@@ -33,6 +33,62 @@
 import redis.clients.jedis.util.KeyValue;
 import redis.clients.jedis.util.Pool;
 
+/**
+ * Jedis is a lightweight Redis client that uses a single, non-pooled connection to Redis.
+ * <p>
+ * <b>Important:</b> For most production use cases, {@link RedisClient} is the recommended and
+ * preferred option. {@code RedisClient} provides connection pooling, better resource management,
+ * and improved performance for typical applications.
+ * </p>
+ * <p>
+ * <b>When to use Jedis:</b>
+ * </p>
+ * <ul>
+ * <li><b>Short-lived scripts or utilities:</b> When you need a simple, lightweight client for
+ * one-off operations or command-line tools.</li>
+ * <li><b>Testing and development:</b> For unit tests or local development where connection pooling
+ * overhead is unnecessary.</li>
+ * <li><b>Fine-grained connection control:</b> Advanced scenarios requiring explicit control over
+ * individual connections, such as managing connection lifecycle manually or implementing custom
+ * connection strategies.</li>
+ * <li><b>Single-threaded applications:</b> Applications that execute Redis commands sequentially
+ * from a single thread and don't benefit from connection pooling.</li>
+ * </ul>
+ * <p>
+ * <b>When to use RedisClient instead:</b>
+ * </p>
+ * <ul>
+ * <li><b>Production applications:</b> Any multi-threaded or high-throughput application should use
+ * {@link RedisClient} for its connection pooling capabilities.</li>
+ * <li><b>Web applications:</b> Server applications handling concurrent requests benefit from
+ * connection pooling to avoid connection overhead.</li>
+ * <li><b>Long-running services:</b> Applications that maintain persistent connections to Redis
+ * should use {@link RedisClient} for better resource management.</li>
+ * <li><b>Default choice:</b> If you're unsure which to use, choose {@link RedisClient}.</li>
+ * </ul>
+ * <p>
+ * <b>Usage example:</b>
+ * </p>
+ *
+ * <pre>
+ * {
+ *   &#64;code
+ *   // Simple usage for a short-lived operation
+ *   try (Jedis jedis = new Jedis("localhost", 6379)) {
+ *     jedis.set("key", "value");
+ *     String value = jedis.get("key");
+ *   }
+ * }
+ * </pre>
+ * <p>
+ * <b>Note:</b> Each {@code Jedis} instance maintains a single connection. For concurrent access
+ * from multiple threads, either use {@link RedisClient} with connection pooling, or create
+ * separate {@code Jedis} instances per thread (not recommended for production).
+ * </p>
+ *
+ * @see RedisClient for the recommended pooled client for production use
+ * @see JedisPool for legacy pooled connections (deprecated, use RedisClient instead)
+ */
 public class Jedis implements ServerCommands, DatabaseCommands, JedisCommands, JedisBinaryCommands,
     ControlCommands, ControlBinaryCommands, ClusterCommands, ModuleCommands, GenericControlCommands,
     SentinelCommands, CommandCommands,  Closeable {

src/main/java/redis/clients/jedis/JedisCluster.java

@@ -18,6 +18,14 @@
 import redis.clients.jedis.providers.ConnectionProvider;
 import redis.clients.jedis.util.JedisClusterCRC16;
 
+/**
+ * JedisCluster is a client for Redis Cluster deployments.
+ *
+ * @deprecated Use {@link RedisClusterClient} instead. RedisClusterClient provides the same functionality
+ *             with a cleaner API and simplified constructor options. For basic usage, simple
+ *             constructors are available. For advanced configuration, use {@link RedisClusterClient#builder()}.
+ */
+@Deprecated
 public class JedisCluster extends UnifiedJedis {
 
   public static final String INIT_NO_ERROR_PROPERTY = "jedis.cluster.initNoError";

src/main/java/redis/clients/jedis/JedisClusterInfoCache.java

@@ -31,7 +31,7 @@
 import redis.clients.jedis.exceptions.JedisException;
 import redis.clients.jedis.util.SafeEncoder;
 
-import static redis.clients.jedis.JedisCluster.INIT_NO_ERROR_PROPERTY;
+import static redis.clients.jedis.RedisClusterClient.INIT_NO_ERROR_PROPERTY;
 
 @Internal
 public class JedisClusterInfoCache {

src/main/java/redis/clients/jedis/JedisFactory.java

@@ -17,9 +17,19 @@
 import redis.clients.jedis.util.JedisURIHelper;
 
 /**
- * PoolableObjectFactory custom impl.
+ * PooledObjectFactory implementation for creating and managing {@link Jedis} instances in connection pools.
+ * <p>
+ * This factory is used internally by {@link JedisPool} and {@link JedisSentinelPool} to create, validate,
+ * and destroy pooled Jedis connections.
+ * </p>
+ *
+ * @deprecated JedisFactory is used exclusively with the deprecated {@link JedisPool} and {@link JedisSentinelPool}
+ *             classes. For modern Redis clients ({@link RedisClient}, {@link RedisSentinelClient}), the framework
+ *             uses {@link ConnectionFactory} internally, which manages {@link Connection} objects instead of
+ *             {@link Jedis} instances. There is no direct replacement for JedisFactory as connection management
+ *             is handled automatically by the new client architecture.
  */
-// Legacy
+@Deprecated
 public class JedisFactory implements PooledObjectFactory<Jedis> {
 
   private static final Logger logger = LoggerFactory.getLogger(JedisFactory.class);

src/main/java/redis/clients/jedis/JedisPool.java

@@ -15,7 +15,14 @@
 import redis.clients.jedis.util.JedisURIHelper;
 import redis.clients.jedis.util.Pool;
 
-// Legacy
+/**
+ * JedisPool is a pooled connection client for standalone Redis servers.
+ *
+ * @deprecated Use {@link RedisClient} instead. RedisClient provides the same functionality
+ *             with a cleaner API and simplified constructor options. For basic usage, simple
+ *             constructors are available. For advanced configuration, use {@link RedisClient#builder()}.
+ */
+@Deprecated
 public class JedisPool extends Pool<Jedis> {
 
   private static final Logger log = LoggerFactory.getLogger(JedisPool.class);