JDBC Update

@JdbcUpdate defines a JDBC method that executes a SQL update statement. The generated method creates a PreparedStatement, binds Java method parameters, applies statement configuration, executes the update, and optionally maps generated values.

The annotation value must contain a valid SQL statement with named parameters. Parameter binding is defined in parameter binding. Generated values are mapped as defined in result mapping. Converter lookup is defined in converter lookup. Return nullness follows the Nullness Contract.

❗️Update methods

Return values

Without generated values, an @JdbcUpdate method may return:

• void: ignores the update count
• int: returns the value from PreparedStatement.executeUpdate()
• boolean: returns true when the update count is greater than zero

Other return types are supported only when generated values are enabled.

Generated values

Generated values are enabled with @JdbcUpdate(returnGeneratedValues = ...) or with @JdbcUpdate(returnGeneratedColumns = {...}).

The supported generated-value modes are:

• GENERATED_KEYS: execute the update and read PreparedStatement.getGeneratedKeys()
• EXECUTE_QUERY: execute the statement with executeQuery()
• DEFAULT: use the configured default generated-value mode

Named generated columns

returnGeneratedColumns requests generated keys by name. It generates prepareStatement(sql, String[]), executes the update, and maps getGeneratedKeys(). This is useful for JDBC drivers, such as Oracle, that require the generated columns to be named explicitly.

returnGeneratedColumns must be used on its own. When it is non-empty, returnGeneratedValues must be NONE. Combining it with GENERATED_KEYS, EXECUTE_QUERY, or DEFAULT is invalid.

Each requested name must be non-blank and unique. The names are JDBC driver metadata and are not inserted into the SQL text.

A scalar generated-value return type requires exactly one requested name. For a row object return type, every JDBC name used by its record component or constructor parameter must be present in returnGeneratedColumns. Additional requested names are allowed. The requested order does not have to match the row object’s component order; Kaumei JDBC maps every component using its JDBC name and the requested column position.

Generated-value return types must be supported value or row return types. They are mapped with the same result-mapping rules used by @JdbcSelect.

Generated-value return nullness must be unspecified or @NonNull. @Nullable and Optional<T> return types are invalid.

These generated-value return forms are invalid:

• void
• collection return types
• JdbcBatch

Batch update methods

❗️Batch update methods

@JdbcBatchUpdate defines a JDBC method that creates a batch object. The return type must be an interface declared inside the same JDBC service interface as the @JdbcBatchUpdate method. That interface must extend exactly JdbcBatch and must not extend any other interface. The batch interface and its @JdbcUpdate method must not declare type parameters. The return type nullness must be unspecified or @NonNull; @Nullable and Optional<T> are invalid.

The batch interface must declare exactly one non-static, non-default @JdbcUpdate method. That method must be annotated with @JdbcUpdate and must return void.

The SQL for the returned batch object is prepared once. Because of that, the nested @JdbcUpdate method must not use dynamic array or list expansion with :param.{values} or :param.*.

Calling the batch update method binds its parameters and adds one entry to the underlying PreparedStatement batch. The generated batch automatically executes collected entries when the configured batch size is reached.

Batch execution

JdbcBatch.executeBatch() executes currently collected batch entries and resets the current batch count. If no entries are collected, it returns an empty result.

JdbcBatch.close() is resource cleanup. It does not execute collected batch entries. If collected entries are still pending, close() throws an exception. Call executeBatch() before closing when entries are still pending.

@JdbcBatchSize defines the automatic execution size. It may be declared as a constant on the @JdbcBatchUpdate method or as one method parameter.