[automatic failover] Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration #4310

ggivo · 2025-10-07T14:02:51Z

Summary

This PR refactors the MultiDb API to improve clarity and maintainability through two major changes:

Renamed endpoint-related methods to use database-centric terminology
Encapsulated retry and circuit breaker configuration into dedicated nested config classes

Changes

1. Endpoint → Database Terminology (Commits: "Rename MultiDbClient endpoint related methods", "Methods Renamed in MultiDbConfig.Builder")

Renamed all endpoint-related methods to use "database" terminology for better clarity:

MultiDbClient methods:

addEndpoint() → addDatabase()
removeEndpoint() → removeDatabase()
forceActiveEndpoint() → forceActiveDatabase()
getActiveEndpoint() → getActiveDatabaseEndpoint()
getEndpoints() → getDatabaseEndpoints()

MultiDbConfig.Builder methods:

endpoint() → database() (both overloaded variants)

2. RetryConfig Encapsulation

Created MultiDbConfig.RetryConfig nested class with builder pattern
Removed individual retry fields and methods:
- retryMaxAttempts → RetryConfig.maxAttempts
- retryWaitDuration → RetryConfig.waitDuration
- retryWaitDurationExponentialBackoffMultiplier → RetryConfig.exponentialBackoffMultiplier
- retryIncludedExceptionList → RetryConfig.includedExceptionList
- retryIgnoreExceptionList → RetryConfig.ignoreExceptionList
Added single commandRetry property with commandRetry(RetryConfig) builder method

3. CircuitBreakerConfig Encapsulation

Created MultiDbConfig.CircuitBreakerConfig nested class with builder pattern
Removed individual circuit breaker fields and methods:
- circuitBreakerFailureRateThreshold → CircuitBreakerConfig.failureRateThreshold
- circuitBreakerSlidingWindowSize → CircuitBreakerConfig.slidingWindowSize
- circuitBreakerMinNumOfFailures → CircuitBreakerConfig.minNumOfFailures
- circuitBreakerIncludedExceptionList → CircuitBreakerConfig.includedExceptionList
- circuitBreakerIgnoreExceptionList → CircuitBreakerConfig.ignoreExceptionList
Added single failureDetector property with failureDetector(CircuitBreakerConfig) builder method

4. Implementation Updates

Updated MultiDbConnectionProvider with helper methods:
- buildRetryConfig() - converts Jedis RetryConfig to Resilience4j RetryConfig
- buildCircuitBreakerConfig() - converts Jedis CircuitBreakerConfig to Resilience4j CircuitBreakerConfig
Updated CircuitBreakerThresholdsAdapter to use new API
Preserved all original javadoc documentation with cross-references updated

5. Documentation Updates

Updated all code examples in javadoc (4 files)
Updated docs/failover.md with new API examples
Maintained all inline comments and explanations

6. Test Updates

Updated all test files to use new terminology and configuration API
All tests pass successfully

API Changes

Endpoint → Database Renaming

Before:

MultiDbClient client = ...;
client.addEndpoint(databaseConfig);
client.removeEndpoint(endpoint);
client.forceActiveEndpoint(endpoint);
Endpoint active = client.getActiveEndpoint();
List<Endpoint> endpoints = client.getEndpoints();

MultiDbConfig.builder()
    .endpoint(databaseConfig)
    .build();

After:

MultiDbClient client = ...;
client.addDatabase(databaseConfig);
client.removeDatabase(endpoint);
client.forceActiveDatabase(endpoint);
Endpoint active = client.getActiveDatabaseEndpoint();
List<Endpoint> endpoints = client.getDatabaseEndpoints();

MultiDbConfig.builder()
    .database(databaseConfig)
    .build();

Configuration changes

Before

MultiDbConfig.builder()
    .retryMaxAttempts(3)
    .retryWaitDuration(500)
    .retryWaitDurationExponentialBackoffMultiplier(2)
    .circuitBreakerSlidingWindowSize(3)
    .circuitBreakerMinNumOfFailures(2)
    .circuitBreakerFailureRateThreshold(50f)
    .build();

After (New API):

MultiDbConfig.builder()
    .commandRetry(MultiDbConfig.RetryConfig.builder()
        .maxAttempts(3)
        .waitDuration(500)
        .exponentialBackoffMultiplier(2)
        .build())
    .failureDetector(MultiDbConfig.CircuitBreakerConfig.builder()
        .slidingWindowSize(3)
        .minNumOfFailures(2)
        .failureRateThreshold(50f)
        .build())
    .build();

Copilot

Pull Request Overview

This PR refactors the MultiDb API to improve clarity and maintainability through two main changes: renaming endpoint-related methods to use database-centric terminology, and encapsulating retry and circuit breaker configuration into dedicated nested config classes.

Renamed all endpoint-related methods to use "database" terminology (e.g., addEndpoint() → addDatabase())
Encapsulated retry configuration into a dedicated RetryConfig nested class with builder pattern
Encapsulated circuit breaker configuration into a dedicated CircuitBreakerConfig nested class with builder pattern

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/test/java/redis/clients/jedis/scenario/ActiveActiveFailoverTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/misc/AutomaticFailoverTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/mcf/MultiDbConnectionProviderTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/mcf/MultiDbCircuitBreakerThresholdsTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/mcf/HealthCheckIntegrationTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/mcf/DefaultValuesTest.java	Updated test to verify default values through new API structure
src/test/java/redis/clients/jedis/mcf/DatabaseEvaluateThresholdsTest.java	Updated test to use new nested config builders
src/test/java/redis/clients/jedis/mcf/ActiveActiveLocalFailoverTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/failover/FailoverIntegrationTest.java	Updated test to use new database API and nested config builders
src/test/java/redis/clients/jedis/MultiDbClientTest.java	Updated test method names and API calls to use database terminology
src/main/java/redis/clients/jedis/mcf/MultiDbConnectionProvider.java	Added helper methods for building Resilience4j configs and updated to use new API
src/main/java/redis/clients/jedis/mcf/CircuitBreakerThresholdsAdapter.java	Updated to use new nested config structure
src/main/java/redis/clients/jedis/builders/MultiDbClientBuilder.java	Updated javadoc examples to use new API
src/main/java/redis/clients/jedis/MultiDbConfig.java	Added nested RetryConfig and CircuitBreakerConfig classes with builders
src/main/java/redis/clients/jedis/MultiDbClient.java	Renamed methods and updated javadoc to use database terminology
docs/failover.md	Updated documentation examples to use new API

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

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

src/main/java/redis/clients/jedis/builders/MultiDbClientBuilder.java

- MultiDbClient::addEndpoint -> MultiDbClient::addDatabase - MultiDbClient::forceActiveEndpoint -> MultiDbClient::forceActiveDatabase - MultiDbClient::removeEndpoint -> MultiDbClient::removeDatabase - MultiDbClient::getActiveEndpoint → MultiDbClient::getActiveDatabaseEndpoint - MultiDbClient::getEndpoints → MultiDbClient::getDatabaseEndpoints

- endpoint(DatabaseConfig databaseConfig) → database(DatabaseConfig databaseConfig) - endpoint(Endpoint endpoint, float weight, JedisClientConfig clientConfig) → database(Endpoint endpoint, float weight, JedisClientConfig clientConfig)

- Related retry settings grouped together - RetryConfig class created with builder pattern Example usage MultiDbConfig.RetryConfig.builder() .maxAttempts(5) .waitDuration(1000) .exponentialBackoffMultiplier(2) .includedExceptionList(Arrays.asList(JedisConnectionException.class)) .build())

- Related cb settings grouped together Example usage .failureDetector(MultiDbConfig.CircuitBreakerConfig.builder() .slidingWindowSize(3) .minNumOfFailures(2) .failureRateThreshold(50f) .build())

Copilot

Pull Request Overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

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

docs/failover.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

github-actions · 2025-10-07T16:05:38Z

Test Results

283 files ±0 283 suites ±0 11m 35s ⏱️ +2s
10 075 tests ±0 10 030 ✅ +411 45 💤 - 411 0 ❌ ±0
2 713 runs ±0 2 713 ✅ ± 0 0 💤 ± 0 0 ❌ ±0

Results for commit 7f327e6. ± Comparison against base commit 14356c4.

This pull request removes 21 and adds 21 tests. Note that renamed tests count towards both.

redis.clients.jedis.MultiDbClientTest ‑ testAddRemoveEndpointWithDatabaseConfig
redis.clients.jedis.MultiDbClientTest ‑ testAddRemoveEndpointWithEndpointInterface
redis.clients.jedis.MultiDbClientTest ‑ testForceActiveEndpoint
redis.clients.jedis.MultiDbClientTest ‑ testForceActiveEndpointWithNonExistingEndpoint
redis.clients.jedis.MultiDbClientTest ‑ testForceActiveEndpointWithNonHealthyEndpoint
redis.clients.jedis.failover.FailoverIntegrationTest ‑ testManualFailoverNewCommandsAreSentToActiveCluster
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testFailbackToHigherWeightCluster
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testFailbackToHigherWeightClusterImmediately
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testGracePeriodDisablesClusterOnUnhealthy
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testGracePeriodReEnablesClusterAfterPeriod
…

redis.clients.jedis.MultiDbClientTest ‑ testAddRemoveDatabaseWithDatabaseConfig
redis.clients.jedis.MultiDbClientTest ‑ testAddRemoveDatabaseWithEndpointInterface
redis.clients.jedis.MultiDbClientTest ‑ testForceActiveDatabase
redis.clients.jedis.MultiDbClientTest ‑ testForceActiveDatabaseWithNonExistingEndpoint
redis.clients.jedis.MultiDbClientTest ‑ testForceActiveDatabaseWithNonHealthyEndpoint
redis.clients.jedis.failover.FailoverIntegrationTest ‑ testManualFailoverNewCommandsAreSentToActiveDatabase
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testFailbackToHigherWeightDatabase
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testFailbackToHigherWeightDatabaseImmediately
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testGracePeriodDisablesDatabaseOnUnhealthy
redis.clients.jedis.mcf.FailbackMechanismIntegrationTest ‑ testGracePeriodReEnablesDatabaseAfterPeriod
…

♻️ This comment has been updated with latest results.

ggivo · 2025-10-08T06:21:34Z

run scenario tests

uglide · 2025-10-08T06:42:13Z

Testcase	Errors	Failures	Skipped	Total
redis.clients.jedis.scenario.ConnectionInterruptionTest	0	0	0	4

---- Details for maintainers

…package

…ithinWindow

atakavci

as i understand these changes will go into GA, so lets replace as much as we can

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

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

Co-authored-by: atakavci <a_takavci@yahoo.com>

atakavci

LGTM!

ggivo requested a review from Copilot October 7, 2025 14:09

Copilot AI reviewed Oct 7, 2025

View reviewed changes

src/main/java/redis/clients/jedis/mcf/MultiDbConnectionProvider.java Show resolved Hide resolved

src/main/java/redis/clients/jedis/builders/MultiDbClientBuilder.java Outdated Show resolved Hide resolved

ggivo marked this pull request as ready for review October 7, 2025 14:35

ggivo added the breakingchange Pull request that has breaking changes. Must include the breaking behavior in release notes. label Oct 7, 2025

ggivo changed the title ~~Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration~~ [automatic failover] Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration Oct 7, 2025

atakavci mentioned this pull request Oct 7, 2025

[automatic failover] Refactor: Rename Multi-Cluster Classes to Multi-Database Terminology #4308

Merged

ggivo changed the base branch from ggivo/multidb-api-rename to master October 7, 2025 15:38

ggivo added 8 commits October 7, 2025 18:47

Methods Renamed in MultiDbConfig.Builder

55d5aeb

- endpoint(DatabaseConfig databaseConfig) → database(DatabaseConfig databaseConfig) - endpoint(Endpoint endpoint, float weight, JedisClientConfig clientConfig) → database(Endpoint endpoint, float weight, JedisClientConfig clientConfig)

Refactor circuit breaker configuration

739324e

- Related cb settings grouped together Example usage .failureDetector(MultiDbConfig.CircuitBreakerConfig.builder() .slidingWindowSize(3) .minNumOfFailures(2) .failureRateThreshold(50f) .build())

fix typo in javadocs

7a873ae

fix examples in failover.md

da4ed1d

fix failover.md example identation

c6db412

fix leftover references to activeCuster

84712d7

ggivo force-pushed the ggivo/multidb-api-rename-2 branch from fb4b4b1 to 84712d7 Compare October 7, 2025 15:48

ggivo requested a review from Copilot October 7, 2025 15:48

Copilot AI reviewed Oct 7, 2025

View reviewed changes

src/main/java/redis/clients/jedis/mcf/MultiDbConnectionProvider.java Outdated Show resolved Hide resolved

docs/failover.md Outdated Show resolved Hide resolved

ggivo and others added 2 commits October 7, 2025 18:52

Apply suggestion from @Copilot

19b1b17

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

1596f50

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ggivo added 3 commits October 8, 2025 09:53

fix leftover cluster references in local/private scope

113f305

clean up leftover 'cluster' references in local/private scope in mcf …

c9defe3

…package

fix failing test delayBetweenFailoverAttempts_gatesCounterIncrementsW…

7e1008c

…ithinWindow

atakavci reviewed Oct 8, 2025

View reviewed changes

ggivo and others added 3 commits October 8, 2025 13:53

Apply suggestion from @atakavci

c6441a2

Co-authored-by: atakavci <a_takavci@yahoo.com>

Apply suggestion from @atakavci

7b7f7a4

Co-authored-by: atakavci <a_takavci@yahoo.com>

more left overs of 'cluster' in javadocs outside mcf package

7f327e6

atakavci approved these changes Oct 8, 2025

View reviewed changes

ggivo merged commit 6a4a94b into master Oct 8, 2025
14 checks passed

ggivo added the feature label Oct 10, 2025

ggivo deleted the ggivo/multidb-api-rename-2 branch October 10, 2025 06:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[automatic failover] Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration #4310

[automatic failover] Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration #4310

ggivo commented Oct 7, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 7, 2025 •

edited

Loading

Uh oh!

ggivo commented Oct 8, 2025

Uh oh!

uglide commented Oct 8, 2025

Uh oh!

atakavci left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

atakavci left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[automatic failover] Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration #4310

[automatic failover] Refactor MultiDb API: Rename endpoint methods to database and encapsulate retry/circuit breaker configuration #4310

Conversation

ggivo commented Oct 7, 2025

Summary

Changes

1. Endpoint → Database Terminology (Commits: "Rename MultiDbClient endpoint related methods", "Methods Renamed in MultiDbConfig.Builder")

2. RetryConfig Encapsulation

3. CircuitBreakerConfig Encapsulation

4. Implementation Updates

5. Documentation Updates

6. Test Updates

API Changes

Endpoint → Database Renaming

Configuration changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

ggivo commented Oct 8, 2025

Uh oh!

uglide commented Oct 8, 2025

Uh oh!

atakavci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

atakavci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Oct 7, 2025 •

edited

Loading