io.r2dbc.spi

Interface Statement

public interface Statement

A statement that can be executed multiple times in a prepared and optimized way. Bound parameters can be either scalar values (using type inference for the database parameter type) or Parameter objects.

See Also:

Result, Row, Blob, Clob, Parameter

Method Summary

Modifier and Type	Method and Description
Statement	add() Save the current binding and create a new one to indicate the statement should be executed again with new bindings provided through subsequent calls to bind and bindNull.
Statement	bind(int index, Object value) Bind a non-null value to an indexed parameter.
Statement	bind(String name, Object value) Bind a non-null to a named parameter.
Statement	bindNull(int index, Class<?> type) Bind a null value to an indexed parameter.
Statement	bindNull(String name, Class<?> type) Bind a null value to a named parameter.
Publisher<? extends Result>	execute() Executes one or more SQL statements and returns the Results.
default Statement	fetchSize(int rows) Configures Statement to retrieve a fixed number of rows when fetching results from a query instead deriving fetch size from back pressure.
default Statement	returnGeneratedValues(String... columns) Configures Statement to return the generated values from any rows created by this Statement in the Result returned from execute().

Method Detail

add

Statement add()

Save the current binding and create a new one to indicate the statement should be executed again with new bindings provided through subsequent calls to bind and bindNull. For example:

 Statement statement = connection.createStatement("INSERT INTO books (author, publisher) VALUES ($1, $2)");
 statement.bind(0, "John Doe").bind(1, "Happy Books LLC").add();
 statement.bind(0, "Jane Doe").bind(1, "Scary Books Inc");
 statement.execute();
 

Returns:

this Statement

Throws:

IllegalStateException - if the statement is parametrized and not all parameter values are provided

bind

Statement bind(int index,
               Object value)

Bind a non-null value to an indexed parameter. Indexes are zero-based.

Parameters:

index - the index to bind to

value - the value to bind

Returns:

this Statement

Throws:

IllegalArgumentException - if value is null

IndexOutOfBoundsException - if the parameter index is out of range

bind

Statement bind(String name,
               Object value)

Bind a non-null to a named parameter.

Parameters:

name - the name of identifier to bind to

value - the value to bind

Returns:

this Statement

Throws:

IllegalArgumentException - if name or value is null

NoSuchElementException - if name is not a known name to bind

bindNull

Statement bindNull(int index,
                   Class<?> type)

Bind a null value to an indexed parameter. Indexes are zero-based.

Parameters:

index - the index to bind to

type - the type of null value

Returns:

this Statement

Throws:

IllegalArgumentException - if type is null

IndexOutOfBoundsException - if the parameter index is out of range

bindNull

Statement bindNull(String name,
                   Class<?> type)

Bind a null value to a named parameter.

Parameters:

name - the name of identifier to bind to

type - the type of null value

Returns:

this Statement

Throws:

IllegalArgumentException - if name or type is null

NoSuchElementException - if name is not a known name to bind

execute

Publisher<? extends Result> execute()

Executes one or more SQL statements and returns the Results. Result objects must be fully consumed to ensure full execution of the Statement. This statement is executed additionally for each binding saved through add().

Returns:

the Results, returned by each statement

Throws:

IllegalStateException - if the statement is parametrized and not all parameter values are provided

returnGeneratedValues

default Statement returnGeneratedValues(String... columns)

Configures Statement to return the generated values from any rows created by this Statement in the Result returned from execute(). If no columns are specified, implementations are free to choose which columns will be returned. If called multiple times, only the columns requested in the final invocation will be returned.

The default implementation of this method is a no-op.

Parameters:

columns - the names of the columns to return

Returns:

this Statement

Throws:

IllegalArgumentException - if columns, or any item in columns is null

fetchSize

default Statement fetchSize(int rows)

Configures Statement to retrieve a fixed number of rows when fetching results from a query instead deriving fetch size from back pressure. If called multiple times, only the fetch size configured in the final invocation will be applied. If the value specified is zero, then the hint is ignored.

The default implementation of this method is a no op and the default value is zero.

Parameters:

rows - the number of rows to fetch

Returns:

this Statement