From 9c58f22540d812e76c2277931da8deef6448d46c Mon Sep 17 00:00:00 2001 From: Rajdeep Chakraborty Date: Mon, 23 Feb 2026 17:10:38 +0530 Subject: [PATCH 1/2] feat(driver): add non-retryable ProxyRemoteException Introduce ProxyRemoteException and map BinaryProtocol REMOTE_ERROR (127) to it so server-side remote transport FaultExceptions are surfaced as non-retryable, preventing automatic SDK retries and letting callers decide whether/how to retry. --- .../nosql/driver/ProxyRemoteException.java | 29 +++++++++++++++++++ .../driver/ops/serde/BinaryProtocol.java | 4 +++ .../nosql/driver/util/BinaryProtocol.java | 8 +++++ 3 files changed, 41 insertions(+) create mode 100644 driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java diff --git a/driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java b/driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java new file mode 100644 index 00000000..e9d9c752 --- /dev/null +++ b/driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java @@ -0,0 +1,29 @@ +/*- + * Copyright (c) 2011, 2025 Oracle and/or its affiliates. All rights reserved. + * + * Licensed under the Universal Permissive License v 1.0 as shown at + * https://oss.oracle.com/licenses/upl/ + */ + +package oracle.nosql.driver; + +/** + * Thrown when the proxy reports a server-side FaultException that appears to + * have originated from a remote networking/transport failure. + *

+ * This exception is intentionally not retryable by the Java SDK's + * internal retry handler; higher-level logic (tests, applications) can decide + * whether and how to retry. + */ +public class ProxyRemoteException extends NoSQLException { + + private static final long serialVersionUID = 1L; + + public ProxyRemoteException(String msg) { + super(msg); + } + + public ProxyRemoteException(String msg, Throwable cause) { + super(msg, cause); + } +} diff --git a/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java b/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java index 0ee8627a..75807c3d 100644 --- a/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java +++ b/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java @@ -18,6 +18,7 @@ import oracle.nosql.driver.Durability; import oracle.nosql.driver.EvolutionLimitException; import oracle.nosql.driver.FieldRange; +import oracle.nosql.driver.ProxyRemoteException; import oracle.nosql.driver.IndexExistsException; import oracle.nosql.driver.IndexLimitException; import oracle.nosql.driver.IndexNotFoundException; @@ -437,6 +438,9 @@ public static RuntimeException mapException(int code, String msg) { return new IllegalArgumentException(msg); case RECOMPILE_QUERY: return new PrepareQueryException(msg); + + case REMOTE_ERROR: + return new ProxyRemoteException(msg); default: return new NoSQLException("Unknown error code " + code + ": " + msg); diff --git a/driver/src/main/java/oracle/nosql/driver/util/BinaryProtocol.java b/driver/src/main/java/oracle/nosql/driver/util/BinaryProtocol.java index 7e47f559..aaefc472 100644 --- a/driver/src/main/java/oracle/nosql/driver/util/BinaryProtocol.java +++ b/driver/src/main/java/oracle/nosql/driver/util/BinaryProtocol.java @@ -222,6 +222,14 @@ public static boolean isTenantOperation(OpCode op) { public static final int UNKNOWN_ERROR = 125; public static final int ILLEGAL_STATE = 126; + /* + * A server-side FaultException that appears to have originated from a + * remote networking/transport failure. This is intentionally in the + * NON-retryable (125+) range so that the Java SDK does not perform + * automatic retries; callers can decide whether/how to retry. + */ + public static final int REMOTE_ERROR = 127; + /* * Return true if the errorCode means a user-generated error. */ From 7043f04477e15b591b017901264d316953663aa1 Mon Sep 17 00:00:00 2001 From: Rajdeep Chakraborty Date: Tue, 24 Feb 2026 19:01:43 +0530 Subject: [PATCH 2/2] feat(driver): add RemoteTransportException for server transport faults Introduce RemoteTransportException and map REMOTE_ERROR to it in BinaryProtocol, ensuring these remote networking/transport failures are not retried by the SDK retry handler and leaving retry decisions to application code. --- .../nosql/driver/ProxyRemoteException.java | 29 --------------- .../driver/RemoteTransportException.java | 36 +++++++++++++++++++ .../driver/ops/serde/BinaryProtocol.java | 5 ++- 3 files changed, 38 insertions(+), 32 deletions(-) delete mode 100644 driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java create mode 100644 driver/src/main/java/oracle/nosql/driver/RemoteTransportException.java diff --git a/driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java b/driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java deleted file mode 100644 index e9d9c752..00000000 --- a/driver/src/main/java/oracle/nosql/driver/ProxyRemoteException.java +++ /dev/null @@ -1,29 +0,0 @@ -/*- - * Copyright (c) 2011, 2025 Oracle and/or its affiliates. All rights reserved. - * - * Licensed under the Universal Permissive License v 1.0 as shown at - * https://oss.oracle.com/licenses/upl/ - */ - -package oracle.nosql.driver; - -/** - * Thrown when the proxy reports a server-side FaultException that appears to - * have originated from a remote networking/transport failure. - *

- * This exception is intentionally not retryable by the Java SDK's - * internal retry handler; higher-level logic (tests, applications) can decide - * whether and how to retry. - */ -public class ProxyRemoteException extends NoSQLException { - - private static final long serialVersionUID = 1L; - - public ProxyRemoteException(String msg) { - super(msg); - } - - public ProxyRemoteException(String msg, Throwable cause) { - super(msg, cause); - } -} diff --git a/driver/src/main/java/oracle/nosql/driver/RemoteTransportException.java b/driver/src/main/java/oracle/nosql/driver/RemoteTransportException.java new file mode 100644 index 00000000..72817e13 --- /dev/null +++ b/driver/src/main/java/oracle/nosql/driver/RemoteTransportException.java @@ -0,0 +1,36 @@ +/*- + * Copyright (c) 2011, 2025 Oracle and/or its affiliates. All rights reserved. + * + * Licensed under the Universal Permissive License v 1.0 as shown at + * https://oss.oracle.com/licenses/upl/ + */ + +package oracle.nosql.driver; + +/** + * Thrown when the service reports a server-side {@code FaultException} that + * appears to have originated from a remote networking/transport failure + * between service components. + *

+ * This exception is intentionally not retried by the Java SDK's + * internal retry handler. Application code may choose to retry, using the + * following guidance: + *

+ */ +public class RemoteTransportException extends NoSQLException { + + private static final long serialVersionUID = 1L; + + public RemoteTransportException(String msg) { + super(msg); + } + + public RemoteTransportException(String msg, Throwable cause) { + super(msg, cause); + } +} diff --git a/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java b/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java index 75807c3d..ee3a8943 100644 --- a/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java +++ b/driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java @@ -18,7 +18,7 @@ import oracle.nosql.driver.Durability; import oracle.nosql.driver.EvolutionLimitException; import oracle.nosql.driver.FieldRange; -import oracle.nosql.driver.ProxyRemoteException; +import oracle.nosql.driver.RemoteTransportException; import oracle.nosql.driver.IndexExistsException; import oracle.nosql.driver.IndexLimitException; import oracle.nosql.driver.IndexNotFoundException; @@ -438,9 +438,8 @@ public static RuntimeException mapException(int code, String msg) { return new IllegalArgumentException(msg); case RECOMPILE_QUERY: return new PrepareQueryException(msg); - case REMOTE_ERROR: - return new ProxyRemoteException(msg); + return new RemoteTransportException(msg); default: return new NoSQLException("Unknown error code " + code + ": " + msg);