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
 - renames `DuckDBScalarContext` into `DuckDBScalarFunctionCallData`
 - removes `DuckDBScalarRow` in favour of streaming plain indices of the
   input vector rows (as a `LongStream`); 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.

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(Integer.class)
+        .withReturnType(Integer.class)
+        .withIntFunction(x -> x + 1)
+        .register(conn);
 }
 ```
 
@@ -41,8 +36,7 @@ SELECT java_add_one(41);
 try (Connection conn = DriverManager.getConnection("jdbc:duckdb:")) {
     DuckDBFunctions.scalarFunction()
         .withName("java_weighted_sum")
-        .withParameter(Double.class)
-        .withParameter(Double.class)
+        .withParameters(Double.class, Double.class)
         .withReturnType(Double.class)
         .withDoubleFunction((x, w) -> x * w + 10.0)
         .register(conn);
@@ -55,15 +49,16 @@ SELECT java_weighted_sum(2.5, 4.0);
 
 Behavior:
 
-- `Function` and `BiFunction` callbacks receive `null` for NULL inputs; implement null handling in Java callback logic.
+- When `.withSpecialHandling()` is set (results in `duckdb_scalar_function_set_special_handling()` C API call),
+  then `Function` and `BiFunction` callbacks receive `null` for NULL inputs; null handling needs to be implemented 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 `withVectorizedFunction(...)`, use `data.propagateNulls(true)` when you want stream-level null skipping and automatic NULL output when **any** of input arguments is NULL.
 - For `Supplier`, returning `null` writes NULL output.
 - `Function` and `BiFunction` are fixed arity only (no varargs).
 
 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`.
 - Invalid row/column indexes throw `IndexOutOfBoundsException`.
 - `SQLException` remains for registration-time API usage and type declaration/validation.
 
@@ -145,7 +140,11 @@ Notes:
 
 ## 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,14 +155,21 @@ 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(...)` for full context control through `DuckDBScalarFunctionCallData` 
+that allows to access input data vectors (single vector for each function argument), and
+the output vector.
+
+`data.stream()` call returns a `LongStream` of the indices of the input rows. 
+Input vectors that can be accessed using `data.input(columnIndex) -> DuckDBReadableVector` method.
+The result of the function invocation for each input `rowIndex` must be set on the 
+`data.output() -> DuckDBWritableVector` vector using the same `rowIndex`.
 
 Example with multiple input types (`TIMESTAMP`, `VARCHAR`, `DOUBLE`) and `VARCHAR` output:
 
@@ -174,16 +180,14 @@ try (Connection conn = DriverManager.getConnection("jdbc:duckdb:");
      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(data -> {
+            data.propagateNulls(true).stream().forEach(rowIndex -> {
+                String value = data.input(0).getLocalDateTime(rowIndex) + " | "
+                    + data.input(1).getString(rowIndex).trim().toUpperCase()
+                    + " | " + data.input(2).getDouble(rowIndex);
+                data.output().setString(rowIndex, value);
             });
         })
         .register(conn);
@@ -196,7 +200,6 @@ 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.
+- `DuckDBScalarFunctionCallData`, `DuckDBReadableVector`, and `DuckDBWritableVector` are valid only during callback execution.
+- Write exactly one output value per input row for each callback invocation *on the same `rowIndex`*.
+- With `propagateNulls(true)`, `DuckDBScalarFunctionCallData.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,7 @@
 import static org.duckdb.DuckDBBindings.*;
 
 import java.nio.ByteBuffer;
+import org.duckdb.DuckDBFunctions.FunctionException;
 
 /**
  * Reader over callback input data chunks.
@@ -17,7 +18,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);
@@ -41,7 +42,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 specialHandlingFlag;
+        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 specialHandlingFlag,
+                                   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.specialHandlingFlag = specialHandlingFlag;
+            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 hasSpecialHandling() {
+            return specialHandlingFlag;
+        }
+
+        public boolean propagateNulls() {
+            return propagateNullsFlag;
+        }
+
+        public boolean isScalar() {
+            return functionKind == Kind.SCALAR;
+        }
+    }
 }