Skip to content
Kaumei JDBC Kaumei JDBC

✅ Parameter Binding

❗️Statement

Parameter binding maps Java method parameters to named SQL markers. The marker format controls how one Java parameter is represented in SQL. Java-to-JDBC converter lookup is described in converter lookup.

Converter names

Section titled “Converter names”
❗️Converter Names

Named converter lookup is described in converter lookup. For parameter binding, @JdbcConverterName("name") selects a named converter on a method parameter. The named converter is applied to the parameter as a whole and is valid only with the whole-parameter :param marker format.

@JdbcConverterName is invalid with :param.{values}, :param.{names}, and :param.*.

Markers

Section titled “Markers”
❗️Marker

Kaumei JDBC uses named SQL markers. Each marker name starts with :, for example :name. JDBC ? markers are not supported.

Every SQL marker must match a Java method parameter name. SQL markers without a matching method parameter are invalid.

The marker format defines how the parameter is bound:

  • :param binds exactly one JDBC value. If the Java parameter is a record, array, or list, it is still bound as one value and needs a matching converter for the whole parameter.
  • :param.{values} expands the Java parameter into multiple JDBC values. Records expand their component values in declaration order. Arrays and lists expand their elements in iteration order.
  • :param.* is equivalent to :param.{values}.
  • :param.{names} expands record component names in declaration order. It is valid only for record parameters.
  • @JdbcName on a record component changes the expanded name used by :param.{names}.

JDBC basic types

Section titled “JDBC basic types”
❗️JDBC Types ❗️JDBC Additional Types

The following JDBC Java types are mapped by default to the PreparedStatement.set... methods:

  • java.lang.String, java.math.BigDecimal, boolean, byte, short, int, long, float, double, byte[], java.sql.Date, java.sql.Time, java.sql.Timestamp, java.sql.Clob, java.sql.Blob, java.sql.Array, java.sql.Ref, java.net.URL, java.sql.RowId, java.sql.NClob, java.sql.SQLXML
  • java.sql.Struct (via setObject)
  • In addition, the following types are supported by default converters that map to the underlying PreparedStatement method:
    • java.lang.Boolean, java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float, java.lang.Double
    • char, java.lang.Character (via setString)
  • Some JDBC drivers do not support all native JDBC types. Check your driver’s documentation.

Java default converters

Section titled “Java default converters”
❗️Record ❗️Enum

Default converters are considered only after converter lookup does not find a matching converter. For the exact lookup order, see converter lookup.

  • Records with exactly one component can use that component as their JDBC value. The component may itself use another converter, but the resolved conversion chain must end in a JDBC-supported value.
  • Enums can use their enum name as a String JDBC value.

Custom converters

Section titled “Custom converters”

The developer can define converters to set JDBC values from Java.

  • ❗️Simple A static simple converter converts a value T into a supported JDBC value R: static R toDB(T value)
    • Parameter and return must be unspecific or non-null.
    • The method must be annotated with @JavaToJdbc
  • ❗️Statement A static JDBC converter sets a value R on a given PreparedStatement: static void toDB(PreparedStatement stmt, int index, T value) The parameter value must be nullable or unspecific. The method must handle null correctly. The method must be annotated with @JavaToJdbc
  • ❗️Object An object method annotated with @JavaToJdbc returns the object value as a JDBC value. The return value must be unspecific or non-null.

Collections and arrays

Section titled “Collections and arrays”
❗️Collections

Arrays and lists are expanded only when the SQL uses :param.{values} or :param.*. The normal :param marker binds the array or list as one JDBC value and needs a matching converter for the whole parameter.

Expansion is useful for SQL IN (...) clauses and for SQL statements that bind several values from one record, such as INSERT INTO (...) VALUES (...). For practical parameter examples, see mapping Java parameters to JDBC. The number of generated JDBC placeholders matches the size of the array or list. Check your JDBC driver and database documentation for any limits on the maximum size of an IN (...) clause.

  • Nullable collections/arrays are not allowed
  • Nullable collection elements are allowed when the collection element type allows null values
  • Primitive array elements are always non-null values