Merge origin/main into polyglot/client-v2-ssl-cipher-suites

Resolve conflicts with #2918 (application-supplied SSLContext), which merged
to main and touched the same client-v2 SSL surface. Union both SSL features
(no behavior change to either):

- Client.java: keep both Builder.setSSLCipherSuites(...) and setSSLContext(...)
- ClientBuilderTest / JdbcConfigurationTest: keep both sides' test methods
- docs/features.md: keep both the cipher-suite and custom-SSLContext bullets
- examples client-v2 + jdbc SSLExamples: keep both example methods + call sites
- CHANGELOG.md: keep both New Features entries (auto-merged, distinct releases)

ClientConfigProperties (SSL_CIPHER_SUITES stays the last enum constant) and
HttpAPIClientHelper.createHttpClient (custom-context selection + cipher-suite
socket factory) auto-merged cleanly and now integrate both features.

Author: polyglotAI-bot

CHANGELOG.md

@@ -11,6 +11,15 @@
 
 ### Bug Fixes 
 
+- **[client-v2]** Fixed binary array decoding for nullable element types so `Array(Nullable(Float64))` and similar columns now return boxed arrays such as `Double[]` instead of `Object[]`. This keeps null-supporting arrays aligned with their element type while preserving the existing `Object[]` fallback for Variant/Dynamic/Geometry arrays. (https://github.com/ClickHouse/clickhouse-java/issues/2846)
+
+- **[client-v2]** Fixed `Float32`/`Float64` columns throwing `ClassCastException` when a value of a
+  non-matching boxed numeric type was supplied through the `Object`-typed insert surface — for example a
+  `Double` (the natural type of a Java literal like `1.5`) for a `Float32` column, or a `Float` for a
+  `Float64` column. The `RowBinary` serializer now narrows any `Number` (and, like the `Int*` columns,
+  a `String`/`Boolean`) through `Number#floatValue()`/`Number#doubleValue()`, so the float columns accept
+  the same value types the integer columns already did. (https://github.com/ClickHouse/clickhouse-java/issues/2930)
+
 - **[client-v2]** Fixed POJO insert error classification so transport write failures such as java.net.SocketException:
   Broken pipe (Write failed) are now surfaced as transfer/network errors instead of being wrapped as
   DataSerializationException. This only changes the exception type reported for request-body transport failures during
@@ -87,6 +96,17 @@
 
 ### New Features
 
+- **[client-v2, jdbc-v2]** Added support for an application-supplied `javax.net.ssl.SSLContext`. In client-v2,
+  `Client.Builder.setSSLContext(SSLContext)` hands the client a fully pre-built context that is used as is; in
+  jdbc-v2 the same context may be passed as a live object in the connection `Properties` under the `ssl_context`
+  key (added with `Properties.put`, since it is not a string). Trust/key material options cannot be combined with
+  a custom context and are rejected; `ssl_mode` still applies but only to server hostname verification. This
+  supports in-memory TLS material that must never be written to disk, including behind connection pools that only
+  expose `java.util.Properties`.
+  - Examples for client-v2 https://github.com/ClickHouse/clickhouse-java/blob/main/examples/client-v2/src/main/java/com/clickhouse/examples/client_v2/SSLExamples.java
+  - Examples for jdbc-v2 https://github.com/ClickHouse/clickhouse-java/blob/main/examples/jdbc/src/main/java/com/clickhouse/examples/jdbc/SSLExamples.java
+  (https://github.com/ClickHouse/clickhouse-java/pull/2918, https://github.com/ClickHouse/clickhouse-java/issues/2909)
+
 - **[jdbc-v2, client-v2]** Implemented SSL modes configuration. Now it is possible to set `ssl_mode` to `DISABLED`, 
   `TRUST`, `VERIFY_CA` and `STRICT`. Note for V1 users: `NONE` is supported only by JDBC driver and mapped to `TRUST`.
   Please migrate to the new naming. 

client-v2/src/main/java/com/clickhouse/client/api/Client.java

@@ -82,6 +82,8 @@
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 
+import javax.net.ssl.SSLContext;
+
 /**
  * <p>Client is the starting point for all interactions with ClickHouse. </p>
  *
@@ -149,8 +151,12 @@ public class Client implements AutoCloseable {
 
     private Client(Collection<Endpoint> endpoints, Map<String,String> configuration,
                    ExecutorService sharedOperationExecutor, ColumnToMethodMatchingStrategy columnToMethodMatchingStrategy,
-                   Object metricsRegistry, Supplier<String> queryIdGenerator, CredentialsManager cManager) {
+                   Object metricsRegistry, Supplier<String> queryIdGenerator, CredentialsManager cManager,
+                   SSLContext sslContext) {
         Map<String, Object> parsedConfiguration = new ConcurrentHashMap<>(ClientConfigProperties.parseConfigMap(configuration));
+        if (sslContext != null) {
+            parsedConfiguration.put(ClientConfigProperties.SSL_CONTEXT.getKey(), sslContext);
+        }
         this.credentialsManager = cManager;
         this.session = Session.extractFrom(parsedConfiguration);
         this.configuration = new ConcurrentHashMap<>(parsedConfiguration);
@@ -271,6 +277,18 @@ public static class Builder {
         private ColumnToMethodMatchingStrategy columnToMethodMatchingStrategy;
         private Object metricRegistry = null;
         private Supplier<String> queryIdGenerator;
+        private SSLContext sslContext = null;
+
+        // Trust/key material options that feed a context the client would otherwise build; none of them
+        // may be combined with an application-supplied SSLContext (see build()).
+        private static final ClientConfigProperties[] SSL_MATERIAL_PROPERTIES = {
+                ClientConfigProperties.SSL_TRUST_STORE,
+                ClientConfigProperties.SSL_KEYSTORE_TYPE,
+                ClientConfigProperties.SSL_KEY_STORE_PASSWORD,
+                ClientConfigProperties.SSL_KEY,
+                ClientConfigProperties.CA_CERTIFICATE,
+                ClientConfigProperties.SSL_CERTIFICATE,
+        };
 
         public Builder() {
             this.endpoints = new LinkedHashSet<>();
@@ -345,6 +363,11 @@ private Builder addEndpoint(Endpoint endpoint) {
          * @param value - configuration option value
          */
         public Builder setOption(String key, String value) {
+            if (key.equals(ClientConfigProperties.SSL_CONTEXT.getKey())) {
+                throw new ClientMisconfigurationException("'" + ClientConfigProperties.SSL_CONTEXT.getKey()
+                        + "' cannot be set as a string; supply a javax.net.ssl.SSLContext object via "
+                        + "Client.Builder.setSSLContext(...)");
+            }
             this.configuration.put(key, value);
             if (key.equals(ClientConfigProperties.PRODUCT_NAME.getKey())) {
                 setClientName(value);
@@ -802,6 +825,20 @@ public Builder setSSLCipherSuites(String... cipherSuites) {
             return this;
         }
 
+        /**
+         * Supplies a pre-built {@link SSLContext}. When set, it is used as is instead of a context built
+         * from the configured trust/key material (which then cannot be set alongside it). {@link SSLMode}
+         * still applies, but only to server hostname verification: {@link SSLMode#STRICT} (default) enforces
+         * it while {@link SSLMode#TRUST} and {@link SSLMode#VERIFY_CA} skip it.
+         *
+         * @param sslContext a fully configured SSL context; {@code null} clears any previously set context
+         * @return same instance of the builder
+         */
+        public Builder setSSLContext(SSLContext sslContext) {
+            this.sslContext = sslContext;
+            return this;
+        }
+
         /**
          * Configure client to use server timezone for date/datetime columns. Default is true.
          * If this options is selected then server timezone should be set as well.
@@ -1182,14 +1219,28 @@ public Client build() {
 
             CredentialsManager cManager = new CredentialsManager(this.configuration);
 
-            if (configuration.containsKey(ClientConfigProperties.SSL_TRUST_STORE.getKey()) &&
+            // A textual 'ssl_context' can never be a live context (also rejected in setOption).
+            if (configuration.containsKey(ClientConfigProperties.SSL_CONTEXT.getKey())) {
+                throw new ClientMisconfigurationException("'" + ClientConfigProperties.SSL_CONTEXT.getKey()
+                        + "' cannot be set as a string; supply a javax.net.ssl.SSLContext object via "
+                        + "Client.Builder.setSSLContext(...)");
+            }
+
+            if (this.sslContext != null) {
+                // A custom SSLContext replaces any context the client would build, so trust/key material
+                // cannot be set alongside it. SSL_MODE (hostname verification) is still allowed.
+                for (ClientConfigProperties material : SSL_MATERIAL_PROPERTIES) {
+                    if (configuration.containsKey(material.getKey())) {
+                        throw new ClientMisconfigurationException("'" + material.getKey() + "' cannot be combined"
+                                + " with a custom SSLContext; the supplied context is used as is. Only 'ssl_mode'"
+                                + " (hostname verification) may be set alongside it.");
+                    }
+                }
+            } else if (configuration.containsKey(ClientConfigProperties.SSL_TRUST_STORE.getKey()) &&
                     configuration.containsKey(ClientConfigProperties.SSL_CERTIFICATE.getKey())) {
                 throw new ClientMisconfigurationException("Trust store and certificates cannot be used together");
             }
 
-            // A trust store and a CA certificate are not rejected here: for VERIFY_CA/STRICT the trust
-            // store takes precedence and the CA certificate is ignored with a warning (see createSSLContext).
-
             // Resolve ssl_mode case-insensitively and normalize it to the canonical enum name so that
             // downstream parsing is consistent and an unknown value is reported as a misconfiguration
             // here instead of failing later with a generic enum-parsing error.
@@ -1246,7 +1297,8 @@ public Client build() {
             }
 
             return new Client(this.endpoints, this.configuration, this.sharedOperationExecutor,
-                this.columnToMethodMatchingStrategy, this.metricRegistry, this.queryIdGenerator, cManager);
+                this.columnToMethodMatchingStrategy, this.metricRegistry, this.queryIdGenerator, cManager,
+                this.sslContext);
         }
     }
 

client-v2/src/main/java/com/clickhouse/client/api/ClientConfigProperties.java

@@ -8,6 +8,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import javax.net.ssl.SSLContext;
+
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
@@ -118,6 +120,8 @@ public enum ClientConfigProperties {
 
     SSL_MODE("ssl_mode", SSLMode.class, SSLMode.STRICT.name()),
 
+    SSL_CONTEXT("ssl_context", SSLContext.class),
+
     RETRY_ON_FAILURE("retry", Integer.class, "3"),
 
     INPUT_OUTPUT_FORMAT("format", ClickHouseFormat.class),

client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/BinaryStreamReader.java

@@ -609,8 +609,8 @@ public ArrayValue readArray(ClickHouseColumn column) throws IOException {
         ArrayValue array;
         ClickHouseColumn itemTypeColumn = column.getNestedColumns().get(0);
         if (len == 0) {
-            Class<?> itemClass = itemTypeColumn.getDataType().getPrimitiveClass();
-            array = new ArrayValue(itemClass == null ? Object.class : itemClass, 0);
+            Class<?> itemClass = resolveArrayItemClass(itemTypeColumn);
+            array = new ArrayValue(itemClass, 0);
         } else if (column.getArrayNestedLevel() == 1) {
             array = readArrayItem(itemTypeColumn, len);
         } else {
@@ -625,8 +625,13 @@ public ArrayValue readArray(ClickHouseColumn column) throws IOException {
 
     public ArrayValue readArrayItem(ClickHouseColumn itemTypeColumn, int len) throws IOException {
         ArrayValue array;
-        if (itemTypeColumn.isNullable()
-                || itemTypeColumn.getDataType() == ClickHouseDataType.Variant
+        if (itemTypeColumn.isNullable()) {
+            Class<?> itemClass = resolveArrayItemClass(itemTypeColumn);
+            array = new ArrayValue(itemClass, len);
+            for (int i = 0; i < len; i++) {
+                array.set(i, readValue(itemTypeColumn));
+            }
+        } else if (itemTypeColumn.getDataType() == ClickHouseDataType.Variant
                 || itemTypeColumn.getDataType() == ClickHouseDataType.Dynamic
                 || itemTypeColumn.getDataType() == ClickHouseDataType.Geometry) {
             array = new ArrayValue(Object.class, len);
@@ -667,6 +672,64 @@ public ArrayValue readArrayItem(ClickHouseColumn itemTypeColumn, int len) throws
         return array;
     }
 
+    /**
+     * Resolves the Java class that {@link #readValue} actually returns for a given column
+     * so that it can be used as the component type of an array.
+     *
+     * <p>For unsigned integer types, {@code readValue} widens the value (e.g. UInt8 → Short,
+     * UInt32 → Long), so we use {@link ClickHouseDataType#getWiderObjectClass()} or 
+     * {@link ClickHouseDataType#getWiderPrimitiveClass()} which mirrors that widening.
+     * For Enum types, {@code readValue} returns {@link EnumValue} rather than the
+     * declared {@code String.class}. All other types use {@link ClickHouseDataType#getObjectClass()}
+     * or {@link ClickHouseDataType#getPrimitiveClass()}.
+     *
+     * @param itemTypeColumn the element column of the array
+     * @return the Java class to use as the array component type; never {@code null}
+     */
+    private static Class<?> resolveArrayItemClass(ClickHouseColumn itemTypeColumn) {
+        ClickHouseDataType dataType = itemTypeColumn.getDataType();
+        if (itemTypeColumn.isNullable()) {
+            switch (dataType) {
+                case UInt8:
+                case UInt16:
+                case UInt32:
+                case UInt64:
+                    return dataType.getWiderObjectClass();
+                case Enum8:
+                case Enum16:
+                    return EnumValue.class;
+                default:
+                    Class<?> cls = dataType.getObjectClass();
+                    return cls == null ? Object.class : cls;
+            }
+        } else {
+            switch (dataType) {
+                case UInt8:
+                case UInt16:
+                case UInt32:
+                case UInt64:
+                    return dataType.getWiderPrimitiveClass();
+                case Enum8:
+                case Enum16:
+                    return EnumValue.class;
+                case Variant:
+                case Dynamic:
+                case Geometry:
+                    return Object.class;
+                case Array:
+                    return ArrayValue.class;
+                case Tuple:
+                case Nested:
+                    return Object[].class;
+                case Map:
+                    return Map.class;
+                default:
+                    Class<?> cls = dataType.getPrimitiveClass();
+                    return cls == null ? Object.class : cls;
+            }
+        }
+    }
+
     public void skipValue(ClickHouseColumn column) throws IOException {
         readValue(column, null);
     }

client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/SerializerUtils.java

@@ -555,10 +555,10 @@ private static void serializePrimitiveData(OutputStream stream, Object value, Cl
                 BinaryStreamUtils.writeUnsignedInt256(stream, NumberConverter.toBigInteger(value));
                 break;
             case Float32:
-                BinaryStreamUtils.writeFloat32(stream, (float) value);
+                BinaryStreamUtils.writeFloat32(stream, NumberConverter.toFloat(value));
                 break;
             case Float64:
-                BinaryStreamUtils.writeFloat64(stream, (double) value);
+                BinaryStreamUtils.writeFloat64(stream, NumberConverter.toDouble(value));
                 break;
             case Decimal:
             case Decimal32:

client-v2/src/main/java/com/clickhouse/client/api/internal/HttpAPIClientHelper.java

@@ -154,7 +154,7 @@ public HttpAPIClientHelper(Map<String, Object> configuration, Object metricsRegi
     }
 
     /**
-     * Creates or returns default SSL context.
+     * Creates an SSL context from the configured trust/key material.
      *
      * @return SSLContext
      */
@@ -280,7 +280,21 @@ private HttpClientConnectionManager poolConnectionManager(LayeredConnectionSocke
     public CloseableHttpClient createHttpClient(boolean initSslContext, Map<String, Object> configuration) {
         // Top Level builders
         HttpClientBuilder clientBuilder = HttpClientBuilder.create();
-        SSLContext sslContext = initSslContext ? createSSLContext(configuration) : null;
+        // An application-supplied SSLContext is used as is; otherwise one is built from the configured
+        // trust/key material. Server hostname verification below still applies via the SSL mode.
+        SSLContext sslContext = null;
+        if (initSslContext) {
+            Object customSSLContext = configuration.get(ClientConfigProperties.SSL_CONTEXT.getKey());
+            if (customSSLContext == null) {
+                sslContext = createSSLContext(configuration);
+            } else if (customSSLContext instanceof SSLContext) {
+                sslContext = (SSLContext) customSSLContext;
+            } else {
+                throw new ClientMisconfigurationException("'" + ClientConfigProperties.SSL_CONTEXT.getKey()
+                        + "' must be a javax.net.ssl.SSLContext instance but was "
+                        + customSSLContext.getClass().getName() + "; supply it via Client.Builder.setSSLContext(...)");
+            }
+        }
         LayeredConnectionSocketFactory sslConnectionSocketFactory;
         if (sslContext != null) {
             String socketSNI = (String)configuration.get(ClientConfigProperties.SSL_SOCKET_SNI.getKey());