feat(jdbc): add OCC retry with exponential backoff (#542)

Add retry utilities for Aurora DSQL OCC conflicts with exponential
backoff and jitter. Includes DataSource (fresh connection per attempt)
and Connection (reuse with rollback) overloads, immutable config with
builder pattern, and OCCTransactionRunner convenience wrapper.

- OCCRetry: static execute() methods, isOCCError() detection, backoff
- OCCRetryConfig: validated builder (maxRetries, baseDelay, jitter, etc)
- OCCTransactionRunner: bind-once wrapper with run()/runVoid()
- VoidTransactionCallback: ergonomic void lambda interface
- Unit tests covering all retry paths and edge cases
- Integration tests with deterministic OCC conflict scenarios
- Update examples to demonstrate OCC retry usage
- Add README documentation with integration framework examples

*Issue #, if available:*
N/A
*Description of changes:*


By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

Co-authored-by: Prabakaran Annadurai <prabaw@amazon.com>

Author: praba2210

.github/workflows/java-jdbc-ci.yml

@@ -106,11 +106,16 @@ jobs:
           CLUSTER_USER: "admin"
         run: ./gradlew integrationTest
 
+      - name: Publish connector to Maven Local
+        run: ./gradlew publishToMavenLocal
+
       - name: Run example smoke tests
         working-directory: java/jdbc/examples/pgjdbc
         env:
           CLUSTER_ENDPOINT: ${{ needs.create-cluster.outputs.cluster-endpoint }}
           CLUSTER_USER: "admin"
+          USE_MAVEN_LOCAL: "true"
+          CONNECTOR_VERSION: "0.0.0-SNAPSHOT"
         run: ../../gradlew test
 
   integration-tests:

java/jdbc/README.md

@@ -160,6 +160,115 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
 java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
 ```
 
+## OCC Retry
+
+Aurora DSQL uses Optimistic Concurrency Control (OCC) — conflicts are detected at commit time. When two transactions modify the same data, the second to commit receives an OCC error. This connector provides utilities for automatic retry with exponential backoff.
+
+### Quick Start
+
+```java
+// Bind once, reuse across call sites
+DataSource ds = new HikariDataSource(config);
+OCCTransactionRunner runner = OCCTransactionRunner.create(ds);
+
+int count = runner.run(conn -> {
+    Statement stmt = conn.createStatement();
+    stmt.executeUpdate("UPDATE accounts SET balance = balance - 100 WHERE id = 1");
+    stmt.executeUpdate("UPDATE accounts SET balance = balance + 100 WHERE id = 2");
+    return 2;
+});
+
+// Void variant — no need to return null
+runner.runVoid(conn -> {
+    conn.createStatement().executeUpdate("DELETE FROM expired_sessions");
+});
+```
+
+### Custom Configuration
+
+```java
+OCCRetryConfig config = OCCRetryConfig.builder()
+    .maxRetries(5)
+    .baseDelayMs(200)
+    .maxDelayMs(10000)
+    .multiplier(2.0)
+    .jitterFactor(0.5)
+    .build();
+
+OCCTransactionRunner runner = OCCTransactionRunner.create(ds, config);
+```
+
+### Static API (for one-off use)
+
+```java
+OCCRetry.execute(dataSource, OCCRetryConfig.defaults(), conn -> {
+    // transaction work
+    return result;
+});
+
+// With an existing connection (rolled back between attempts, not closed)
+OCCRetry.execute(connection, OCCRetryConfig.defaults(), conn -> {
+    // transaction work
+    return result;
+});
+```
+
+### Integration with Retry Frameworks
+
+Use `OCCRetry.isOCCError(SQLException)` as the predicate for any retry framework:
+
+**Spring Retry:**
+```java
+RetryTemplate template = RetryTemplate.builder()
+    .maxAttempts(4)
+    .exponentialBackoff(100, 2.0, 5000)
+    .retryOn(SQLException.class)
+    .traversingCauses()
+    .build();
+
+template.execute(ctx -> {
+    try (Connection conn = ds.getConnection()) {
+        conn.setAutoCommit(false);
+        // ... transaction work ...
+        conn.commit();
+        return null;
+    }
+});
+```
+
+**Resilience4j:**
+```java
+RetryConfig retryConfig = RetryConfig.custom()
+    .maxAttempts(4)
+    .retryOnException(e -> e instanceof SQLException && OCCRetry.isOCCError((SQLException) e))
+    .build();
+```
+
+**Failsafe:**
+```java
+RetryPolicy<Object> policy = RetryPolicy.builder()
+    .handleIf(e -> e instanceof SQLException && OCCRetry.isOCCError((SQLException) e))
+    .withMaxAttempts(4)
+    .withBackoff(Duration.ofMillis(100), Duration.ofSeconds(5))
+    .build();
+```
+
+**Plain loop:**
+```java
+SQLException lastErr = null;
+for (int i = 0; i <= maxRetries; i++) {
+    try {
+        doTransaction(ds);
+        return;
+    } catch (SQLException e) {
+        if (!OCCRetry.isOCCError(e)) throw e;
+        lastErr = e;
+        Thread.sleep(backoff(i));
+    }
+}
+throw lastErr;
+```
+
 ## Examples
 
 | Description | Examples |

java/jdbc/examples/pgjdbc/README.md

@@ -73,6 +73,7 @@ The example demonstrates the following operations:
 - Opening a connection to an Aurora DSQL cluster
 - Creating a table
 - Inserting and querying data
+- Automatic OCC (Optimistic Concurrency Control) retry for write operations
 
 The example is designed to work with both admin and non-admin users:
 

java/jdbc/examples/pgjdbc/build.gradle.kts

@@ -15,13 +15,18 @@ application {
 group = "software.amazon.dsql.examples"
 version = "1.0-SNAPSHOT"
 
+val connectorVersion: String = providers.environmentVariable("CONNECTOR_VERSION").getOrElse("1.4.0")
+
 repositories {
+    if (providers.environmentVariable("USE_MAVEN_LOCAL").isPresent) {
+        mavenLocal()
+    }
     mavenCentral()
 }
 
 dependencies {
     implementation("com.zaxxer:HikariCP:7.0.2")
-    implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.4.0")
+    implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:$connectorVersion")
 
     testImplementation(platform("org.junit:junit-bom:6.1.0"))
     testImplementation("org.junit.jupiter:junit-jupiter")

java/jdbc/examples/pgjdbc/src/main/java/software/amazon/dsql/examples/ExamplePreferred.java

@@ -14,6 +14,8 @@
 import java.sql.SQLException;
 import java.sql.Statement;
 
+import software.amazon.dsql.jdbc.OCCTransactionRunner;
+
 /**
  * Aurora DSQL example using HikariCP with Aurora DSQL JDBC Connector
  * <p>
@@ -30,9 +32,11 @@
 public class ExamplePreferred {
 
     private final HikariDataSource dataSource;
+    private final OCCTransactionRunner transactionRunner;
 
     public ExamplePreferred(String endpoint, String user) {
         this.dataSource = initializeConnectionPool(endpoint, user);
+        this.transactionRunner = OCCTransactionRunner.create(dataSource);
     }
 
     private HikariDataSource initializeConnectionPool(String endpoint, String username) {
@@ -82,30 +86,35 @@ public Connection getConnection() throws SQLException {
         return this.dataSource.getConnection();
     }
 
-    private void executeExample(Connection conn, int connectionNumber) throws SQLException {
+    private void executeExample(int connectionNumber) throws SQLException {
         // Create a new table named owner
-        try (Statement create = conn.createStatement()) {
-            create.executeUpdate("""
-                    CREATE TABLE IF NOT EXISTS owner(
-                    id uuid NOT NULL DEFAULT gen_random_uuid(),
-                    name varchar(30) NOT NULL,
-                    city varchar(80) NOT NULL,
-                    telephone varchar(20) DEFAULT NULL,
-                    PRIMARY KEY (id))""");
-        }
+        transactionRunner.runVoid(conn -> {
+            try (Statement create = conn.createStatement()) {
+                create.executeUpdate("""
+                        CREATE TABLE IF NOT EXISTS owner(
+                        id uuid NOT NULL DEFAULT gen_random_uuid(),
+                        name varchar(30) NOT NULL,
+                        city varchar(80) NOT NULL,
+                        telephone varchar(20) DEFAULT NULL,
+                        PRIMARY KEY (id))""");
+            }
+        });
 
         // Insert some data with a unique identifier
         String uniqueName = "John Doe " + System.currentTimeMillis() + "_" + connectionNumber;
-        try (PreparedStatement insert = conn.prepareStatement(
-                "INSERT INTO owner (name, city, telephone) VALUES (?, ?, ?)")) {
-            insert.setString(1, uniqueName);
-            insert.setString(2, "Anytown");
-            insert.setString(3, "555-555-1991");
-            insert.executeUpdate();
-        }
+        transactionRunner.runVoid(conn -> {
+            try (PreparedStatement insert = conn.prepareStatement(
+                    "INSERT INTO owner (name, city, telephone) VALUES (?, ?, ?)")) {
+                insert.setString(1, uniqueName);
+                insert.setString(2, "Anytown");
+                insert.setString(3, "555-555-1991");
+                insert.executeUpdate();
+            }
+        });
 
         // Read back the data and verify
-        try (PreparedStatement read = conn.prepareStatement("SELECT * FROM owner WHERE name = ?")) {
+        try (Connection conn = dataSource.getConnection();
+             PreparedStatement read = conn.prepareStatement("SELECT * FROM owner WHERE name = ?")) {
             read.setString(1, uniqueName);
             try (ResultSet rs = read.executeQuery()) {
                 while (rs.next()) {
@@ -136,30 +145,26 @@ public static void main(String[] args) throws SQLException {
 
         try {
 
-            // Demonstrate connection pooling with multiple concurrent connections
-            System.out.println("Testing connection pool with multiple connections...");
+            // Demonstrate connection pooling with OCC retry
+            System.out.println("Testing connection pool with OCC retry...");
 
-            try (Connection conn1 = example.getConnection();
-                 Connection conn2 = example.getConnection();
-                 Connection conn3 = example.getConnection()) {
+            System.out.println("Connection 1 obtained from pool");
+            example.executeExample(1);
 
-                System.out.println("Connection 1 obtained from pool");
-                example.executeExample(conn1, 1);
+            System.out.println("Connection 2 obtained from pool");
+            example.executeExample(2);
 
-                System.out.println("Connection 2 obtained from pool");
-                example.executeExample(conn2, 2);
+            System.out.println("Connection 3 obtained from pool");
+            example.executeExample(3);
 
-                System.out.println("Connection 3 obtained from pool");
-                example.executeExample(conn3, 3);
-            }
-
-            try (Connection conn = example.getConnection();
-                 PreparedStatement cleanup = conn.prepareStatement("DELETE FROM owner WHERE name LIKE ?")) {
-                cleanup.setString(1, "%John Doe%");
-                int deletedRows = cleanup.executeUpdate();
-
-                System.out.println("Cleaned up " + deletedRows + " test records");
-            }
+            // Cleanup
+            example.transactionRunner.runVoid(conn -> {
+                try (PreparedStatement cleanup = conn.prepareStatement("DELETE FROM owner WHERE name LIKE ?")) {
+                    cleanup.setString(1, "%John Doe%");
+                    int deletedRows = cleanup.executeUpdate();
+                    System.out.println("Cleaned up " + deletedRows + " test records");
+                }
+            });
 
         } finally {
             // Graceful shutdown

java/jdbc/examples/pgjdbc/src/main/java/software/amazon/dsql/examples/alternatives/README.md

@@ -18,4 +18,4 @@ The connector + pool combination handles this automatically:
 
 ### `no_connection_pool/`
 Examples without pooling:
-- `ExampleWithNoConnectionPool.java` - Single connection with connector
+- `ExampleWithNoConnectionPool.java` - Single connection with connector and OCC retry

java/jdbc/examples/pgjdbc/src/main/java/software/amazon/dsql/examples/alternatives/no_connection_pool/ExampleWithNoConnectionPool.java

@@ -14,6 +14,9 @@
 import java.sql.Statement;
 import java.util.Properties;
 
+import software.amazon.dsql.jdbc.OCCRetry;
+import software.amazon.dsql.jdbc.OCCRetryConfig;
+
 public class ExampleWithNoConnectionPool {
 
     // Get a connection to Aurora DSQL.
@@ -42,25 +45,35 @@ public static void main(String[] args) throws SQLException {
                     setSchema.execute("SET search_path=myschema");
                 }
             }
+
+            // Use OCC retry with existing connection for write operations
+            OCCRetryConfig retryConfig = OCCRetryConfig.defaults();
+
             // Create a new table named owner
-            try (Statement create = conn.createStatement()) {
-                create.executeUpdate("""
-                        CREATE TABLE IF NOT EXISTS owner(
-                        id uuid NOT NULL DEFAULT gen_random_uuid(),
-                        name varchar(30) NOT NULL,
-                        city varchar(80) NOT NULL,
-                        telephone varchar(20) DEFAULT NULL,
-                        PRIMARY KEY (id))""");
-            }
+            OCCRetry.execute(conn, retryConfig, c -> {
+                try (Statement create = c.createStatement()) {
+                    create.executeUpdate("""
+                            CREATE TABLE IF NOT EXISTS owner(
+                            id uuid NOT NULL DEFAULT gen_random_uuid(),
+                            name varchar(30) NOT NULL,
+                            city varchar(80) NOT NULL,
+                            telephone varchar(20) DEFAULT NULL,
+                            PRIMARY KEY (id))""");
+                }
+                return null;
+            });
 
             // Insert some data
-            try (PreparedStatement insert = conn.prepareStatement(
-                    "INSERT INTO owner (name, city, telephone) VALUES (?, ?, ?)")) {
-                insert.setString(1, "John Doe");
-                insert.setString(2, "Anytown");
-                insert.setString(3, "555-555-1999");
-                insert.executeUpdate();
-            }
+            OCCRetry.execute(conn, retryConfig, c -> {
+                try (PreparedStatement insert = c.prepareStatement(
+                        "INSERT INTO owner (name, city, telephone) VALUES (?, ?, ?)")) {
+                    insert.setString(1, "John Doe");
+                    insert.setString(2, "Anytown");
+                    insert.setString(3, "555-555-1999");
+                    insert.executeUpdate();
+                }
+                return null;
+            });
 
             // Read back the data and assert they are present
             try (PreparedStatement read = conn.prepareStatement("SELECT * FROM owner WHERE name = ?")) {
@@ -76,10 +89,13 @@ telephone varchar(20) DEFAULT NULL,
             }
 
             // Delete some data
-            try (PreparedStatement delete = conn.prepareStatement("DELETE FROM owner WHERE name = ?")) {
-                delete.setString(1, "John Doe");
-                delete.executeUpdate();
-            }
+            OCCRetry.execute(conn, retryConfig, c -> {
+                try (PreparedStatement delete = c.prepareStatement("DELETE FROM owner WHERE name = ?")) {
+                    delete.setString(1, "John Doe");
+                    delete.executeUpdate();
+                }
+                return null;
+            });
         }
         System.out.println("Connection exercised successfully");
     }