Merge remote-tracking branch 'origin/main' into polyglot/enum-null-non-nullable-npe

Author: polyglotAI-bot

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 [Release Migration Guide](docs/releases/0_11_0.md)
 
+### New Features
+
+- **[client-v2, jdbc-v2]** Added support for the `BFloat16` data type (ClickHouse `24.11+`). `BFloat16` columns are read as
+  Java `float` values (widening is lossless) and written from `float`/`Float` values, including through generic records, POJO
+  binding, `Nullable(BFloat16)`, and `BFloat16` values held in `Dynamic`/`Variant` columns. On write the client keeps the
+  high 16 bits of the `float`, matching the ClickHouse server's own `Float32` → `BFloat16` conversion. In the JDBC driver
+  (`jdbc-v2`) `BFloat16` maps to `java.sql.Types.FLOAT` / `java.lang.Float` and is read and written through the standard
+  `getFloat`/`setFloat` and `getObject` accessors, and reported as such by `ResultSetMetaData` and `DatabaseMetaData`.
+  Previously reading or writing a `BFloat16` column failed with an
+  unsupported-data-type error. (https://github.com/ClickHouse/clickhouse-java/issues/2279)
+- **[client-v2, jdbc-v2]** Added TLS cipher suite selection. `Client.Builder.setSSLCipherSuites(String...)` (client-v2)
+  and the comma-separated `ssl_cipher_suites` connection property (client-v2 and jdbc-v2) restrict the cipher suites
+  enabled on secure connections; when unset, the transport defaults are used. Cipher-suite selection is independent of the
+  trust configuration and `ssl_mode`. (https://github.com/ClickHouse/clickhouse-java/issues/2882)
+
 ### 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)
@@ -95,6 +110,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. 

clickhouse-data/src/main/java/com/clickhouse/data/ClickHouseDataType.java

@@ -202,6 +202,7 @@ static Map<ClickHouseDataType, Set<Class<?>>> dataTypeClassMap() {
         map.put(String, setOf(String.class));
         map.put(Float64, setOf(float.class, Float.class, double.class, Double.class));
         map.put(Float32, setOf(float.class, Float.class));
+        map.put(BFloat16, setOf(float.class, Float.class));
         map.put(Decimal, setOf(float.class, Float.class, double.class, Double.class, BigDecimal.class));
         map.put(Decimal256, setOf(float.class, Float.class, double.class, Double.class, BigDecimal.class));
         map.put(Decimal128, setOf(float.class, Float.class, double.class, Double.class, BigDecimal.class));

clickhouse-data/src/main/java/com/clickhouse/data/format/BinaryStreamUtils.java

@@ -985,6 +985,21 @@ public static void writeFloat32(OutputStream output, float value) throws IOExcep
         writeInt32(output, Float.floatToIntBits(value));
     }
 
+    /**
+     * Write a bfloat16 value to given output stream. {@code BFloat16} occupies the
+     * high 16 bits of the IEEE-754 {@code float} representation, so the low 16 bits of
+     * the mantissa are dropped (truncated toward zero), which matches how the ClickHouse
+     * server converts {@code Float32} to {@code BFloat16}.
+     *
+     * @param output non-null output stream
+     * @param value  float value to be stored as bfloat16
+     * @throws IOException when failed to write value to output stream or reached
+     *                     end of the stream
+     */
+    public static void writeBFloat16(OutputStream output, float value) throws IOException {
+        writeInt16(output, (short) (Float.floatToIntBits(value) >>> 16));
+    }
+
     /**
      * Read a double value from given input stream.
      *

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

@@ -60,6 +60,7 @@
 import java.time.ZoneId;
 import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
@@ -81,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>
  *
@@ -148,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);
@@ -270,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<>();
@@ -344,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);
@@ -785,6 +809,36 @@ public Builder setSSLMode(SSLMode sslMode) {
             return this;
         }
 
+        /**
+         * Restricts the TLS cipher suites the client may negotiate on secure connections. When set, only
+         * the listed cipher suites are enabled on the SSL socket (subject to what the JVM and the server
+         * support); when not set, the transport defaults are used (Apache HttpClient enables the JVM's
+         * default suites minus those it considers weak). Suite names use the standard JSSE names, for
+         * example {@code TLS_AES_256_GCM_SHA384}.
+         *
+         * @param cipherSuites cipher suite names to enable
+         * @return same instance of the builder
+         */
+        public Builder setSSLCipherSuites(String... cipherSuites) {
+            this.configuration.put(ClientConfigProperties.SSL_CIPHER_SUITES.getKey(),
+                    ClientConfigProperties.commaSeparated(Arrays.asList(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.
@@ -1165,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.
@@ -1229,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),
@@ -204,6 +208,35 @@ public Object parseValue(String value) {
      *  See <a href="https://clickhouse.com/docs/operations/settings/query-level#custom_settings">ClickHouse Docs</a>
      */
     CUSTOM_SETTINGS_PREFIX("custom_settings_prefix", String.class, "custom_"),
+
+    /**
+     * Comma-separated list of TLS cipher suites the client is allowed to negotiate on secure connections.
+     * When set, only these cipher suites are enabled on the SSL socket (subject to what the JVM and server
+     * support); when unset, the transport defaults are used (Apache HttpClient enables the JVM's default
+     * suites minus those it considers weak).
+     * <p>
+     * The value is parsed into a sanitized list here, in the config-parsing layer (not in transport code):
+     * blank tokens produced by a leading, trailing or doubled comma are dropped and each surviving name is
+     * trimmed, so consumers receive a ready-to-use list. A null, empty or whitespace-only entry would
+     * otherwise be rejected by the SSL socket and break the handshake even alongside valid suites.
+     * <p>
+     * Appended at the end of the enum on purpose: adding a constant in the middle would shift the ordinal
+     * of every following constant (see {@code docs/changes_checklist.md}).
+     */
+    SSL_CIPHER_SUITES("ssl_cipher_suites", List.class) {
+        @Override
+        @SuppressWarnings("unchecked")
+        public Object parseValue(String value) {
+            List<String> suites = (List<String>) super.parseValue(value);
+            if (suites == null) {
+                return null;
+            }
+            return suites.stream()
+                    .filter(s -> s != null && !s.trim().isEmpty())
+                    .map(String::trim)
+                    .collect(Collectors.toList());
+        }
+    },
     ;
 
     private static final Logger LOG = LoggerFactory.getLogger(ClientConfigProperties.class);

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

@@ -323,6 +323,7 @@ protected void setSchema(TableSchema schema) {
                 case Int256:
                 case UInt128:
                 case UInt256:
+                case BFloat16:
                 case Float32:
                 case Float64:
                 case Decimal:

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

@@ -164,6 +164,8 @@ public <T> T readValue(ClickHouseColumn column, Class<?> typeHint) throws IOExce
                     return (T) readDecimal(ClickHouseDataType.Decimal128.getMaxPrecision(), scale);
                 case Decimal256:
                     return (T) readDecimal(ClickHouseDataType.Decimal256.getMaxPrecision(), scale);
+                case BFloat16:
+                    return (T) (Float)readBFloat16LE();
                 case Float32:
                     return (T) (Float)readFloatLE();
                 case Float64:
@@ -509,6 +511,18 @@ public float readFloatLE() throws IOException {
         return Float.intBitsToFloat(readIntLE());
     }
 
+    /**
+     * Reads a little-endian {@code BFloat16} value from the internal input stream and
+     * widens it to a {@code float}. {@code BFloat16} carries the high 16 bits of the
+     * IEEE-754 {@code float} representation, so widening (shifting them back into the
+     * high bits) is lossless.
+     * @return float value
+     * @throws IOException when IO error occurs
+     */
+    public float readBFloat16LE() throws IOException {
+        return Float.intBitsToFloat(readUnsignedShortLE() << 16);
+    }
+
     private static final byte[] B1 = new byte[8];
     /**
      * Reads a double value from the internal input stream.
@@ -1268,6 +1282,7 @@ public static boolean isReadToPrimitive(ClickHouseDataType dataType) {
             case Int32:
             case UInt32:
             case Int64:
+            case BFloat16:
             case Float32:
             case Float64:
             case Bool:
@@ -1473,8 +1488,6 @@ private ClickHouseColumn readDynamicData() throws IOException {
             }
             case AggregateFunction:
                 throw new ClientException("Aggregate functions are not supported yet");
-            case BFloat16:
-                throw new ClientException("BFloat16 is not supported yet");
             default:
                 return ClickHouseColumn.of("v", type, false, 0, 0);
         }

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

@@ -554,6 +554,9 @@ private static void serializePrimitiveData(OutputStream stream, Object value, Cl
             case UInt256:
                 BinaryStreamUtils.writeUnsignedInt256(stream, NumberConverter.toBigInteger(value));
                 break;
+            case BFloat16:
+                BinaryStreamUtils.writeBFloat16(stream, (float) value);
+                break;
             case Float32:
                 BinaryStreamUtils.writeFloat32(stream, NumberConverter.toFloat(value));
                 break;
@@ -1116,6 +1119,11 @@ private static void binaryReaderMethodForType(MethodVisitor mv, Class<?> targetT
                 readerMethodReturnType = Type.getDescriptor(long.class);
                 convertOpcode = longToOpcode(targetType);
                 break;
+            case BFloat16:
+                readerMethod = "readBFloat16LE";
+                readerMethodReturnType = Type.getDescriptor(float.class);
+                convertOpcode = floatToOpcode(targetType);
+                break;
             case Float32:
                 readerMethod = "readFloatLE";
                 readerMethodReturnType = Type.getDescriptor(float.class);