Top Description Inners Methods
org.springframework.r2dbc.core

public Interface DatabaseClient

extends ConnectionAccessor
Known Direct Implementers
org.springframework.r2dbc.core.DefaultDatabaseClient
Imports
java.util.Map, java.util.function.BiFunction, .Consumer, .Function, .Predicate, .Supplier, io.r2dbc.spi.ConnectionFactory, .Readable, .Result, .Row, .RowMetadata, .Statement, org.reactivestreams.Publisher, reactor.core.publisher.Flux, .Mono, org.springframework.r2dbc.core.binding.BindMarkersFactory, org.springframework.util.Assert
A non-blocking, reactive client for performing database calls with Reactive Streams back pressure. Provides a higher level, common API over R2DBC client libraries. Propagates org.springframework.dao.DataAccessException variants for errors.

Use the static factory method create(ConnectionFactory) or obtain a builder to create an instance.

Usage example: 

ConnectionFactory factory = …

DatabaseClient client = DatabaseClient.create(factory);
Mono<Actor> actor = client.sql("select first_name, last_name from t_actor")
    .map(row -> new Actor(row.get("first_name", String.class),
         row.get("last_name", String.class)))
    .first();
Authors
Mark Paluch, Juergen Hoeller
Since
5.3

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
DatabaseClient.Builder

A mutable builder for creating a DatabaseClient.

public static interface
DatabaseClient.GenericExecuteSpec

Contract for specifying an SQL call along with options leading to the execution.

Method Summary

Modifier and TypeMethod and Description
public static DatabaseClient.Builder
builder()

Obtain a DatabaseClient builder.

public static DatabaseClient

Returns:

a new DatabaseClient; never null
create(ConnectionFactory
the ConnectionFactory to use for obtaining connections
factory)

Create a DatabaseClient that will use the provided ConnectionFactory.

public ConnectionFactory

Returns:

the connection factory
getConnectionFactory()

Get the ConnectionFactory that this client uses.

public DatabaseClient.GenericExecuteSpec

Returns:

a new GenericExecuteSpec
sql(String
the SQL statement
sql)

Specify a static sql statement to run.

public DatabaseClient.GenericExecuteSpec

Returns:

a new GenericExecuteSpec
sql(Supplier<String>
a supplier for the SQL statement
sqlSupplier)

Specify an SQL supplier that provides SQL to run.

Inherited from org.springframework.r2dbc.core.ConnectionAccessor:
inConnectioninConnectionMany

Method Detail

builderback to summary
public static DatabaseClient.Builder builder()

Obtain a DatabaseClient builder.

createback to summary
public static DatabaseClient create(ConnectionFactory factory)

Create a DatabaseClient that will use the provided ConnectionFactory.

Parameters
factory:ConnectionFactory

the ConnectionFactory to use for obtaining connections

Returns:DatabaseClient

a new DatabaseClient; never null

getConnectionFactoryback to summary
public ConnectionFactory getConnectionFactory()

Get the ConnectionFactory that this client uses.

Returns:ConnectionFactory

the connection factory

sqlback to summary
public DatabaseClient.GenericExecuteSpec sql(String sql)

Specify a static sql statement to run. Contract for specifying an SQL call along with options leading to the execution. The SQL string can contain either native parameter bind markers or named parameters (e.g. :foo, :bar) when NamedParameterExpander is enabled.

Parameters
sql:String

the SQL statement

Returns:DatabaseClient.GenericExecuteSpec

a new GenericExecuteSpec

See Also
NamedParameterExpander, DatabaseClient.Builder#namedParameters(boolean)
sqlback to summary
public DatabaseClient.GenericExecuteSpec sql(Supplier<String> sqlSupplier)

Specify an SQL supplier that provides SQL to run. Contract for specifying an SQL call along with options leading to the execution. The SQL string can contain either native parameter bind markers or named parameters (e.g. :foo, :bar) when NamedParameterExpander is enabled.

Accepts PreparedOperation as SQL and binding Supplier.

DatabaseClient implementations should defer the resolution of the SQL string as much as possible, ideally up to the point where a Subscription happens. This is the case for the default implementation.

Parameters
sqlSupplier:Supplier<String>

a supplier for the SQL statement

Returns:DatabaseClient.GenericExecuteSpec

a new GenericExecuteSpec

See Also
NamedParameterExpander, DatabaseClient.Builder#namedParameters(boolean), PreparedOperation
org.springframework.r2dbc.core back to summary

public Interface DatabaseClient.Builder

Known Direct Implementers
org.springframework.r2dbc.core.DefaultDatabaseClientBuilder
A mutable builder for creating a DatabaseClient.

Method Summary

Modifier and TypeMethod and Description
public DatabaseClient.Builder
apply(Consumer<DatabaseClient.Builder> builderConsumer)

Apply a Consumer to configure this builder.

public DatabaseClient.Builder
bindMarkers(BindMarkersFactory bindMarkers)

Configure the BindMarkers to be used.

public DatabaseClient
build()

Build the DatabaseClient instance.

public DatabaseClient.Builder
connectionFactory(ConnectionFactory factory)

Configure the R2DBC connector.

public DatabaseClient.Builder
executeFunction(ExecuteFunction executeFunction)

Configure an ExecuteFunction to execute Statement objects.

public DatabaseClient.Builder
namedParameters(boolean
true to use named parameter expansion; false to disable named parameter expansion
enabled)

Configure whether to use named parameter expansion.

Method Detail

applyback to summary
public DatabaseClient.Builder apply(Consumer<DatabaseClient.Builder> builderConsumer)

Apply a Consumer to configure this builder.

bindMarkersback to summary
public DatabaseClient.Builder bindMarkers(BindMarkersFactory bindMarkers)

Configure the BindMarkers to be used.

buildback to summary
public DatabaseClient build()

Build the DatabaseClient instance.

connectionFactoryback to summary
public DatabaseClient.Builder connectionFactory(ConnectionFactory factory)

Configure the R2DBC connector.

executeFunctionback to summary
public DatabaseClient.Builder executeFunction(ExecuteFunction executeFunction)

Configure an ExecuteFunction to execute Statement objects.

See Also
Statement#execute()
namedParametersback to summary
public DatabaseClient.Builder namedParameters(boolean enabled)

Configure whether to use named parameter expansion.

Defaults to true.

Parameters
enabled:boolean

true to use named parameter expansion; false to disable named parameter expansion

See Also
NamedParameterExpander
org.springframework.r2dbc.core back to summary

public Interface DatabaseClient.GenericExecuteSpec

Known Direct Implementers
org.springframework.r2dbc.core.DefaultDatabaseClient.DefaultGenericExecuteSpec
Contract for specifying an SQL call along with options leading to the execution.

Method Summary

Modifier and TypeMethod and Description
public DatabaseClient.GenericExecuteSpec
bind(int
zero based index to bind the parameter to
index, Object
either a scalar value or a io.r2dbc.spi.Parameter
value)

Bind a non-null value to a parameter identified by its index.

public DatabaseClient.GenericExecuteSpec
bind(String
the name of the parameter
name, Object
either a scalar value or a io.r2dbc.spi.Parameter
value)

Bind a non-null value to a parameter identified by its name.

public DatabaseClient.GenericExecuteSpec
bindNull(int
zero based index to bind the parameter to
index, Class<?>
the parameter type
type)

Bind a null value to a parameter identified by its index.

public DatabaseClient.GenericExecuteSpec
bindNull(String
the name of the parameter
name, Class<?>
the parameter type
type)

Bind a null value to a parameter identified by its name.

public DatabaseClient.GenericExecuteSpec
bindProperties(Object
the source object (a JavaBean or record)
source)

Bind the bean properties or record components from the given source object, registering each as a named parameter.

public DatabaseClient.GenericExecuteSpec
bindValues(Map<String, ?>
the source map of parameters, with keys as names and each value either a scalar value or a io.r2dbc.spi.Parameter
source)

Bind the parameter values from the given source map, registering each as a parameter with the map key as name.

public FetchSpec<Map<String, Object>>
fetch()

Perform the SQL call and retrieve the result by entering the execution stage.

public default DatabaseClient.GenericExecuteSpec
filter(Function<? super Statement, ? extends Statement>
the filter to be added to the chain
filterFunction)

Add the given filter to the end of the filter chain.

public DatabaseClient.GenericExecuteSpec
filter(StatementFilterFunction
the filter to be added to the chain
filter)

Add the given filter to the end of the filter chain.

public <
the result type
R> Flux<R>

Returns:

a Flux that emits mapped elements
flatMap(Function<Result, Publisher<R>>
a function that maps from Result into a result publisher
mappingFunction)

Perform the SQL call and apply function to the Result.

public <
the result type
R> RowsFetchSpec<R>

Returns:

a RowsFetchSpec for configuration what to fetch
map(Function<? super Readable, R>
a function that maps from Readable to the result type
mappingFunction)

Configure a result mapping function and enter the execution stage.

public <
the result type
R> RowsFetchSpec<R>

Returns:

a RowsFetchSpec for configuration what to fetch
map(BiFunction<Row, RowMetadata, R>
a function that maps from Row and RowMetadata to the result type
mappingFunction)

Configure a result mapping function and enter the execution stage.

public <
the result type
R> RowsFetchSpec<R>

Returns:

a RowsFetchSpec for configuration what to fetch
mapProperties(Class<R>
the target class (a JavaBean or record) with properties to map to (bean properties or record components)
mappedClass)

Configure a row mapper for the given mapped class and enter the execution stage.

public <
the result type
R> RowsFetchSpec<R>

Returns:

a RowsFetchSpec for configuration what to fetch
mapValue(Class<R>
the target class (a database-supported value class)
mappedClass)

Configure a mapping for values in the first column and enter the execution stage.

public Mono<Void>

Returns:

a Mono ignoring its payload (actively dropping)
then()

Perform the SQL call and return a Mono that completes without result on statement completion.

Method Detail

bindback to summary
public DatabaseClient.GenericExecuteSpec bind(int index, Object value)

Bind a non-null value to a parameter identified by its index.

Parameters
index:int

zero based index to bind the parameter to

value:Object

either a scalar value or a io.r2dbc.spi.Parameter

bindback to summary
public DatabaseClient.GenericExecuteSpec bind(String name, Object value)

Bind a non-null value to a parameter identified by its name.

Parameters
name:String

the name of the parameter

value:Object

either a scalar value or a io.r2dbc.spi.Parameter

bindNullback to summary
public DatabaseClient.GenericExecuteSpec bindNull(int index, Class<?> type)

Bind a null value to a parameter identified by its index.

Parameters
index:int

zero based index to bind the parameter to

type:Class<?>

the parameter type

bindNullback to summary
public DatabaseClient.GenericExecuteSpec bindNull(String name, Class<?> type)

Bind a null value to a parameter identified by its name.

Parameters
name:String

the name of the parameter

type:Class<?>

the parameter type

bindPropertiesback to summary
public DatabaseClient.GenericExecuteSpec bindProperties(Object source)

Bind the bean properties or record components from the given source object, registering each as a named parameter.

Parameters
source:Object

the source object (a JavaBean or record)

Since
6.1
See Also
mapProperties
bindValuesback to summary
public DatabaseClient.GenericExecuteSpec bindValues(Map<String, ?> source)

Bind the parameter values from the given source map, registering each as a parameter with the map key as name.

Parameters
source:Map<String, ?>

the source map of parameters, with keys as names and each value either a scalar value or a io.r2dbc.spi.Parameter

Since
6.1
See Also
bindProperties
fetchback to summary
public FetchSpec<Map<String, Object>> fetch()

Perform the SQL call and retrieve the result by entering the execution stage.

filterback to summary
public default DatabaseClient.GenericExecuteSpec filter(Function<? super Statement, ? extends Statement> filterFunction)

Add the given filter to the end of the filter chain.

Filter functions are typically used to invoke methods on the Statement before it is executed. For example: 

DatabaseClient client = …;
client.sql("SELECT book_id FROM book").filter(statement -> statement.fetchSize(100))
Parameters
filterFunction:Function<? super Statement, ? extends Statement>

the filter to be added to the chain

filterback to summary
public DatabaseClient.GenericExecuteSpec filter(StatementFilterFunction filter)

Add the given filter to the end of the filter chain.

Filter functions are typically used to invoke methods on the Statement before it is executed. For example: 

DatabaseClient client = …;
client.sql("SELECT book_id FROM book").filter((statement, next) -> next.execute(statement.fetchSize(100)))
Parameters
filter:StatementFilterFunction

the filter to be added to the chain

flatMapback to summary
public <R> Flux<R> flatMap(Function<Result, Publisher<R>> mappingFunction)

Perform the SQL call and apply function to the Result.

Parameters
<R>
the result type
mappingFunction:Function<Result, Publisher<R>>

a function that maps from Result into a result publisher

Returns:Flux<R>

a Flux that emits mapped elements

Since
6.0
See Also
Result#filter(Predicate), Result#flatMap(Function)
mapback to summary
public <R> RowsFetchSpec<R> map(Function<? super Readable, R> mappingFunction)

Configure a result mapping function and enter the execution stage.

Parameters
<R>
the result type
mappingFunction:Function<? super Readable, R>

a function that maps from Readable to the result type

Returns:RowsFetchSpec<R>

a RowsFetchSpec for configuration what to fetch

Since
6.0
mapback to summary
public <R> RowsFetchSpec<R> map(BiFunction<Row, RowMetadata, R> mappingFunction)

Configure a result mapping function and enter the execution stage.

Parameters
<R>
the result type
mappingFunction:BiFunction<Row, RowMetadata, R>

a function that maps from Row and RowMetadata to the result type

Returns:RowsFetchSpec<R>

a RowsFetchSpec for configuration what to fetch

mapPropertiesback to summary
public <R> RowsFetchSpec<R> mapProperties(Class<R> mappedClass)

Configure a row mapper for the given mapped class and enter the execution stage.

Parameters
<R>
the result type
mappedClass:Class<R>

the target class (a JavaBean or record) with properties to map to (bean properties or record components)

Returns:RowsFetchSpec<R>

a RowsFetchSpec for configuration what to fetch

Since
6.1
See Also
DataClassRowMapper
mapValueback to summary
public <R> RowsFetchSpec<R> mapValue(Class<R> mappedClass)

Configure a mapping for values in the first column and enter the execution stage.

Parameters
<R>
the result type
mappedClass:Class<R>

the target class (a database-supported value class)

Returns:RowsFetchSpec<R>

a RowsFetchSpec for configuration what to fetch

Since
6.1
See Also
Readable#get(int, Class)
thenback to summary
public Mono<Void> then()

Perform the SQL call and return a Mono that completes without result on statement completion.

Returns:Mono<Void>

a Mono ignoring its payload (actively dropping)