Package org.eclipse.net4j.db.dml

Interface SQLParameterBinder

public interface SQLParameterBinder
A mutable cursor that binds successive values to one prepared statement using one compiled statement. Each cursor has an independent position. Failed operations leave the cursor at its starting position, although JDBC effects from earlier values in a failed sequence may already have occurred. The compiled statement remains immutable and does not retain cursors. Callers are responsible for positions and stale JDBC parameter values when they bind only part of a reused statement.
Since:
4.15
Author:
Eike Stepper
No Implement
This interface is not intended to be implemented by clients.
No Extend
This interface is not intended to be extended by clients.

  • Method Details

    • bind

      SQLParameterBinder bind(Object... values) throws SQLException
      Binds a sequence at the current position and advances after the whole sequence succeeds. The full range is validated before JDBC is changed. A converter or JDBC failure leaves the cursor position unchanged, although earlier JDBC positions in the sequence may already have been bound.
      Parameters:
      values - values in placeholder order; a single null value is passed as (Object)null
      Returns:
      this cursor
      Throws:
      IllegalArgumentException - if the sequence exceeds the remaining parameter range
      NullPointerException - if values is null
      SQLException - if a converter or JDBC setter fails
      Since:
      4.15

    • bindParameter

      <JAVA> SQLParameterBinder bindParameter(JAVA value, SQLValueSetter<? super JAVA> setter) throws SQLException
      Binds one value with a complete JDBC setter and advances after success. The setter replaces the parameter's configured strategy and receives the original value including null.
      Type Parameters:
      JAVA - the application value type
      Parameters:
      value - the application value, possibly null
      setter - the complete JDBC binding operation
      Returns:
      this cursor
      Throws:
      SQLException - if the setter reports a binding failure
      IllegalArgumentException - if the cursor is at the end position
      NullPointerException - if setter is null
      Since:
      4.15

    • bindParameter

      SQLParameterBinder bindParameter(SQLDefaultSetter setter) throws SQLException
      Sets the current parameter to its implementation-defined default and advances after success. The setter does not receive an application value; its default may be domain-specific and need not be the SQL column's DEFAULT expression. This operation is distinct from binding a supplied null value.
      Parameters:
      setter - the complete JDBC default-value binding operation
      Returns:
      this cursor
      Throws:
      SQLException - if the setter reports a binding failure
      IllegalArgumentException - if the cursor is at the end position
      NullPointerException - if setter is null
      Since:
      4.15

    • bindParameter

      <JAVA, JDBC> SQLParameterBinder bindParameter(JAVA value, Function<JAVA,JDBC> converter) throws SQLException
      Converts one value and applies standard JDBC binding, then advances after success. The explicit converter replaces any configured parameter strategy; null input bypasses conversion and uses the parameter's explicit or inferred JDBC NULL type.
      Type Parameters:
      JAVA - the application value type
      JDBC - the converted JDBC value type
      Parameters:
      value - the application value, possibly null
      converter - the conversion applied to non-null values
      Returns:
      this cursor
      Throws:
      SQLException - if JDBC reports a binding failure
      IllegalArgumentException - if the cursor is at the end position
      NullPointerException - if converter is null
      Since:
      4.15

    • getNextIndex

      int getNextIndex()
      Returns the one-based position of the next parameter to bind.
      Returns:
      the next JDBC parameter position

    • from

      SQLParameterBinder from(int index)
      Repositions this cursor to a valid one-based parameter position. The position may be from 1 through parameter count plus one; the final position permits empty binding sequences only.
      Parameters:
      index - the position from 1 through parameter count plus one
      Returns:
      this cursor
      Throws:
      IllegalArgumentException - if the position is outside the valid range
      Since:
      4.15

    • skip

      SQLParameterBinder skip()
      Advances this cursor by one parameter position without binding that position. The same cursor is returned. Skipped positions remain unbound by this call and may retain old values when the prepared statement is reused; use another binding operation to provide their values. Unlike from(int), this operation only moves forward. The final valid position is parameter count plus one; skipping from it is invalid.
      Returns:
      this cursor
      Throws:
      IllegalArgumentException - if advancing would move past the final valid position
      Since:
      4.15

    • skip

      SQLParameterBinder skip(int count)
      Advances this cursor by a nonnegative number of parameter positions without binding or clearing those positions. A zero count is a valid no-op. The same cursor is returned. Positions skipped this way must be bound separately if they need values; a reused prepared statement may retain previous JDBC values. This relative forward movement is distinct from the absolute repositioning, forward or backward, provided by from(int). The destination may be the final valid position, parameter count plus one, but not beyond it.
      Parameters:
      count - the nonnegative number of positions to skip
      Returns:
      this cursor
      Throws:
      IllegalArgumentException - if count is negative, overflows the valid range, or moves past the final valid position
      Since:
      4.15