Class SqlStatement<This extends SqlStatement<This>>

java.lang.Object
org.jdbi.v3.core.statement.SqlStatement<This>
All Implemented Interfaces:
Closeable, AutoCloseable, Configurable<This>
Direct Known Subclasses:
Call, PreparedBatch, Query, Script, Update

public abstract class SqlStatement<This extends SqlStatement<This>> extends Object
This class provides the common functions between Query and Update. It defines most of the argument binding functions used by its subclasses.
  • Method Details

    • setQueryTimeout

      public This setQueryTimeout(int seconds)
      Set the query timeout, in seconds, on the prepared statement.
      Parameters:
      seconds - number of seconds before timing out
      Returns:
      the same Query instance
    • cleanupHandleCommit

      public This cleanupHandleCommit()
      Transfer ownership of the handle to the statement: when the statement is closed, commit the handle's transaction (if one exists) and close the handle.
      Returns:
      this
    • cleanupHandleRollback

      public This cleanupHandleRollback()
      When the statement is closed, roll it back then close the owning Handle.
      Returns:
      this
    • bind

      public This bind(int position, Argument argument)
      Used if you need to have some exotic parameter bound.
      Parameters:
      position - position to bindBinaryStream this argument, starting at 0
      argument - exotic argument factory
      Returns:
      the same Query instance
    • bind

      public This bind(String name, Argument argument)
      Used if you need to have some exotic parameter bound.
      Parameters:
      name - name to bindBinaryStream this argument
      argument - exotic argument factory
      Returns:
      the same Query instance
    • bindBean

      public This bindBean(Object bean)
      Binds named parameters from JavaBean properties on the argument.
      Parameters:
      bean - source of named parameter values to use as arguments
      Returns:
      modified statement
    • bindBean

      public This bindBean(String prefix, Object bean)
      Binds named parameters from JavaBean properties on the bean argument, with the given prefix. Example: the prefix foo applied to a bean property bar will be bound as foo.bar.
      Parameters:
      prefix - a prefix to apply to all property names.
      bean - source of named parameter values to use as arguments. Can be null, in this case, nothing is bound.
      Returns:
      modified statement
    • bindPojo

      @Beta public This bindPojo(Object pojo)
      Binds named parameters from object properties on the argument. The type must have been registered with pojo type mapping functionality first, usually by a plugin or configuration.
      Parameters:
      pojo - source of named parameter values to use as arguments
      Returns:
      modified statement
      See Also:
    • bindPojo

      @Beta public This bindPojo(String prefix, Object pojo)
      Binds named parameters from object properties on the bean argument, with the given prefix. The type must have been registered with pojo type mapping functionality first, usually by a plugin or configuration.
      Parameters:
      prefix - a prefix to apply to all property names.
      pojo - source of named parameter values to use as arguments
      Returns:
      modified statement
      See Also:
    • bindPojo

      @Beta public This bindPojo(Object pojo, Type type)
      Binds named parameters from object properties on the argument. The type must have been registered with pojo type mapping functionality first, usually by a plugin or configuration.
      Parameters:
      pojo - source of named parameter values to use as arguments
      type - the static, possibly generic type of the pojo
      Returns:
      modified statement
      See Also:
    • bindPojo

      @Beta public This bindPojo(String prefix, Object pojo, Type type)
      Binds named parameters from object properties on the bean argument, with the given prefix. The type must have been registered with pojo type mapping functionality first, usually by a plugin or configuration.
      Parameters:
      prefix - a prefix to apply to all property names.
      pojo - source of named parameter values to use as arguments
      type - the static, possibly generic type of the pojo
      Returns:
      modified statement
      See Also:
    • bindPojo

      @Beta public This bindPojo(Object pojo, GenericType<?> type)
      Binds named parameters from object properties on the argument. The type must have been registered with pojo type mapping functionality first, usually by a plugin or configuration.
      Parameters:
      pojo - source of named parameter values to use as arguments
      type - the static generic type of the pojo
      Returns:
      modified statement
      See Also:
    • bindPojo

      @Beta public This bindPojo(String prefix, Object pojo, GenericType<?> type)
      Binds named parameters from object properties on the bean argument, with the given prefix. The type must have been registered with pojo type mapping functionality first, usually by a plugin or configuration.
      Parameters:
      prefix - a prefix to apply to all property names.
      pojo - source of named parameter values to use as arguments
      type - the static generic type of the pojo
      Returns:
      modified statement
      See Also:
    • bindFields

      public This bindFields(Object object)
      Binds public fields of the specified object as arguments for the query.
      Parameters:
      object - source of the public fields to bind.
      Returns:
      modified statement
    • bindFields

      public This bindFields(String prefix, Object object)
      Binds public fields of the specified object as arguments for the query.
      Parameters:
      prefix - a prefix to apply to all field names.
      object - source of the public fields to bind. If the object is null, nothing is bound.
      Returns:
      modified statement
    • bindMethods

      public This bindMethods(Object object)
      Binds methods with no parameters on the argument.
      Parameters:
      object - source of methods to use as arguments
      Returns:
      modified statement
    • bindMethods

      public This bindMethods(String prefix, Object object)
      Binds methods with no parameters on the argument, with the given prefix.
      Parameters:
      prefix - a prefix to apply to all property names.
      object - source of methods to use as arguments. If the object is null, nothing is bound.
      Returns:
      modified statement
    • bindMap

      public This bindMap(Map<String,?> map)
      Binds named parameters from a map of String to Object instances
      Parameters:
      map - map where keys are matched to named parameters in order to bind arguments. Can be null, in which case the binding has no effect.
      Returns:
      modified statement
    • bindNamedArgumentFinder

      public This bindNamedArgumentFinder(NamedArgumentFinder namedArgumentFinder)
      Binds a new NamedArgumentFinder.
      Parameters:
      namedArgumentFinder - A NamedArgumentFinder to bind. Can be null.
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Character value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Character value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, String value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, String value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bindNVarchar

      public final This bindNVarchar(int position, String value)
      Bind a String argument positionally, as NVARCHAR type.
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bindNVarchar

      public final This bindNVarchar(String name, String value)
      Bind a String argument by name, as NVARCHAR type.
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, int value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Integer value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, int value)
      Bind an argument by name
      Parameters:
      name - name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Integer value)
      Bind an argument by name
      Parameters:
      name - name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, char value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, char value)
      Bind an argument by name
      Parameters:
      name - name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bindASCIIStream

      public final This bindASCIIStream(int position, InputStream value, int length)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      length - how long is the stream being bound?
      Returns:
      the same Query instance
    • bindASCIIStream

      public final This bindASCIIStream(String name, InputStream value, int length)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      length - bytes to read from value
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, BigDecimal value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, BigDecimal value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bindBinaryStream

      public final This bindBinaryStream(int position, InputStream value, int length)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      length - the number of bytes in the stream.
      Returns:
      the same Query instance
    • bindBinaryStream

      public final This bindBinaryStream(String name, InputStream value, int length)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      length - bytes to read from value
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Blob value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Blob value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, boolean value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Boolean value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, boolean value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Boolean value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, byte value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Byte value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, byte value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Byte value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, byte[] value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, byte[] value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Reader value, int length)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      length - number of characters to read
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Reader value, int length)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      length - number of characters to read
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Clob value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Clob value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Date value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Date value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Date value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Date value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, double value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Double value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, double value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Double value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, float value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Float value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, float value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Float value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, long value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Long value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, long value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Long value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Short value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, short value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, short value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Short value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Object value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Object value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Time value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Time value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, Timestamp value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, Timestamp value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, URL value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, URL value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, URI value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, URI value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(int position, UUID value)
      Bind an argument positionally
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      Returns:
      the same Query instance
    • bind

      public final This bind(String name, UUID value)
      Bind an argument by name
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      Returns:
      the same Query instance
    • bindByType

      public final This bindByType(int position, Object value, Type argumentType)
      Bind an argument dynamically by the type passed in.
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      argumentType - type for value argument
      Returns:
      the same Query instance
    • bindByType

      public final This bindByType(int position, Object value, GenericType<?> argumentType)
      Bind an argument dynamically by the generic type passed in.
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      argumentType - type token for value argument
      Returns:
      the same Query instance
    • bindByType

      public final This bindByType(int position, Object value, QualifiedType<?> argumentType)
      Bind an argument dynamically by the qualified type passed in.
      Parameters:
      position - position to bind the parameter at, starting at 0
      value - to bind
      argumentType - type token for value argument
      Returns:
      the same Query instance
    • bindByType

      public final This bindByType(String name, Object value, Type argumentType)
      Bind an argument dynamically by the type passed in.
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      argumentType - type for value argument
      Returns:
      the same Query instance
    • bindByType

      public final This bindByType(String name, Object value, GenericType<?> argumentType)
      Bind an argument dynamically by the generic type passed in.
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      argumentType - type token for value argument
      Returns:
      the same Query instance
    • bindByType

      public final This bindByType(String name, Object value, QualifiedType<?> argumentType)
      Bind an argument dynamically by the type passed in.
      Parameters:
      name - token name to bind the parameter to
      value - to bind
      argumentType - type for value argument
      Returns:
      the same Query instance
    • bindArray

      @SafeVarargs public final <T> This bindArray(String name, T... array)
      Bind a Java array as a SQL array. Usually you can just bind(int, Object) an array, but this method allows varargs.
      Type Parameters:
      T - the array element type
      Parameters:
      name - the name of the parameter to bind
      array - the array to bind
      Returns:
      this Query
    • bindArray

      @SafeVarargs public final <T> This bindArray(int pos, T... array)
      Bind a Java array as a SQL array. Usually you can just bind(int, Object) an array, but this method allows varargs.
      Type Parameters:
      T - the array element type
      Parameters:
      pos - the position of the parameter to bind
      array - the array to bind
      Returns:
      this Query
    • bindArray

      public final This bindArray(String name, Type elementType, Object... array)
      Bind a Java array as a SQL array, casting each element to a new type.
      Parameters:
      name - the name of the parameter to bind
      elementType - the array element type
      array - the array to bind
      Returns:
      this Query
    • bindArray

      public final This bindArray(int pos, Type elementType, Object... array)
      Bind a Java array as a SQL array, casting each element to a new type.
      Parameters:
      pos - the position of the parameter to bind
      elementType - the array element type
      array - the array to bind
      Returns:
      this Query
    • bindArray

      public final This bindArray(String name, Type elementType, Iterable<?> iterable)
      Bind an Iterable as a SQL array.
      Parameters:
      name - the name of the parameter to bind
      elementType - the element type of the Iterable
      iterable - the iterable to bind as an array
      Returns:
      this Query
    • bindArray

      public final This bindArray(int pos, Type elementType, Iterable<?> iterable)
      Bind an Iterable as a SQL array.
      Parameters:
      pos - the position of the parameter to bind
      elementType - the element type of the Iterable
      iterable - the iterable to bind as an array
      Returns:
      this Query
    • bindArray

      public final This bindArray(String name, Type elementType, Iterator<?> iterator)
      Bind an Iterator as a SQL array.
      Parameters:
      name - the name of the parameter to bind
      elementType - the element type of the Iterable
      iterator - the iterator to bind as an array
      Returns:
      this Query
    • bindArray

      public final This bindArray(int pos, Type elementType, Iterator<?> iterator)
      Bind an Iterator as a SQL array.
      Parameters:
      pos - the position of the parameter to bind
      elementType - the element type of the Iterator
      iterator - the Iterator to bind as an array
      Returns:
      this Query
    • bindNull

      public final This bindNull(String name, int sqlType)
      Bind NULL to be set for a given argument.
      Parameters:
      name - Named parameter to bind to
      sqlType - The sqlType must be set and is a value from java.sql.Types
      Returns:
      the same statement instance
    • bindNull

      public final This bindNull(int position, int sqlType)
      Bind NULL to be set for a given argument.
      Parameters:
      position - position to bind NULL to, starting at 0
      sqlType - The sqlType must be set and is a value from java.sql.Types
      Returns:
      the same statement instance
    • bindBySqlType

      public final This bindBySqlType(String name, Object value, int sqlType)
      Bind a value using a specific type from java.sql.Types via PreparedStatement#setObject(int, Object, int)
      Parameters:
      name - Named parameter to bind at
      value - Value to bind
      sqlType - The sqlType from java.sql.Types
      Returns:
      self
    • bindBySqlType

      public final This bindBySqlType(int position, Object value, int sqlType)
      Bind a value using a specific type from java.sql.Types via PreparedStatement#setObject(int, Object, int)
      Parameters:
      position - position to bind NULL to, starting at 0
      value - Value to bind
      sqlType - The sqlType from java.sql.Types
      Returns:
      self
    • bindList

      public final This bindList(String key, Object... values)
      Parameters:
      key - attribute name
      values - vararg values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the vararg array is empty.
      See Also:
    • bindList

      public final This bindList(BiConsumer<SqlStatement,String> onEmpty, String key, Object... values)
      Parameters:
      onEmpty - handler for null/empty vararg array
      key - attribute name
      values - vararg values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the vararg array is empty.
      See Also:
    • bindList

      public final This bindList(String key, Iterable<?> values)
      Parameters:
      key - attribute name
      values - iterable values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the iterable is empty.
      See Also:
    • bindList

      public final This bindList(BiConsumer<SqlStatement,String> onEmpty, String key, Iterable<?> values)
      Parameters:
      onEmpty - handler for null/empty list
      key - attribute name
      values - iterable values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the iterable is empty.
      See Also:
    • bindList

      public final This bindList(String key, Iterator<?> values)
      Parameters:
      key - attribute name
      values - iterator of values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the iterator is empty.
      See Also:
    • bindList

      public final This bindList(BiConsumer<SqlStatement,String> onEmpty, String key, Iterator<?> values)
      Parameters:
      onEmpty - handler for null/empty list
      key - attribute name
      values - iterator of values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the iterator is empty.
      See Also:
    • bindList

      public final This bindList(BiConsumer<SqlStatement,String> onEmpty, String key, List<?> values)
      Bind a parameter for each value in the given list, and defines an attribute as the comma-separated list of parameter references (using colon prefix).

      Examples:

       List<String> columnNames = Arrays.asList("id", "name", "created_on");
       List<Object> values = Arrays.asList(1, "Alice", LocalDate.now());
       handle.createUpdate("insert into things (<columnNames>) values (<values>)")
           .defineList("columnNames", columnNames)
           .bindList("values", values)
           .execute();
      
       List<Integer> ids = Arrays.asList(1, 2, 3);
       List<Thing> things = handle.createQuery("select * from things where id in (<ids>)")
           .bindList("ids", ids)
           .mapTo(Contact.class)
           .list();
       
      Note that using this method modifies the SQL statement by using a defined attribute. This is problematic when using Handle.prepareBatch(String) or the PreparedBatch SQL operation as those evaluate the SQL statement only once. When binding lists of different size, the number of placeholders will not match the number of elements in the list which will lead to errors.
      Parameters:
      onEmpty - handler for null/empty list
      key - attribute name
      values - list of values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the list is empty.
      See Also:
    • bindBeanList

      public final This bindBeanList(String key, List<?> values, List<String> propertyNames)
      Bind a parameter for each value in the given list * number of property names, and defines an attribute as the comma-separated list of parameter references (using colon prefix). Used to create query similar to: select * from things where (id, foo) in ((1,'abc'),(2,'def'),(3,'ghi'))

      Examples:

      
       List<ThingKey> thingKeys = ...
       List<Thing> things = handle.createQuery("select * from things where (id, foo) in (<thingKeys>)")
           .bindBeanList("thingKeys", thingKeys, Arrays.asList("id", "foo"))
           .mapTo(Contact.class)
           .list();
       
      Parameters:
      key - attribute name
      values - list of values that will be comma-spliced into the defined attribute value.
      propertyNames - list of properties that will be invoked on the values.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the list of values or properties is empty.
      UnableToCreateStatementException - If a property can't be found on an value or we can't find a Argument for it.
      See Also:
    • bindMethodsList

      public final This bindMethodsList(String key, Iterable<?> values, List<String> methodNames)
      For each value given, create a tuple by invoking each given method in order, and bind the tuple into a VALUES (...) format insert clause.
      Parameters:
      key - attribute name
      values - list of values that will be comma-spliced into the defined attribute value
      methodNames - list of methods that will be invoked on the values
      Returns:
      this
      Throws:
      IllegalArgumentException - if the list of values or properties is empty.
      UnableToCreateStatementException - if the method cannot be found
      See Also:
    • defineList

      public final This defineList(String key, Object... values)
      Define an attribute as the comma-separated String from the elements of the values argument.

      Examples:

       handle.createUpdate("insert into things (<columnNames>) values (<values>)")
           .defineList("columnNames", "id", "name", "created_on")
           .bindList("values", 1, "Alice", LocalDate.now())
           .execute();
      
       List<Thing> things = handle.createQuery("select <columnNames> from things")
           .bindList("columnNames", "id", "name", "created_on")
           .mapTo(Contact.class)
           .list();
       
      Parameters:
      key - attribute name
      values - vararg values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the vararg array is empty, or contains any null elements.
    • defineList

      public final This defineList(String key, List<?> values)
      Define an attribute as the comma-separated String from the elements of the values argument.

      Examples:

       List<String> columnNames = Arrays.asList("id", "name", "created_on");
       List<Object> values = Arrays.asList(1, "Alice", LocalDate.now());
       handle.createUpdate("insert into things (<columnNames>) values (<values>)")
           .defineList("columnNames", columnNames)
           .bindList("values", 1, values)
           .execute();
      
       List<String> columnNames = Arrays.asList("id", "name", "created_on");
       List<Thing> things = handle.createQuery("select <columnNames> from things")
           .bindList("columnNames", columnNames)
           .mapTo(Contact.class)
           .list();
       
      Parameters:
      key - attribute name
      values - list of values that will be comma-spliced into the defined attribute value.
      Returns:
      this
      Throws:
      IllegalArgumentException - if the list is empty, or contains any null elements.
    • defineNamedBindings

      @Beta public This defineNamedBindings()
      Define all bound arguments that don't already have a definition with a boolean indicating their presence. Useful to easily template optional properties of pojos or beans like <if(property)>property = :property<endif>.
      Returns:
      this
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • getHandle

      public final Handle getHandle()
    • getConfig

      public ConfigRegistry getConfig()
      Description copied from interface: Configurable
      Returns the configuration registry associated with this object.
      Specified by:
      getConfig in interface Configurable<This>
      Returns:
      the configuration registry associated with this object.
    • getContext

      public final StatementContext getContext()
      Returns the statement context associated with this statement.
      Returns:
      the statement context associated with this statement.
    • attachToHandleForCleanup

      @Beta public final This attachToHandleForCleanup()
      Registers with the handle for cleaning when the handle is closed.
      There are some situations where Statements need to be cleaned up to avoid resource leaks. This method registers the current Statement it with the Handle. If the statement or the context are cleaned by themselves, it will automatically unregister, so in normal operations, resources should not pool for cleanup with the Handle.
      Since:
      3.35.0
    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
    • equals

      public final boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object