Top Description Inners Methods
org.springframework.jdbc.core.simple

public Interface JdbcClient

Known Direct Implementers
org.springframework.jdbc.core.simple.DefaultJdbcClient
Imports
java.util.Collection, .LinkedHashSet, .List, .Map, .Optional, .Set, java.util.stream.Stream, javax.sql.DataSource, org.springframework.dao.support.DataAccessUtils, org.springframework.jdbc.core.JdbcOperations, .ResultSetExtractor, .RowCallbackHandler, .RowMapper, org.springframework.jdbc.core.namedparam.NamedParameterJdbcOperations, .SqlParameterSource, org.springframework.jdbc.support.KeyHolder, org.springframework.jdbc.support.rowset.SqlRowSet, org.springframework.lang.Nullable
A fluent JdbcClient with common JDBC query and update operations, supporting JDBC-style positional as well as Spring-style named parameters with a convenient unified facade for JDBC PreparedStatement execution.

An example for retrieving a query result as a java.util.Optional: 

Optional<Integer> value = client.sql("SELECT AGE FROM CUSTOMER WHERE ID = :id")
    .param("id", 3)
    .query(Integer.class)
    .optional();

Delegates to org.springframework.jdbc.core.JdbcTemplate and org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate. For complex JDBC operations — for example, batch inserts and stored procedure calls — you may use those lower-level template classes directly, or alternatively SimpleJdbcInsert and SimpleJdbcCall.

Authors
Juergen Hoeller, Sam Brannen
Since
6.1
See Also
ResultSetExtractor, RowCallbackHandler, RowMapper, JdbcOperations, NamedParameterJdbcOperations, org.springframework.jdbc.core.JdbcTemplate, org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
JdbcClient.MappedQuerySpec<
the RowMapper-declared result type
T>

A specification for RowMapper-mapped queries.

public static interface
JdbcClient.ResultQuerySpec

A specification for simple result queries.

public static interface
JdbcClient.StatementSpec

A statement specification for parameter bindings and query/update execution.

Method Summary

Modifier and TypeMethod and Description
public static JdbcClient
create(DataSource
the DataSource to obtain connections from
dataSource)

Create a JdbcClient for the given DataSource.

public static JdbcClient
create(JdbcOperations
the delegate to perform operations on
jdbcTemplate)

Create a JdbcClient for the given JdbcOperations delegate, typically an org.springframework.jdbc.core.JdbcTemplate.

public static JdbcClient
create(NamedParameterJdbcOperations
the delegate to perform operations on
jdbcTemplate)

Create a JdbcClient for the given NamedParameterJdbcOperations delegate, typically an org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate.

public JdbcClient.StatementSpec

Returns:

a chained statement specification
sql(String
the SQL query or update statement as a String
sql)

The starting point for any JDBC operation: a custom SQL String.

Method Detail

createback to summary
public static JdbcClient create(DataSource dataSource)

Create a JdbcClient for the given DataSource.

Parameters
dataSource:DataSource

the DataSource to obtain connections from

createback to summary
public static JdbcClient create(JdbcOperations jdbcTemplate)

Create a JdbcClient for the given JdbcOperations delegate, typically an org.springframework.jdbc.core.JdbcTemplate.

Use this factory method to reuse existing JdbcTemplate configuration, including its DataSource.

Parameters
jdbcTemplate:JdbcOperations

the delegate to perform operations on

createback to summary
public static JdbcClient create(NamedParameterJdbcOperations jdbcTemplate)

Create a JdbcClient for the given NamedParameterJdbcOperations delegate, typically an org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate.

Use this factory method to reuse existing NamedParameterJdbcTemplate configuration, including its underlying JdbcTemplate and DataSource.

Parameters
jdbcTemplate:NamedParameterJdbcOperations

the delegate to perform operations on

sqlback to summary
public JdbcClient.StatementSpec sql(String sql)

The starting point for any JDBC operation: a custom SQL String.

Parameters
sql:String

the SQL query or update statement as a String

Returns:JdbcClient.StatementSpec

a chained statement specification

org.springframework.jdbc.core.simple back to summary

public Interface JdbcClient.MappedQuerySpec<T>

Known Direct Implementers
org.springframework.jdbc.core.simple.DefaultJdbcClient.DefaultStatementSpec.IndexedParamMappedQuerySpec, org.springframework.jdbc.core.simple.DefaultJdbcClient.DefaultStatementSpec.NamedParamMappedQuerySpec
Type Parameters
<T>
the RowMapper-declared result type
A specification for RowMapper-mapped queries.

Method Summary

Modifier and TypeMethod and Description
public List<T>

Returns:

the result as a detached List, containing mapped objects
list()

Retrieve the result as a pre-resolved list of mapped objects, retaining the order from the original database result.

public default Optional<T>

Returns:

an Optional handle with a single result object or none
optional()

Retrieve a single result, if available, as an Optional handle.

public default Set<T>

Returns:

the result as a detached Set, containing mapped objects
set()

Retrieve the result as an order-preserving set of mapped objects.

public default T

Returns:

the single result object (never null)
single()

Retrieve a single result as a required object instance.

public Stream<T>

Returns:

the result Stream, containing mapped objects, needing to be closed once fully processed (e.g. through a try-with-resources clause)
stream()

Retrieve the result as a lazily resolved stream of mapped objects, retaining the order from the original database result.

Method Detail

listback to summary
public List<T> list()

Retrieve the result as a pre-resolved list of mapped objects, retaining the order from the original database result.

Returns:List<T>

the result as a detached List, containing mapped objects

optionalback to summary
public default Optional<T> optional()

Retrieve a single result, if available, as an Optional handle.

Returns:Optional<T>

an Optional handle with a single result object or none

See Also
list(), DataAccessUtils#optionalResult(Collection)
setback to summary
public default Set<T> set()

Retrieve the result as an order-preserving set of mapped objects.

Returns:Set<T>

the result as a detached Set, containing mapped objects

See Also
list(), LinkedHashSet
singleback to summary
public default T single()

Retrieve a single result as a required object instance.

Returns:T

the single result object (never null)

See Also
list(), DataAccessUtils#requiredSingleResult(Collection)
streamback to summary
public Stream<T> stream()

Retrieve the result as a lazily resolved stream of mapped objects, retaining the order from the original database result.

Returns:Stream<T>

the result Stream, containing mapped objects, needing to be closed once fully processed (e.g. through a try-with-resources clause)

org.springframework.jdbc.core.simple back to summary

public Interface JdbcClient.ResultQuerySpec

Known Direct Implementers
org.springframework.jdbc.core.simple.DefaultJdbcClient.DefaultStatementSpec.IndexedParamResultQuerySpec, org.springframework.jdbc.core.simple.DefaultJdbcClient.DefaultStatementSpec.NamedParamResultQuerySpec
A specification for simple result queries.

Method Summary

Modifier and TypeMethod and Description
public List<Map<String, Object>>

Returns:

a (potentially empty) list of rows, with each result row represented as a map of case-insensitive column names to column values
listOfRows()

Retrieve the result as a list of rows, retaining the order from the original database result.

public SqlRowSet

Returns:

a detached row set representation of the original database result
rowSet()

Retrieve the result as a row set.

public List<Object>

Returns:

a (potentially empty) list of rows, with each row represented as its single column value
singleColumn()

Retrieve a single column result, retaining the order from the original database result.

public Map<String, Object>

Returns:

the result row represented as a map of case-insensitive column names to column values
singleRow()

Retrieve a single row result.

public default Object

Returns:

the single row represented as its single column value
singleValue()

Retrieve a single value result.

Method Detail

listOfRowsback to summary
public List<Map<String, Object>> listOfRows()

Retrieve the result as a list of rows, retaining the order from the original database result.

Returns:List<Map<String, Object>>

a (potentially empty) list of rows, with each result row represented as a map of case-insensitive column names to column values

rowSetback to summary
public SqlRowSet rowSet()

Retrieve the result as a row set.

Returns:SqlRowSet

a detached row set representation of the original database result

singleColumnback to summary
public List<Object> singleColumn()

Retrieve a single column result, retaining the order from the original database result.

Returns:List<Object>

a (potentially empty) list of rows, with each row represented as its single column value

singleRowback to summary
public Map<String, Object> singleRow()

Retrieve a single row result.

Returns:Map<String, Object>

the result row represented as a map of case-insensitive column names to column values

singleValueback to summary
public default Object singleValue()

Retrieve a single value result.

Returns:Object

the single row represented as its single column value

See Also
DataAccessUtils#requiredSingleResult(Collection)
org.springframework.jdbc.core.simple back to summary

public Interface JdbcClient.StatementSpec

Known Direct Implementers
org.springframework.jdbc.core.simple.DefaultJdbcClient.DefaultStatementSpec
A statement specification for parameter bindings and query/update execution.

Method Summary

Modifier and TypeMethod and Description
public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
param(Object
the parameter value to bind
value)

Bind a positional JDBC statement parameter for "?" placeholder resolution by implicit order of parameter value registration.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
param(int
the JDBC-style index (starting with 1)
jdbcIndex, Object
the parameter value to bind
value)

Bind a positional JDBC statement parameter for "?" placeholder resolution by explicit JDBC statement parameter index.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
param(int
the JDBC-style index (starting with 1)
jdbcIndex, Object
the parameter value to bind
value, int
the associated SQL type (see java.sql.Types)
sqlType)

Bind a positional JDBC statement parameter for "?" placeholder resolution by explicit JDBC statement parameter index.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
param(String
the parameter name
name, Object
the parameter value to bind
value)

Bind a named statement parameter for ":x" placeholder resolution, with each "x" name matching a ":x" placeholder in the SQL statement.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
param(String
the parameter name
name, Object
the parameter value to bind
value, int
the associated SQL type (see java.sql.Types)
sqlType)

Bind a named statement parameter for ":x" placeholder resolution, with each "x" name matching a ":x" placeholder in the SQL statement.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
params(Object...
the parameter values to bind
values)

Bind a var-args list of positional parameters for "?" placeholder resolution.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
params(List<?>
the parameter values to bind
values)

Bind a list of positional parameters for "?" placeholder resolution.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
params(Map<String, ?>
a map of names and parameter values to bind
paramMap)

Bind named statement parameters for ":x" placeholder resolution.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
paramSource(Object
a custom parameter object (e.g. a JavaBean, record class, or field holder) with named properties serving as statement parameters
namedParamObject)

Bind named statement parameters for ":x" placeholder resolution.

public JdbcClient.StatementSpec

Returns:

this statement specification (for chaining)
paramSource(SqlParameterSource
a custom SqlParameterSource instance
namedParamSource)

Bind named statement parameters for ":x" placeholder resolution.

public JdbcClient.ResultQuerySpec

Returns:

the result query specification
query()

Proceed towards execution of a query, with several result options available in the returned query specification.

public <T> JdbcClient.MappedQuerySpec<T>

Returns:

the mapped query specification
query(Class<T>
the target class to apply a RowMapper for (either a simple value type for a single column mapping or a JavaBean / record class / field holder for a multi-column mapping)
mappedClass)

Proceed towards execution of a mapped query, with several options available in the returned query specification.

public <T> JdbcClient.MappedQuerySpec<T>

Returns:

the mapped query specification
query(RowMapper<T>
the callback for mapping each row in the ResultSet
rowMapper)

Proceed towards execution of a mapped query, with several options available in the returned query specification.

public void
query(RowCallbackHandler
a callback for processing each row in the ResultSet
rch)

Execute a query with the provided SQL statement, processing each row with the given callback.

public <T> T

Returns:

the value returned by the ResultSetExtractor
query(ResultSetExtractor<T>
a callback for processing the entire ResultSet
rse)

Execute a query with the provided SQL statement, returning a result object for the entire ResultSet.

public int

Returns:

the number of rows affected
update()

Execute the provided SQL statement as an update.

public int

Returns:

the number of rows affected
update(KeyHolder
a KeyHolder that will hold the generated keys (typically a org.springframework.jdbc.support.GeneratedKeyHolder)
generatedKeyHolder)

Execute the provided SQL statement as an update.

public int

Returns:

the number of rows affected
update(KeyHolder
a KeyHolder that will hold the generated keys (typically a org.springframework.jdbc.support.GeneratedKeyHolder)
generatedKeyHolder, String...
names of the columns that will have keys generated for them
keyColumnNames)

Execute the provided SQL statement as an update.

Method Detail

paramback to summary
public JdbcClient.StatementSpec param(Object value)

Bind a positional JDBC statement parameter for "?" placeholder resolution by implicit order of parameter value registration.

This is primarily intended for statements with a single parameter or very few parameters, registering each parameter value in the order of the parameter's occurrence in the SQL statement.

Parameters
value:Object

the parameter value to bind

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
java.sql.PreparedStatement#setObject(int, Object)
paramback to summary
public JdbcClient.StatementSpec param(int jdbcIndex, Object value)

Bind a positional JDBC statement parameter for "?" placeholder resolution by explicit JDBC statement parameter index.

Parameters
jdbcIndex:int

the JDBC-style index (starting with 1)

value:Object

the parameter value to bind

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
java.sql.PreparedStatement#setObject(int, Object)
paramback to summary
public JdbcClient.StatementSpec param(int jdbcIndex, Object value, int sqlType)

Bind a positional JDBC statement parameter for "?" placeholder resolution by explicit JDBC statement parameter index.

Parameters
jdbcIndex:int

the JDBC-style index (starting with 1)

value:Object

the parameter value to bind

sqlType:int

the associated SQL type (see java.sql.Types)

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
java.sql.PreparedStatement#setObject(int, Object, int)
paramback to summary
public JdbcClient.StatementSpec param(String name, Object value)

Bind a named statement parameter for ":x" placeholder resolution, with each "x" name matching a ":x" placeholder in the SQL statement.

Parameters
name:String

the parameter name

value:Object

the parameter value to bind

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
org.springframework.jdbc.core.namedparam.MapSqlParameterSource#addValue(String, Object)
paramback to summary
public JdbcClient.StatementSpec param(String name, Object value, int sqlType)

Bind a named statement parameter for ":x" placeholder resolution, with each "x" name matching a ":x" placeholder in the SQL statement.

Parameters
name:String

the parameter name

value:Object

the parameter value to bind

sqlType:int

the associated SQL type (see java.sql.Types)

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
org.springframework.jdbc.core.namedparam.MapSqlParameterSource#addValue(String, Object, int)
paramsback to summary
public JdbcClient.StatementSpec params(Object... values)

Bind a var-args list of positional parameters for "?" placeholder resolution.

The given list will be added to existing positional parameters, if any. Each element from the complete list will be bound as a JDBC positional parameter with a corresponding JDBC index (i.e. list index + 1).

Parameters
values:Object[]

the parameter values to bind

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
param(Object), params(List)
paramsback to summary
public JdbcClient.StatementSpec params(List<?> values)

Bind a list of positional parameters for "?" placeholder resolution.

The given list will be added to existing positional parameters, if any. Each element from the complete list will be bound as a JDBC positional parameter with a corresponding JDBC index (i.e. list index + 1).

Parameters
values:List<?>

the parameter values to bind

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
param(Object)
paramsback to summary
public JdbcClient.StatementSpec params(Map<String, ?> paramMap)

Bind named statement parameters for ":x" placeholder resolution.

The given map will be merged into existing named parameters, if any.

Parameters
paramMap:Map<String, ?>

a map of names and parameter values to bind

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
param(String, Object)
paramSourceback to summary
public JdbcClient.StatementSpec paramSource(Object namedParamObject)

Bind named statement parameters for ":x" placeholder resolution.

The given parameter object will define all named parameters based on its JavaBean properties, record components, or raw fields. A Map instance can be provided as a complete parameter source as well.

Parameters
namedParamObject:Object

a custom parameter object (e.g. a JavaBean, record class, or field holder) with named properties serving as statement parameters

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
paramSource(SqlParameterSource), org.springframework.jdbc.core.namedparam.MapSqlParameterSource, org.springframework.jdbc.core.namedparam.SimplePropertySqlParameterSource
paramSourceback to summary
public JdbcClient.StatementSpec paramSource(SqlParameterSource namedParamSource)

Bind named statement parameters for ":x" placeholder resolution.

The given parameter source will define all named parameters, possibly associating specific SQL types with each value.

Parameters
namedParamSource:SqlParameterSource

a custom SqlParameterSource instance

Returns:JdbcClient.StatementSpec

this statement specification (for chaining)

See Also
org.springframework.jdbc.core.namedparam.AbstractSqlParameterSource#registerSqlType
queryback to summary
public JdbcClient.ResultQuerySpec query()

Proceed towards execution of a query, with several result options available in the returned query specification.

Returns:JdbcClient.ResultQuerySpec

the result query specification

See Also
java.sql.PreparedStatement#executeQuery()
queryback to summary
public <T> JdbcClient.MappedQuerySpec<T> query(Class<T> mappedClass)

Proceed towards execution of a mapped query, with several options available in the returned query specification.

Parameters
mappedClass:Class<T>

the target class to apply a RowMapper for (either a simple value type for a single column mapping or a JavaBean / record class / field holder for a multi-column mapping)

Returns:JdbcClient.MappedQuerySpec<T>

the mapped query specification

See Also
query(RowMapper), org.springframework.jdbc.core.SingleColumnRowMapper, org.springframework.jdbc.core.SimplePropertyRowMapper
queryback to summary
public <T> JdbcClient.MappedQuerySpec<T> query(RowMapper<T> rowMapper)

Proceed towards execution of a mapped query, with several options available in the returned query specification.

Parameters
rowMapper:RowMapper<T>

the callback for mapping each row in the ResultSet

Returns:JdbcClient.MappedQuerySpec<T>

the mapped query specification

See Also
java.sql.PreparedStatement#executeQuery()
queryback to summary
public void query(RowCallbackHandler rch)

Execute a query with the provided SQL statement, processing each row with the given callback.

Parameters
rch:RowCallbackHandler

a callback for processing each row in the ResultSet

See Also
java.sql.PreparedStatement#executeQuery()
queryback to summary
public <T> T query(ResultSetExtractor<T> rse)

Execute a query with the provided SQL statement, returning a result object for the entire ResultSet.

Parameters
rse:ResultSetExtractor<T>

a callback for processing the entire ResultSet

Returns:T

the value returned by the ResultSetExtractor

See Also
java.sql.PreparedStatement#executeQuery()
updateback to summary
public int update()

Execute the provided SQL statement as an update.

Returns:int

the number of rows affected

See Also
java.sql.PreparedStatement#executeUpdate()
updateback to summary
public int update(KeyHolder generatedKeyHolder)

Execute the provided SQL statement as an update.

This method requires support for generated keys in the JDBC driver.

Parameters
generatedKeyHolder:KeyHolder

a KeyHolder that will hold the generated keys (typically a org.springframework.jdbc.support.GeneratedKeyHolder)

Returns:int

the number of rows affected

See Also
java.sql.PreparedStatement#executeUpdate(), java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
updateback to summary
public int update(KeyHolder generatedKeyHolder, String... keyColumnNames)

Execute the provided SQL statement as an update.

This method requires support for generated keys in the JDBC driver.

Parameters
generatedKeyHolder:KeyHolder

a KeyHolder that will hold the generated keys (typically a org.springframework.jdbc.support.GeneratedKeyHolder)

keyColumnNames:String[]

names of the columns that will have keys generated for them

Returns:int

the number of rows affected

See Also
java.sql.PreparedStatement#executeUpdate(), java.sql.DatabaseMetaData#supportsGetGeneratedKeys()