Add Experimental, Internal and VisibleForTesting annotations (#3790)

* Add Experimental, Internal and VisibleForTesting annotations

* Use VisibleForTesting annotation

* Use Internal annotation

* Use Experimental annotation

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

@@ -11,22 +11,26 @@
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Set;
+
 import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.locks.Lock;
 import java.util.concurrent.locks.ReentrantLock;
 import java.util.concurrent.locks.ReentrantReadWriteLock;
-import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
 
+import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+
+import redis.clients.jedis.annots.Internal;
 import redis.clients.jedis.exceptions.JedisClusterOperationException;
 import redis.clients.jedis.exceptions.JedisException;
 import redis.clients.jedis.util.SafeEncoder;
 
 import static redis.clients.jedis.JedisCluster.INIT_NO_ERROR_PROPERTY;
 
+@Internal
 public class JedisClusterInfoCache {
 
   private static final Logger logger = LoggerFactory.getLogger(JedisClusterInfoCache.class);

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

@@ -7,6 +7,7 @@
 import java.util.Arrays;
 import java.util.List;
 
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.exceptions.JedisConnectionException;
 import redis.clients.jedis.exceptions.JedisValidationException;
 
@@ -25,6 +26,7 @@
  * <p>
  */
 // TODO: move
+@Experimental
 public final class MultiClusterClientConfig {
 
     private static final int RETRY_MAX_ATTEMPTS_DEFAULT = 3;

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

@@ -9,6 +9,7 @@
 import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
 import org.json.JSONArray;
 
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.args.*;
 import redis.clients.jedis.bloom.*;
 import redis.clients.jedis.commands.JedisCommands;
@@ -192,6 +193,7 @@ public UnifiedJedis(ConnectionProvider provider, int maxAttempts, Duration maxTo
    * by using simple configuration which is passed through from Resilience4j - https://resilience4j.readme.io/docs
    * <p>
    */
+  @Experimental
   public UnifiedJedis(MultiClusterPooledConnectionProvider provider) {
     this(new CircuitBreakerCommandExecutor(provider), provider);
   }

src/main/java/redis/clients/jedis/annots/Experimental.java

@@ -0,0 +1,17 @@
+package redis.clients.jedis.annots;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to mark classes for experimental development.
+ * <p>
+ * Classes with this annotation may be renamed, changed or even removed in a future version. This
+ * annotation doesn't mean that the implementation has an 'experimental' quality.
+ * <p>
+ * If a type is marked with this annotation, all its members are considered experimental.
+ */
+@Documented
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
+public @interface Experimental { }

src/main/java/redis/clients/jedis/annots/Internal.java

@@ -0,0 +1,17 @@
+package redis.clients.jedis.annots;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to mark classes or methods as an internal development API. It indicates that the
+ * annotated element must not be considered as a public API.
+ * <p>
+ * Classes or methods with this annotation may change across releases.
+ * <p>
+ * If a type is marked with this annotation, all its members are considered internal.
+ */
+@Documented
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
+public @interface Internal { }

src/main/java/redis/clients/jedis/annots/VisibleForTesting.java

@@ -0,0 +1,12 @@
+package redis.clients.jedis.annots;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * A member or type annotated with {@link VisibleForTesting} declares that it is only visible for testing purposes.
+ */
+@Documented
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.TYPE})
+public @interface VisibleForTesting { }

src/main/java/redis/clients/jedis/executors/ClusterCommandExecutor.java

@@ -13,6 +13,7 @@
 import redis.clients.jedis.ConnectionPool;
 import redis.clients.jedis.HostAndPort;
 import redis.clients.jedis.Protocol;
+import redis.clients.jedis.annots.VisibleForTesting;
 import redis.clients.jedis.exceptions.*;
 import redis.clients.jedis.providers.ClusterConnectionProvider;
 import redis.clients.jedis.util.IOUtils;
@@ -135,6 +136,7 @@ public final <T> T executeCommand(CommandObject<T> commandObject) {
    * WARNING: This method is accessible for the purpose of testing.
    * This should not be used or overriden.
    */
+  @VisibleForTesting
   protected <T> T execute(Connection connection, CommandObject<T> commandObject) {
     return connection.executeCommand(commandObject);
   }
@@ -193,6 +195,7 @@ private static long getBackoffSleepMillis(int attemptsLeft, Instant deadline) {
    * WARNING: This method is accessible for the purpose of testing.
    * This should not be used or overriden.
    */
+  @VisibleForTesting
   protected void sleep(long sleepMillis) {
     try {
       TimeUnit.MILLISECONDS.sleep(sleepMillis);

src/main/java/redis/clients/jedis/executors/RetryableCommandExecutor.java

@@ -8,6 +8,7 @@
 
 import redis.clients.jedis.CommandObject;
 import redis.clients.jedis.Connection;
+import redis.clients.jedis.annots.VisibleForTesting;
 import redis.clients.jedis.exceptions.JedisConnectionException;
 import redis.clients.jedis.exceptions.JedisException;
 import redis.clients.jedis.util.IOUtils;
@@ -75,6 +76,7 @@ public final <T> T executeCommand(CommandObject<T> commandObject) {
    * WARNING: This method is accessible for the purpose of testing.
    * This should not be used or overriden.
    */
+  @VisibleForTesting
   protected <T> T execute(Connection connection, CommandObject<T> commandObject) {
     return connection.executeCommand(commandObject);
   }
@@ -115,6 +117,7 @@ private static long getBackoffSleepMillis(int attemptsLeft, Instant deadline) {
    * WARNING: This method is accessible for the purpose of testing.
    * This should not be used or overriden.
    */
+  @VisibleForTesting
   protected void sleep(long sleepMillis) {
     try {
       TimeUnit.MILLISECONDS.sleep(sleepMillis);

src/main/java/redis/clients/jedis/mcf/CircuitBreakerCommandExecutor.java

@@ -6,6 +6,7 @@
 
 import redis.clients.jedis.CommandObject;
 import redis.clients.jedis.Connection;
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.executors.CommandExecutor;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider.Cluster;
@@ -18,6 +19,7 @@
  * by using simple configuration which is passed through from Resilience4j - https://resilience4j.readme.io/docs
  * <p>
  */
+@Experimental
 public class CircuitBreakerCommandExecutor extends CircuitBreakerFailoverBase implements CommandExecutor {
 
     public CircuitBreakerCommandExecutor(MultiClusterPooledConnectionProvider provider) {

src/main/java/redis/clients/jedis/mcf/CircuitBreakerFailoverBase.java

@@ -1,6 +1,7 @@
 package redis.clients.jedis.mcf;
 
 import io.github.resilience4j.circuitbreaker.CircuitBreaker;
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.exceptions.JedisConnectionException;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider;
 import redis.clients.jedis.util.IOUtils;
@@ -14,6 +15,7 @@
  * Resilience4j - https://resilience4j.readme.io/docs
  * <p>
  */
+@Experimental
 public class CircuitBreakerFailoverBase implements AutoCloseable {
 
     protected final MultiClusterPooledConnectionProvider provider;

src/main/java/redis/clients/jedis/mcf/CircuitBreakerFailoverConnectionProvider.java

@@ -5,6 +5,7 @@
 import io.github.resilience4j.decorators.Decorators.DecorateSupplier;
 
 import redis.clients.jedis.Connection;
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider.Cluster;
 
@@ -13,6 +14,7 @@
  * With this executor users can seamlessly failover to Disaster Recovery (DR), Backup, and Active-Active cluster(s)
  * by using simple configuration which is passed through from Resilience4j - https://resilience4j.readme.io/docs
  */
+@Experimental
 public class CircuitBreakerFailoverConnectionProvider extends CircuitBreakerFailoverBase {
 
     public CircuitBreakerFailoverConnectionProvider(MultiClusterPooledConnectionProvider provider) {

src/main/java/redis/clients/jedis/mcf/MultiClusterPipeline.java

@@ -7,6 +7,7 @@
 import java.util.Queue;
 
 import redis.clients.jedis.*;
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.graph.ResultSet;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider;
 import redis.clients.jedis.util.KeyValue;
@@ -15,6 +16,7 @@
  * This is high memory dependent solution as all the appending commands will be hold in memory until
  * {@link MultiClusterPipeline#sync() SYNC} (or {@link MultiClusterPipeline#close() CLOSE}) gets called.
  */
+@Experimental
 public class MultiClusterPipeline extends PipelineBase implements Closeable {
 
   private final CircuitBreakerFailoverConnectionProvider failoverProvider;

src/main/java/redis/clients/jedis/mcf/MultiClusterTransaction.java

@@ -14,6 +14,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 import redis.clients.jedis.*;
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.exceptions.JedisDataException;
 import redis.clients.jedis.graph.ResultSet;
 import redis.clients.jedis.providers.MultiClusterPooledConnectionProvider;
@@ -22,6 +23,7 @@
 /**
  * This is high memory dependent solution as all the appending commands will be hold in memory.
  */
+@Experimental
 public class MultiClusterTransaction extends TransactionBase {
 
   private static final Builder<?> NO_OP_BUILDER = BuilderFactory.RAW_OBJECT;

src/main/java/redis/clients/jedis/providers/MultiClusterPooledConnectionProvider.java

@@ -19,6 +19,7 @@
 
 import redis.clients.jedis.*;
 import redis.clients.jedis.MultiClusterClientConfig.ClusterConfig;
+import redis.clients.jedis.annots.Experimental;
 import redis.clients.jedis.exceptions.JedisConnectionException;
 import redis.clients.jedis.exceptions.JedisValidationException;
 import redis.clients.jedis.util.Pool;
@@ -35,6 +36,7 @@
  * <p>
  */
 // TODO: move?
+@Experimental
 public class MultiClusterPooledConnectionProvider implements ConnectionProvider {
 
     private final Logger log = LoggerFactory.getLogger(getClass());