polish excpetion api + build in code list that is retryable

mzitnik · mzitnik · commit 6425c9b00f2e · 2025-06-14T20:50:05.000+02:00
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/Client.java b/client-v2/src/main/java/com/clickhouse/client/api/Client.java
@@ -12,6 +12,8 @@
 import com.clickhouse.client.api.data_formats.internal.ProcessParser;
 import com.clickhouse.client.api.enums.Protocol;
 import com.clickhouse.client.api.enums.ProxyType;
+import com.clickhouse.client.api.exception.ClientException;
+import com.clickhouse.client.api.exception.ServerException;
 import com.clickhouse.client.api.http.ClickHouseHttpProto;
 import com.clickhouse.client.api.insert.InsertResponse;
 import com.clickhouse.client.api.insert.InsertSettings;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/ClientMisconfigurationException.java b/client-v2/src/main/java/com/clickhouse/client/api/ClientMisconfigurationException.java
@@ -1,5 +1,7 @@
 package com.clickhouse.client.api;
 
+import com.clickhouse.client.api.exception.ClientException;
+
 /**
  * Represents errors caused by a client misconfiguration.
  */
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/command/CommandResponse.java b/client-v2/src/main/java/com/clickhouse/client/api/command/CommandResponse.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.command;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.metrics.OperationMetrics;
 import com.clickhouse.client.api.metrics.ServerMetrics;
 import com.clickhouse.client.api.query.QueryResponse;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/data_formats/NativeFormatReader.java b/client-v2/src/main/java/com/clickhouse/client/api/data_formats/NativeFormatReader.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.data_formats;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.data_formats.internal.AbstractBinaryFormatReader;
 import com.clickhouse.client.api.data_formats.internal.BinaryStreamReader;
 import com.clickhouse.client.api.metadata.TableSchema;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/data_formats/RowBinaryWithNamesAndTypesFormatReader.java b/client-v2/src/main/java/com/clickhouse/client/api/data_formats/RowBinaryWithNamesAndTypesFormatReader.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.data_formats;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.data_formats.internal.AbstractBinaryFormatReader;
 import com.clickhouse.client.api.data_formats.internal.BinaryStreamReader;
 import com.clickhouse.client.api.metadata.TableSchema;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/AbstractBinaryFormatReader.java b/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/AbstractBinaryFormatReader.java
@@ -1,7 +1,7 @@
 package com.clickhouse.client.api.data_formats.internal;
 
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.data_formats.ClickHouseBinaryFormatReader;
 import com.clickhouse.client.api.internal.MapUtils;
 import com.clickhouse.client.api.internal.ServerSettings;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/BinaryStreamReader.java b/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/BinaryStreamReader.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.data_formats.internal;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.data.ClickHouseColumn;
 import com.clickhouse.data.ClickHouseDataType;
 import com.clickhouse.data.ClickHouseEnum;
@@ -33,10 +33,8 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
-import java.util.Stack;
 import java.util.TimeZone;
 import java.util.UUID;
-import java.util.concurrent.TimeUnit;
 
 /**
  * This class is not thread safe and should not be shared between multiple threads.
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/MapBackedRecord.java b/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/MapBackedRecord.java
@@ -1,19 +1,17 @@
 package com.clickhouse.client.api.data_formats.internal;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.metadata.TableSchema;
 import com.clickhouse.client.api.query.GenericRecord;
 import com.clickhouse.client.api.query.NullValueException;
 import com.clickhouse.data.ClickHouseColumn;
-import com.clickhouse.data.ClickHouseDataType;
 import com.clickhouse.data.value.*;
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
 import java.net.Inet4Address;
 import java.net.Inet6Address;
 import java.time.*;
-import java.time.temporal.ChronoUnit;
 import java.time.temporal.TemporalAmount;
 import java.util.HashMap;
 import java.util.List;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/SerializerUtils.java b/client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/SerializerUtils.java
@@ -1,7 +1,7 @@
 package com.clickhouse.client.api.data_formats.internal;
 
 import com.clickhouse.client.api.Client;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.serde.POJOFieldDeserializer;
 import com.clickhouse.data.ClickHouseAggregateFunction;
 import com.clickhouse.data.ClickHouseColumn;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/exception/ClientException.java b/client-v2/src/main/java/com/clickhouse/client/api/exception/ClientException.java
@@ -1,12 +1,12 @@
-package com.clickhouse.client.api;
-
-public class ClientException extends RuntimeException {
-
-    public ClientException(String message) {
-        super(message);
-    }
-
-    public ClientException(String message, Throwable cause) {
-        super(message, cause);
-    }
-}
+package com.clickhouse.client.api.exception;
+
+public class ClientException extends RuntimeException {
+
+    public ClientException(String message) {
+        super(message);
+    }
+
+    public ClientException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/exception/ConnectionInitiationException.java b/client-v2/src/main/java/com/clickhouse/client/api/exception/ConnectionInitiationException.java
@@ -1,12 +1,12 @@
-package com.clickhouse.client.api;
-
-public class ConnectionInitiationException extends ClientException {
-
-    public ConnectionInitiationException(String message) {
-        super(message);
-    }
-
-    public ConnectionInitiationException(String message, Throwable cause) {
-        super(message, cause);
-    }
-}
+package com.clickhouse.client.api.exception;
+
+public class ConnectionInitiationException extends ClientException {
+
+    public ConnectionInitiationException(String message) {
+        super(message);
+    }
+
+    public ConnectionInitiationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/exception/ServerException.java b/client-v2/src/main/java/com/clickhouse/client/api/exception/ServerException.java
@@ -1,40 +1,47 @@
-package com.clickhouse.client.api;
-
-public class ServerException extends RuntimeException {
-
-    public static final int CODE_UNKNOWN = 0;
-
-    public static final int TABLE_NOT_FOUND = 60;
-
-    private final int code;
-
-    private final int transportProtocolCode;
-
-    public ServerException(int code, String message) {
-        this(code, message, 500);
-    }
-
-    public ServerException(int code, String message, int transportProtocolCode) {
-        super(message);
-        this.code = code;
-        this.transportProtocolCode = transportProtocolCode;
-    }
-
-    /**
-     * Returns CH server error code. May return 0 if code is unknown.
-     * @return - error code from server response
-     */
-    public int getCode() {
-        return code;
-    }
-
-    /**
-     * Returns error code of underlying transport protocol. For example, HTTP status.
-     * By default, will return {@code 500 } what is derived from HTTP Server Internal Error.
-     *
-     * @return - transport status code
-     */
-    public int getTransportProtocolCode() {
-        return transportProtocolCode;
-    }
-}
+package com.clickhouse.client.api.exception;
+
+public class ServerException extends RuntimeException {
+
+    public static final int CODE_UNKNOWN = 0;
+
+    public static final int TABLE_NOT_FOUND = 60;
+
+    private final int code;
+
+    private final int transportProtocolCode;
+
+    private boolean isRetryable  = false;
+
+    public ServerException(int code, String message) {
+        this(code, message, 500);
+    }
+
+    public ServerException(int code, String message, int transportProtocolCode) {
+        super(message);
+        this.code = code;
+        this.transportProtocolCode = transportProtocolCode;
+        this.isRetryable = Utils.isRetryable(code, message, transportProtocolCode);
+    }
+
+    /**
+     * Returns CH server error code. May return 0 if code is unknown.
+     * @return - error code from server response
+     */
+    public int getCode() {
+        return code;
+    }
+
+    /**
+     * Returns error code of underlying transport protocol. For example, HTTP status.
+     * By default, will return {@code 500 } what is derived from HTTP Server Internal Error.
+     *
+     * @return - transport status code
+     */
+    public int getTransportProtocolCode() {
+        return transportProtocolCode;
+    }
+
+    public boolean isRetryable() {
+        return isRetryable;
+    }
+}
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/exception/Utils.java b/client-v2/src/main/java/com/clickhouse/client/api/exception/Utils.java
@@ -0,0 +1,34 @@
+package com.clickhouse.client.api.exception;
+
+public class Utils {
+
+    public static boolean isRetryable(int code, String message, int transportProtocolCode) {
+        //Let's check if we have a ServerException to reference the error code
+        //https://github.com/ClickHouse/ClickHouse/blob/master/src/Common/ErrorCodes.cpp
+        switch (code) { // UNEXPECTED_END_OF_FILE
+            case 3: // UNEXPECTED_END_OF_FILE
+            case 107: // FILE_DOESNT_EXIST
+            case 159: // TIMEOUT_EXCEEDED
+            case 164: // READONLY
+            case 202: // TOO_MANY_SIMULTANEOUS_QUERIES
+            case 203: // NO_FREE_CONNECTION
+            case 209: // SOCKET_TIMEOUT
+            case 210: // NETWORK_ERROR
+            case 241: // MEMORY_LIMIT_EXCEEDED
+            case 242: // TABLE_IS_READ_ONLY
+            case 252: // TOO_MANY_PARTS
+            case 285: // TOO_FEW_LIVE_REPLICAS
+            case 319: // UNKNOWN_STATUS_OF_INSERT
+            case 425: // SYSTEM_ERROR
+            case 999: // KEEPER_EXCEPTION
+                return true;
+            case 0:
+                switch (transportProtocolCode) { // Bad request
+                    case 400: // Bad request
+                    case 500: // Internal server error
+                        return true;
+                };
+        };
+        return false;
+    }
+}
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/internal/ClickHouseLZ4InputStream.java b/client-v2/src/main/java/com/clickhouse/client/api/internal/ClickHouseLZ4InputStream.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.internal;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.data.ClickHouseByteUtils;
 import com.clickhouse.data.ClickHouseCityHash;
 import com.clickhouse.data.ClickHouseUtils;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/internal/HttpAPIClientHelper.java b/client-v2/src/main/java/com/clickhouse/client/api/internal/HttpAPIClientHelper.java
@@ -3,12 +3,12 @@
 import com.clickhouse.client.ClickHouseSslContextProvider;
 import com.clickhouse.client.api.Client;
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.ClientFaultCause;
 import com.clickhouse.client.api.ClientMisconfigurationException;
-import com.clickhouse.client.api.ConnectionInitiationException;
+import com.clickhouse.client.api.exception.ConnectionInitiationException;
 import com.clickhouse.client.api.ConnectionReuseStrategy;
-import com.clickhouse.client.api.ServerException;
+import com.clickhouse.client.api.exception.ServerException;
 import com.clickhouse.client.api.data_formats.internal.SerializerUtils;
 import com.clickhouse.client.api.enums.ProxyType;
 import com.clickhouse.client.api.http.ClickHouseHttpProto;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/metadata/NoSuchColumnException.java b/client-v2/src/main/java/com/clickhouse/client/api/metadata/NoSuchColumnException.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.metadata;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 
 public class NoSuchColumnException extends ClientException {
 
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/query/NullValueException.java b/client-v2/src/main/java/com/clickhouse/client/api/query/NullValueException.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.query;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 
 /**
  * Throw when a null value cannot be returned because of data type.
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/query/QueryResponse.java b/client-v2/src/main/java/com/clickhouse/client/api/query/QueryResponse.java
@@ -1,7 +1,7 @@
 package com.clickhouse.client.api.query;
 
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.http.ClickHouseHttpProto;
 import com.clickhouse.client.api.metrics.OperationMetrics;
 import com.clickhouse.client.api.metrics.ServerMetrics;
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/serde/DataSerializationException.java b/client-v2/src/main/java/com/clickhouse/client/api/serde/DataSerializationException.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.serde;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 
 public class DataSerializationException extends ClientException {
 
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/serde/SerializerNotFoundException.java b/client-v2/src/main/java/com/clickhouse/client/api/serde/SerializerNotFoundException.java
@@ -1,6 +1,6 @@
 package com.clickhouse.client.api.serde;
 
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 
 public class SerializerNotFoundException extends ClientException {
 
diff --git a/client-v2/src/test/java/com/clickhouse/client/ClientTests.java b/client-v2/src/test/java/com/clickhouse/client/ClientTests.java
@@ -2,7 +2,7 @@
 
 import com.clickhouse.client.api.Client;
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.ClientFaultCause;
 import com.clickhouse.client.api.ConnectionReuseStrategy;
 import com.clickhouse.client.api.enums.Protocol;
diff --git a/client-v2/src/test/java/com/clickhouse/client/HttpTransportTests.java b/client-v2/src/test/java/com/clickhouse/client/HttpTransportTests.java
@@ -2,11 +2,11 @@
 
 import com.clickhouse.client.api.Client;
 import com.clickhouse.client.api.ClientConfigProperties;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.ClientFaultCause;
-import com.clickhouse.client.api.ConnectionInitiationException;
+import com.clickhouse.client.api.exception.ConnectionInitiationException;
 import com.clickhouse.client.api.ConnectionReuseStrategy;
-import com.clickhouse.client.api.ServerException;
+import com.clickhouse.client.api.exception.ServerException;
 import com.clickhouse.client.api.command.CommandResponse;
 import com.clickhouse.client.api.command.CommandSettings;
 import com.clickhouse.client.api.enums.Protocol;
diff --git a/client-v2/src/test/java/com/clickhouse/client/ProxyTests.java b/client-v2/src/test/java/com/clickhouse/client/ProxyTests.java
@@ -1,7 +1,7 @@
 package com.clickhouse.client;
 
 import com.clickhouse.client.api.Client;
-import com.clickhouse.client.api.ClientException;
+import com.clickhouse.client.api.exception.ClientException;
 import com.clickhouse.client.api.ClientMisconfigurationException;
 import com.clickhouse.client.api.enums.Protocol;
 import com.clickhouse.client.api.enums.ProxyType;
diff --git a/client-v2/src/test/java/com/clickhouse/client/command/CommandTests.java b/client-v2/src/test/java/com/clickhouse/client/command/CommandTests.java
@@ -5,8 +5,8 @@
 import com.clickhouse.client.ClickHouseProtocol;
 import com.clickhouse.client.ClickHouseServerForTest;
 import com.clickhouse.client.api.Client;
-import com.clickhouse.client.api.ClientException;
-import com.clickhouse.client.api.ServerException;
+import com.clickhouse.client.api.exception.ClientException;
+import com.clickhouse.client.api.exception.ServerException;
 import com.clickhouse.client.api.command.CommandResponse;
 import com.clickhouse.client.api.enums.Protocol;
 import com.clickhouse.client.api.internal.ServerSettings;
diff --git a/client-v2/src/test/java/com/clickhouse/client/insert/InsertTests.java b/client-v2/src/test/java/com/clickhouse/client/insert/InsertTests.java
diff --git a/client-v2/src/test/java/com/clickhouse/client/query/QueryTests.java b/client-v2/src/test/java/com/clickhouse/client/query/QueryTests.java
diff --git a/jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/ExceptionUtils.java b/jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/ExceptionUtils.java
diff --git a/jdbc-v2/src/test/java/com/clickhouse/jdbc/ConnectionTest.java b/jdbc-v2/src/test/java/com/clickhouse/jdbc/ConnectionTest.java
