Scalar functions post-integration changes

This is a follow-up to PR duckdb#630.

It makes the following changes to newly added Scalar Functions Java
API:

 - moves exception and registered shell classes into the
   `DuckDBFunction.java`
 - removes abstract classes for vector reader and writer
 - removes `DuckDBScalarContext` and `DuckDBScalarRow` in favour of
   streaming plain indices (as a `LongStream`) from the input data
   chunk; the row object inteface appeared to have an unintended
   overhead of creating a Java object for every input row that we would
   like to avoid. And without it the context abstraction appeared to be
   unnecessary

Null-propagation handling is changed the following way:

 - null propagation on Java side is enabled only for primitive callbacks
   (set automatically) and not exposed to the user, null propagation
   support for object callbacks is removed
 - null propagation on DuckDB engine side (
 `duckdb_scalar_function_set_special_handling` C API call skip) is also
 enabled automatically only for primitive callbacks, but it is
 additionally exposed to users as `withNullInNullOut()` builder call
 (replaces awkwardly named `withSpecialHandling()`); in some cases NULLs
 still can be passed to callbacks wheh `withNullInNullOut()` is
 set so callback still must check for nulls

Testing: more tests added aroung the null handling

Author: staticlibs

UDF.MD

@@ -1,11 +1,6 @@
 # Java Scalar Functions (UDF)
 
 Use `DuckDBFunctions.scalarFunction()` to build and register scalar functions.
-`register(java.sql.Connection)` returns a `DuckDBRegisteredFunction` with metadata about the registered scalar function.
-
-Registered functions are also tracked in a Java-side registry exposed by `DuckDBDriver.registeredFunctions()`.
-This registry is bookkeeping for functions registered through the JDBC API, not an authoritative view of the DuckDB catalog.
-`DuckDBDriver.clearFunctionsRegistry()` clears only the Java-side registry and does not de-register functions from DuckDB.
 
 ## Recommended API (Functional Interfaces)
 
@@ -22,12 +17,12 @@ Use these overloads for simple functions:
 
 ```java
 try (Connection conn = DriverManager.getConnection("jdbc:duckdb:")) {
-    DuckDBRegisteredFunction function = DuckDBFunctions.scalarFunction()
-                                            .withName("java_add_one")
-                                            .withParameter(Integer.class)
-                                            .withReturnType(Integer.class)
-                                            .withIntFunction(x -> x + 1)
-                                            .register(conn);
+    DuckDBFunctions.scalarFunction()
+        .withName("java_add_one")
+        .withParameter(int.class)
+        .withReturnType(int.class)
+        .withIntFunction(x -> x + 1)
+        .register(conn);
 }
 ```
 
@@ -41,9 +36,8 @@ SELECT java_add_one(41);
 try (Connection conn = DriverManager.getConnection("jdbc:duckdb:")) {
     DuckDBFunctions.scalarFunction()
         .withName("java_weighted_sum")
-        .withParameter(Double.class)
-        .withParameter(Double.class)
-        .withReturnType(Double.class)
+        .withParameters(double.class, double.class)
+        .withReturnType(double.class)
         .withDoubleFunction((x, w) -> x * w + 10.0)
         .register(conn);
 }
@@ -53,32 +47,38 @@ try (Connection conn = DriverManager.getConnection("jdbc:duckdb:")) {
 SELECT java_weighted_sum(2.5, 4.0);
 ```
 
-Behavior:
+NULL handling behavior:
 
-- `Function` and `BiFunction` callbacks receive `null` for NULL inputs; implement null handling in Java callback logic.
-- `withIntFunction(...)`, `withLongFunction(...)`, and `withDoubleFunction(...)` run with null propagation enabled.
-- For `withVectorizedFunction(...)`, use `ctx.propagateNulls(true)` when you want stream-level null skipping and automatic NULL output.
-- For `Supplier`, returning `null` writes NULL output.
-- `Function` and `BiFunction` are fixed arity only (no varargs).
+- Java functions that take object arguments (`Function` and `BiFunction` callbacks) are registered with
+  `duckdb_scalar_function_set_special_handling()` C API option enabled - `null` Java arguments are passed for `NULL` input values
+- when `withNullInNullOut()` option is set (skips the `duckdb_scalar_function_set_special_handling()` call on function registration),
+  then DuckDB engine may skip the function call completely (and set `NULL` to the call result automatically),
+  but this does not happen in all cases (for example, when the function is applied to a relation where some rows are `NULL`),
+  so the function still can be passed `null` arguments and need to check them and return `null` accordingly
+- Java functions that take primitive arguments (`withIntFunction(...)`, `withLongFunction(...)`, and `withDoubleFunction(...)`)
+  are never passed `null` arguments as an input - even when the DuckDB engine calls such function with `NULL` value - 
+  the call will be skipped on Java side and `null` value will be returned (returning `null` writes NULL output)
 
 Runtime error model:
 
-- Callback-time reader/writer/context type and value failures throw `DuckDBFunctionException`.
+- Callback-time reader/writer/context type and value failures throw `DuckDBFunctions.CallException extends RuntimeException`.
 - Invalid row/column indexes throw `IndexOutOfBoundsException`.
-- `SQLException` remains for registration-time API usage and type declaration/validation.
+- `SQLException` is used for registration-time API usage and type declaration/validation.
 
 ## Type declaration and mapping
 
 `withParameter(...)` and `withReturnType(...)` accept:
 
-- `Class<?>`
+- `Class<?>` (Object or primitive class, like `int.class` or `Integer.TYPE`)
 - `DuckDBColumnType`
 - `DuckDBLogicalType`
 
 Common class mappings include:
 
-- `Integer` -> `INTEGER`
-- `Long` -> `BIGINT`
+- `int` -> `INTEGER`
+- `long` -> `BIGINT`
+- `float` -> `FLOAT`
+- `double` -> `DOUBLE`
 - `String` -> `VARCHAR`
 - `BigDecimal` -> `DECIMAL`
 - `BigInteger` -> `HUGEINT`
@@ -140,12 +140,16 @@ Notes:
 - `withVarArgsFunction(Function<Object[], ?>)`
 - `withVectorizedFunction(DuckDBScalarFunction)`
 - `withVolatile()`
-- `withSpecialHandling()`
+- `withNullInNullOut()`
 - `register(java.sql.Connection)`
 
 ## Registered Function Metadata And Registry
 
-`DuckDBRegisteredFunction` exposes immutable metadata about the successful registration result:
+Registered functions, returned from `.register()` call, are additionally tracked in a Java-side registry exposed by `DuckDBDriver.registeredFunctions()`.
+This registry provides bookkeeping for functions registered through the JDBC API, not an authoritative view of the DuckDB catalog.
+`DuckDBDriver.clearFunctionsRegistry()` clears only the Java-side registry and does not de-register functions from DuckDB.
+
+`DuckDBFunctions.RegisteredFunction` exposes immutable metadata about the successful registration result:
 
 - `name()`
 - `functionKind()`
@@ -156,47 +160,50 @@ Notes:
 To inspect Java-side registrations:
 
 ```java
-List<DuckDBRegisteredFunction> functions = DuckDBDriver.registeredFunctions();
+List<DuckDBFunctions.RegisteredFunction> functions = DuckDBDriver.registeredFunctions();
 ```
 
 The returned list is read-only. Duplicate function names may appear in the registry.
 
 ## Advanced API (`DuckDBScalarFunction`)
 
-Use `withVectorizedFunction(...)` for full context control through `DuckDBScalarContext`.
+Use `withVectorizedFunction(...)` to access multiple input rows (when the scalar function is applied
+to a row set from a relation) in a single call. DuckDB engine splits the input row set into "data chunks"
+(represented in Java as `DuckDBDataChunkReader`) each chunk containing up to 2048 rows.
+
+`DuckDBScalarFunction` callback receives the `DuckDBDataChunkReader` as an `input` argument.
+Data chunk contains a number of "data vectors" (`DuckDBReadableVector`) - single vector for each input column.
+Vectors can be accessed using `input.vector(columnIndex)`. It writes the results into  the `output` `DuckDBWritableVector`.
+Results in the `output` vector must be set **on the same `row` indices** that are used to read `input`.
+
+`input.stream()` call returns a `LongStream` of `row` indices that can be used with Java Streams API. 
+
+- `DuckDBDataChunkReader`, `DuckDBReadableVector`, and `DuckDBWritableVector` are valid only during callback execution.
 
 Example with multiple input types (`TIMESTAMP`, `VARCHAR`, `DOUBLE`) and `VARCHAR` output:
 
-```java
-try (Connection conn = DriverManager.getConnection("jdbc:duckdb:");
+```
+try (Connection conn = DriverManager.getConnection("jdbc:duckdb:"); Statement stmt = conn.createStatement();
      DuckDBLogicalType tsType = DuckDBLogicalType.of(DuckDBColumnType.TIMESTAMP);
      DuckDBLogicalType strType = DuckDBLogicalType.of(DuckDBColumnType.VARCHAR);
      DuckDBLogicalType dblType = DuckDBLogicalType.of(DuckDBColumnType.DOUBLE)) {
     DuckDBFunctions.scalarFunction()
         .withName("java_event_label")
-        .withParameter(tsType)
-        .withParameter(strType)
-        .withParameter(dblType)
+        .withParameters(tsType, strType, dblType)
         .withReturnType(strType)
-        .withVectorizedFunction(ctx -> {
-            ctx.propagateNulls(true).stream().forEachOrdered(row -> {
-                String value = row.getLocalDateTime(0) + " | "
-                    + row.getString(1).trim().toUpperCase()
-                    + " | " + row.getDouble(2);
-                row.setString(value);
+        .withVectorizedFunction((input, output) -> {
+            input.stream().forEach(row -> {
+                String value = input.vector(0).getLocalDateTime(row) + " | " +
+                               String.valueOf(input.vector(1).getString(row)).trim().toUpperCase() + " | " +
+                               input.vector(2).getDouble(row, 0.0d);
+                output.setString(row, value);
             });
         })
         .register(conn);
+    ...
 }
 ```
 
 ```sql
 SELECT java_event_label(TIMESTAMP '2026-04-04 12:00:00', 'launch', 4.5);
 ```
-
-Lifecycle rules:
-
-- `DuckDBScalarContext`, `DuckDBScalarRow`, `DuckDBReadableVector`, and `DuckDBWritableVector` are valid only during callback execution.
-- `DuckDBReadableVector` and `DuckDBWritableVector` are abstract callback runtime types (not interfaces).
-- Write exactly one output value per input row for each callback invocation.
-- With `propagateNulls(true)`, `DuckDBScalarContext.stream()` skips rows that contain NULL in any input column and writes NULL to the output for those rows.

src/main/java/org/duckdb/DuckDBDataChunkReader.java

@@ -3,6 +3,8 @@
 import static org.duckdb.DuckDBBindings.*;
 
 import java.nio.ByteBuffer;
+import java.util.stream.LongStream;
+import org.duckdb.DuckDBFunctions.FunctionException;
 
 /**
  * Reader over callback input data chunks.
@@ -17,7 +19,7 @@ public final class DuckDBDataChunkReader {
 
     DuckDBDataChunkReader(ByteBuffer chunkRef) {
         if (chunkRef == null) {
-            throw new DuckDBFunctionException("Invalid data chunk reference");
+            throw new FunctionException("Invalid data chunk reference");
         }
         this.chunkRef = chunkRef;
         this.rowCount = duckdb_data_chunk_get_size(chunkRef);
@@ -33,6 +35,10 @@ public long columnCount() {
         return columnCount;
     }
 
+    public LongStream stream() {
+        return LongStream.range(0, rowCount);
+    }
+
     public DuckDBReadableVector vector(long columnIndex) {
         if (columnIndex < 0 || columnIndex >= columnCount) {
             throw new IndexOutOfBoundsException("Column index out of bounds: " + columnIndex);
@@ -41,7 +47,7 @@ public DuckDBReadableVector vector(long columnIndex) {
         DuckDBReadableVector vector = vectors[arrayIndex];
         if (vector == null) {
             ByteBuffer vectorRef = duckdb_data_chunk_get_vector(chunkRef, columnIndex);
-            vector = new DuckDBReadableVectorImpl(vectorRef, rowCount);
+            vector = new DuckDBReadableVector(vectorRef, rowCount);
             vectors[arrayIndex] = vector;
         }
         return vector;

src/main/java/org/duckdb/DuckDBDriver.java

@@ -16,6 +16,7 @@
 import java.util.concurrent.ThreadFactory;
 import java.util.concurrent.locks.ReentrantLock;
 import java.util.logging.Logger;
+import org.duckdb.DuckDBFunctions.RegisteredFunction;
 import org.duckdb.io.LimitedInputStream;
 
 public class DuckDBDriver implements java.sql.Driver {
@@ -42,7 +43,7 @@ public class DuckDBDriver implements java.sql.Driver {
     private static boolean pinnedDbRefsShutdownHookRegistered = false;
     private static boolean pinnedDbRefsShutdownHookRun = false;
 
-    private static final ArrayList<DuckDBRegisteredFunction> functionsRegistry = new ArrayList<>();
+    private static final ArrayList<RegisteredFunction> functionsRegistry = new ArrayList<>();
     private static final ReentrantLock functionsRegistryLock = new ReentrantLock();
 
     private static final Set<String> supportedOptions = new LinkedHashSet<>();
@@ -266,7 +267,7 @@ public static boolean shutdownQueryCancelScheduler() {
         return true;
     }
 
-    public static List<DuckDBRegisteredFunction> registeredFunctions() {
+    public static List<RegisteredFunction> registeredFunctions() {
         functionsRegistryLock.lock();
         try {
             return Collections.unmodifiableList(new ArrayList<>(functionsRegistry));
@@ -284,7 +285,7 @@ public static void clearFunctionsRegistry() {
         }
     }
 
-    static void registerFunction(DuckDBRegisteredFunction function) {
+    static void registerFunction(RegisteredFunction function) {
         functionsRegistryLock.lock();
         try {
             functionsRegistry.add(function);

src/main/java/org/duckdb/DuckDBFunctionException.java

@@ -1,14 +1,121 @@
 package org.duckdb;
 
 import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 
 public final class DuckDBFunctions {
-    public enum DuckDBFunctionKind { SCALAR }
+    public enum Kind { SCALAR }
 
     private DuckDBFunctions() {
     }
 
     public static DuckDBScalarFunctionBuilder scalarFunction() throws SQLException {
         return new DuckDBScalarFunctionBuilder();
     }
+
+    static RegisteredFunction createRegisteredFunction(String name, List<DuckDBLogicalType> parameterTypes,
+                                                       List<DuckDBColumnType> parameterColumnTypes,
+                                                       DuckDBLogicalType returnType, DuckDBColumnType returnColumnType,
+                                                       DuckDBScalarFunction function, DuckDBLogicalType varArgType,
+                                                       boolean volatileFlag, boolean specialHandlingFlag,
+                                                       boolean propagateNullsFlag) {
+        return new RegisteredFunction(name, Kind.SCALAR, Collections.unmodifiableList(new ArrayList<>(parameterTypes)),
+                                      Collections.unmodifiableList(new ArrayList<>(parameterColumnTypes)), returnType,
+                                      returnColumnType, function, varArgType, volatileFlag, specialHandlingFlag,
+                                      propagateNullsFlag);
+    }
+
+    public static class FunctionException extends RuntimeException {
+        private static final long serialVersionUID = 1L;
+
+        public FunctionException(String message) {
+            super(message);
+        }
+
+        public FunctionException(String message, Throwable cause) {
+            super(message, cause);
+        }
+    }
+
+    public static final class RegisteredFunction {
+        private final String name;
+        private final Kind functionKind;
+        private final List<DuckDBLogicalType> parameterTypes;
+        private final List<DuckDBColumnType> parameterColumnTypes;
+        private final DuckDBLogicalType returnType;
+        private final DuckDBColumnType returnColumnType;
+        private final DuckDBScalarFunction function;
+        private final DuckDBLogicalType varArgType;
+        private final boolean volatileFlag;
+        private final boolean nullInNullOutFlag;
+        private final boolean propagateNullsFlag;
+
+        private RegisteredFunction(String name, Kind functionKind, List<DuckDBLogicalType> parameterTypes,
+                                   List<DuckDBColumnType> parameterColumnTypes, DuckDBLogicalType returnType,
+                                   DuckDBColumnType returnColumnType, DuckDBScalarFunction function,
+                                   DuckDBLogicalType varArgType, boolean volatileFlag, boolean nullInNullOutFlag,
+                                   boolean propagateNullsFlag) {
+            this.name = name;
+            this.functionKind = functionKind;
+            this.parameterTypes = parameterTypes;
+            this.parameterColumnTypes = parameterColumnTypes;
+            this.returnType = returnType;
+            this.returnColumnType = returnColumnType;
+            this.function = function;
+            this.varArgType = varArgType;
+            this.volatileFlag = volatileFlag;
+            this.nullInNullOutFlag = nullInNullOutFlag;
+            this.propagateNullsFlag = propagateNullsFlag;
+        }
+
+        public String name() {
+            return name;
+        }
+
+        public Kind functionKind() {
+            return functionKind;
+        }
+
+        public List<DuckDBLogicalType> parameterTypes() {
+            return parameterTypes;
+        }
+
+        public List<DuckDBColumnType> parameterColumnTypes() {
+            return parameterColumnTypes;
+        }
+
+        public DuckDBLogicalType returnType() {
+            return returnType;
+        }
+
+        public DuckDBColumnType returnColumnType() {
+            return returnColumnType;
+        }
+
+        public DuckDBScalarFunction function() {
+            return function;
+        }
+
+        public DuckDBLogicalType varArgType() {
+            return varArgType;
+        }
+
+        public boolean isVolatile() {
+            return volatileFlag;
+        }
+
+        public boolean isNullInNullOut() {
+            return nullInNullOutFlag;
+        }
+
+        public boolean propagateNulls() {
+            return propagateNullsFlag;
+        }
+
+        public boolean isScalar() {
+            return functionKind == Kind.SCALAR;
+        }
+    }
 }