Parameter Binding

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. Parameter nullness terms are defined in the Nullness Contract.

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}. Values used as expanded record component names must not be blank.

Plain property paths are not supported in parameter binding. Use one of the marker formats listed above. A method parameter must also keep one binding shape within one SQL statement; for example, do not mix :param with :param.{values} for the same parameter.

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 values used for parameter binding must not be blank.

@JdbcConverterName is invalid with :param.{values}, :param.{names}, and :param.*. Record components may still use @JdbcConverterName when their values are expanded with :param.{values}.

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

❗️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

❗️Invalid 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 valueR:
  • shape: static R toDB(T value)
  • Parameter and return must be unspecified or non-null.
  • The method must be annotated with @JavaToJdbc
• ❗️Statement A static JDBC converter sets a value R on a given PreparedStatement:
  • shape: static void toDB(PreparedStatement stmt, int index, T value)
  • The parameter value must be nullable or unspecified.
  • 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 unspecified or non-null.

Collections and arrays

❗️Collections

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

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.

Optional<T> is not supported as a JDBC method parameter or as an expanded collection/array element.

• 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