Package com.glyart.asql.common.database

Class DataTemplate<T extends ASQLContext<?>>

java.lang.Object

com.glyart.asql.common.database.DataTemplate<T>

Type Parameters:

T - The context who created this data template

public class DataTemplate<T extends ASQLContext<?>>
extends Object

Represents the final interaction to a data source.

An instance of the DataTemplate class is linked to the ASQLContext which provided its instance. Knowing that, the DataTemplate class can access and use that ASQLContext members.

This class:

• works asynchronously, without overhead on the main thread
• executes all the CRUD operations on a data source
• handles exceptions
• gives not null CompletableFuture objects that WILL STORE usable future results
• iterates over ResultSets
• deals with static and prepared statements

Methods of this class use various callback interfaces. A reading of those is greatly suggested.

There shouldn't be the need for using the public constructor. Getting an instance of this class by using ASQLContext.getDataTemplate() should be enough.
Since the callback interfaces make DataTemplate's methods parameterizable, there should be no need to subclass DataTemplate.

See Also:

CompletableFuture, BatchPreparedStatementSetter, ParametrizedPreparedStatementSetter, PreparedStatementCallback, PreparedStatementCreator, ResultSetExtractor, RowMapper, StatementCallback

Constructor Summary

Constructors

Constructor	Description
DataTemplate(T context)

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	batchUpdate(String sql, BatchPreparedStatementSetter batchSetter)	Performs multiple update operations using a single SQL statement.
CompletableFuture<Void>	batchUpdate(String sql, List<Object[]> batchArgs)	Performs multiple update operations using a single SQL statement.
<S> CompletableFuture<Void>	batchUpdate(String sql, List<S> batchArgs, ParametrizedPreparedStatementSetter<S> paramsBatchSetter)	Performs multiple update operations using a single SQL statement.
protected void	closeConnection(Connection connection)	Closes a connection using DataSourceHandler's implementation.
protected void	closeResultSet(ResultSet set)	Tries to close a ResultSet object.
protected void	closeStatement(Statement statement)	Tries to close a statement (accepts PreparedStatement objects).
<S> CompletableFuture<S>	execute(PreparedStatementCreator creator, PreparedStatementCallback<S> callback)	Executes a JDBC data access operation, implemented as PreparedStatementCallback callback working on a PreparedStatement.
<S> CompletableFuture<S>	execute(StatementCallback<S> callback)	Executes a JDBC data access operation, implemented as StatementCallback callback, using an active connection.
<S> CompletableFuture<S>	execute(String sql, PreparedStatementCallback<S> callback)	Executes a JDBC data access operation, implemented as PreparedStatementCallback callback working on a PreparedStatement.
protected Connection	getConnection()	Gets a connection using DataSourceHandler's implementation.
protected CompletableFuture<Connection>	getFutureConnection()	Gets a connection using DataSourceHandler's implementation.
<S> CompletableFuture<S>	query(PreparedStatementCreator creator, PreparedStatementSetter setter, ResultSetExtractor<S> extractor)	Executes a query using a PreparedStatement, created by a PreparedStatementCreator and with his values set by a PreparedStatementSetter.
<S> CompletableFuture<S>	query(PreparedStatementCreator creator, ResultSetExtractor<S> extractor)	Executes a query using a PreparedStatement, then reading the ResultSet with a ResultSetExtractor implementation.
<S> CompletableFuture<List<S>>	query(PreparedStatementCreator psc, RowMapper<S> rowMapper)	Executes a query using a PreparedStatement, mapping each row to a result object via a RowMapper implementation.
<S> CompletableFuture<S>	query(String sql, PreparedStatementSetter setter, ResultSetExtractor<S> extractor)	Executes a query using a SQL statement, then reading the ResultSet with a ResultSetExtractor implementation.
<S> CompletableFuture<List<S>>	query(String sql, PreparedStatementSetter pss, RowMapper<S> rowMapper)	Executes a query using a SQL statement and a PreparedStatementSetter implementation that will bind values to the query.
<S> CompletableFuture<S>	query(String sql, ResultSetExtractor<S> extractor)	Executes a query given static SQL statement, then it reads the ResultSet using the ResultSetExtractor implementation.
<S> CompletableFuture<S>	query(String sql, Object[] args, ResultSetExtractor<S> extractor)	Executes a query given a SQL statement: it will be used to create a PreparedStatement.
<S> CompletableFuture<List<S>>	queryForList(String sql, RowMapper<S> rowMapper)	Executes a query given static SQL statement, then it maps each ResultSet row to a result object using the RowMapper implementation.
<S> CompletableFuture<List<S>>	queryForList(String sql, Object[] args, RowMapper<S> rowMapper)	Executes a query given a SQL statement: it will be used to create a PreparedStatement.
<S> CompletableFuture<S>	queryForObject(String sql, RowMapper<S> rowMapper)	Executes a query given static SQL statement, then it maps the first ResultSet row to a result object using the RowMapper implementation.
<S> CompletableFuture<S>	queryForObject(String sql, Object[] args, RowMapper<S> rowMapper)	Executes a query given a SQL statement: it will be used to create a PreparedStatement.
CompletableFuture<Integer>	update(PreparedStatementCreator creator, boolean getGeneratedKeys)	Performs a single update operation (like insert, delete, update) using a PreparedStatementCreator to to provide SQL and any required parameters.
CompletableFuture<Integer>	update(PreparedStatementCreator creator, PreparedStatementSetter setter, boolean getGeneratedKey)	Performs a single update operation (like insert, delete, update) using a PreparedStatementCreator to provide SQL and any required parameters.
CompletableFuture<Integer>	update(String sql, boolean getGeneratedKeys)	Performs a single update operation (like insert, delete, update).
CompletableFuture<Integer>	update(String sql, PreparedStatementSetter setter, boolean getGeneratedKey)	Performs a single update operation (like insert, delete, update).
CompletableFuture<Integer>	update(String sql, Object[] params, boolean getGeneratedKey)	Performs a single update operation (like insert, update or delete statement) via PreparedStatement, binding the given parameters.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataTemplate

public DataTemplate(T context)

Method Detail

execute

public <S> CompletableFuture<S> execute(@NotNull
                                        StatementCallback<S> callback)

Executes a JDBC data access operation, implemented as StatementCallback callback, using an active connection. The callback CAN return a result object (if it exists), for example a single object or a collection of objects.

Type Parameters:

S - the result type

Parameters:

callback - a callback that holds the operation logic

Returns:

a never null CompletableFuture object which holds: an object returned by the callback, or null if it's not available

update

public CompletableFuture<Integer> update(@NotNull
                                         String sql,
                                         boolean getGeneratedKeys)

Performs a single update operation (like insert, delete, update).

Parameters:

sql - static SQL statement to execute

getGeneratedKeys - a boolean value

Returns:

a never null CompletableFuture object which holds: the number of the affected rows. If getGeneratedKeys is true, this method will return the key of the new generated row

query

public <S> CompletableFuture<S> query(@NotNull
                                      String sql,
                                      ResultSetExtractor<S> extractor)

Executes a query given static SQL statement, then it reads the ResultSet using the ResultSetExtractor implementation.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

extractor - a callback that will extract all rows from the ResultSet

Returns:

a never null CompletableFuture object which holds: a result object (if it exists), according to the ResultSetExtractor implementation

queryForList

public <S> CompletableFuture<List<S>> queryForList(@NotNull
                                                   String sql,
                                                   RowMapper<S> rowMapper)

Executes a query given static SQL statement, then it maps each ResultSet row to a result object using the RowMapper implementation.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

rowMapper - a callback that will map one object per ResultSet row

Returns:

a never null CompletableFuture object which holds: a result list containing mapped objects (if they exist)

queryForObject

public <S> CompletableFuture<S> queryForObject(@NotNull
                                               String sql,
                                               RowMapper<S> rowMapper)

Executes a query given static SQL statement, then it maps the first ResultSet row to a result object using the RowMapper implementation.

Note: use of this method is discouraged when the query doesn't supply exactly one row. If more rows are supplied then this method will return only the first one.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

rowMapper - a callback that will map the object per ResultSet row

Returns:

a never null CompletableFuture object which holds: a mapped result object (if it exists)

execute

public <S> CompletableFuture<S> execute(@NotNull
                                        PreparedStatementCreator creator,
                                        @NotNull
                                        PreparedStatementCallback<S> callback)

Executes a JDBC data access operation, implemented as PreparedStatementCallback callback working on a PreparedStatement. The callback CAN return a result object (if it exists), for example a singlet or a collection of objects.

Type Parameters:

S - the result type

Parameters:

creator - a callback that creates a PreparedStatement object given a connection

callback - a callback that holds the operation logic

Returns:

a never null CompletableFuture object which holds: an object returned by the callback, or null if it's not available

execute

public <S> CompletableFuture<S> execute(@NotNull
                                        String sql,
                                        @NotNull
                                        PreparedStatementCallback<S> callback)

Executes a JDBC data access operation, implemented as PreparedStatementCallback callback working on a PreparedStatement. The callback CAN return a result object (if it exists), for example a singlet or a collection of objects.

Type Parameters:

S - the result type

Parameters:

sql - the SQL statement to execute

callback - a callback that holds the operation logic

Returns:

a never null CompletableFuture object which holds: an object returned by the callback, or null if it's not available

update

public CompletableFuture<Integer> update(@NotNull
                                         PreparedStatementCreator creator,
                                         @Nullable
                                         PreparedStatementSetter setter,
                                         boolean getGeneratedKey)

Performs a single update operation (like insert, delete, update) using a PreparedStatementCreator to provide SQL and any required parameters. A PreparedStatementSetter can be passed as helper that sets bind parameters.

Parameters:

creator - a callback that provides the PreparedStatement with bind parameters

setter - a helper that sets bind parameters. If it's null then this will be an update with static SQL

getGeneratedKey - a boolean value

Returns:

a never null CompletableFuture object which holds: the number of the affected rows. If getGeneratedKeys is true, this method will return the key of the new generated row

update

public CompletableFuture<Integer> update(@NotNull
                                         PreparedStatementCreator creator,
                                         boolean getGeneratedKeys)

Performs a single update operation (like insert, delete, update) using a PreparedStatementCreator to to provide SQL and any required parameters.

Parameters:

creator - a callback that provides the PreparedStatement with required parameters

getGeneratedKeys - a boolean values

Returns:

a never null CompletableFuture object which holds: the number of the affected rows. If getGeneratedKeys is true, this method will return the key of the new generated row

update

public CompletableFuture<Integer> update(@NotNull
                                         String sql,
                                         @Nullable
                                         PreparedStatementSetter setter,
                                         boolean getGeneratedKey)

Performs a single update operation (like insert, delete, update). A PreparedStatementSetter can be passed as helper that sets bind parameters.

Parameters:

sql - the SQL containing bind parameters

setter - a helper that sets bind parameters. If it's null then this will be an update with static SQL

getGeneratedKey - a boolean value

Returns:

a never null CompletableFuture object which holds: the number of the affected rows. If getGeneratedKeys is true, this method will return the key of the new generated row

update

public CompletableFuture<Integer> update(@NotNull
                                         String sql,
                                         Object[] params,
                                         boolean getGeneratedKey)

Performs a single update operation (like insert, update or delete statement) via PreparedStatement, binding the given parameters.

Parameters:

sql - the SQL containing bind parameters

params - arguments to be bind to the given SQL

getGeneratedKey - a boolean value

Returns:

a never null CompletableFuture object which holds: the number of the affected rows. If getGeneratedKeys is true, this method will return the key of the new generated row

batchUpdate

public CompletableFuture<Void> batchUpdate(@NotNull
                                           String sql,
                                           @NotNull
                                           BatchPreparedStatementSetter batchSetter)
                                    throws IllegalStateException

Performs multiple update operations using a single SQL statement.

NOTE: this method will be unusable if the driver doesn't support batch updates.

Parameters:

sql - the SQL containing bind parameters. It will be reused because all statements in a batch use the same SQL

batchSetter - a callback that sets parameters on the PreparedStatement created by this method

Returns:

a CompletableFuture object. It can be used for knowing when the batch update is done and if an exception occurred

Throws:

IllegalStateException - if the driver doesn't support batch updates

See Also:

CompletableFuture.exceptionally(Function), CompletableFuture.whenComplete(BiConsumer), BatchPreparedStatementSetter

batchUpdate

public CompletableFuture<Void> batchUpdate(@NotNull
                                           String sql,
                                           @Nullable
                                           List<Object[]> batchArgs)
                                    throws IllegalStateException

Performs multiple update operations using a single SQL statement.

Parameters:

sql - The SQL containing bind parameters. It will be reused because all statements in a batch use the same SQL

batchArgs - A list of object arrays containing the batch arguments

Returns:

A CompletableFuture object. It can be used for knowing when the batch update is done and if an exception occurred

Throws:

IllegalStateException - If the driver doesn't support batch updates

See Also:

CompletableFuture.isCompletedExceptionally()

batchUpdate

public <S> CompletableFuture<Void> batchUpdate(@NotNull
                                               String sql,
                                               @Nullable
                                               List<S> batchArgs,
                                               @NotNull
                                               ParametrizedPreparedStatementSetter<S> paramsBatchSetter)
                                        throws IllegalStateException

Performs multiple update operations using a single SQL statement.

Type Parameters:

S - the parameter type

Parameters:

sql - the SQL containing bind parameters. It will be reused because all statements in a batch use the same SQL

batchArgs - a list of objects containing the batch arguments

paramsBatchSetter - a callback that sets parameters on the PreparedStatement created by this method

Returns:

a CompletableFuture object. It can be used for knowing when the batch update is done and if an exception occurred

Throws:

IllegalStateException - if the driver doesn't support batch updates

See Also:

ParametrizedPreparedStatementSetter

query

public <S> CompletableFuture<S> query(@NotNull
                                      PreparedStatementCreator creator,
                                      @Nullable
                                      PreparedStatementSetter setter,
                                      @NotNull
                                      ResultSetExtractor<S> extractor)

Executes a query using a PreparedStatement, created by a PreparedStatementCreator and with his values set by a PreparedStatementSetter.

Most other query methods use this method, but application code will always work with either a creator or a setter.

Type Parameters:

S - the result type

Parameters:

creator - a callback that creates a PreparedStatement

setter - a callback that sets values on the PreparedStatement. If null, the SQL will be treated as static SQL with no bind parameters

extractor - a callback that will extract results given a ResultSet

Returns:

a never null CompletableFuture object which holds: a result object (if it exists), according to the ResultSetExtractor implementation

See Also:

PreparedStatementSetter

query

public <S> CompletableFuture<S> query(@NotNull
                                      PreparedStatementCreator creator,
                                      @NotNull
                                      ResultSetExtractor<S> extractor)

Executes a query using a PreparedStatement, then reading the ResultSet with a ResultSetExtractor implementation.

Type Parameters:

S - the result type

Parameters:

creator - a callback that creates a PreparedStatement

extractor - a callback that will extract results given a ResultSet

Returns:

a never null CompletableFuture object which holds: a result object (if it exists), according to the ResultSetExtractor implementation

See Also:

PreparedStatementCreator

query

public <S> CompletableFuture<List<S>> query(@NotNull
                                            PreparedStatementCreator psc,
                                            @NotNull
                                            RowMapper<S> rowMapper)

Executes a query using a PreparedStatement, mapping each row to a result object via a RowMapper implementation.

Type Parameters:

S - the result type

Parameters:

psc - a callback that creates a PreparedStatement

rowMapper - a callback that will map one object per ResultSet row

Returns:

a never null CompletableFuture object which holds: a result list containing mapped objects (if they exist)

query

public <S> CompletableFuture<S> query(@NotNull
                                      String sql,
                                      @Nullable
                                      PreparedStatementSetter setter,
                                      @NotNull
                                      ResultSetExtractor<S> extractor)

Executes a query using a SQL statement, then reading the ResultSet with a ResultSetExtractor implementation.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

setter - a callback that sets values on the PreparedStatement. If null, the SQL will be treated as static SQL with no bind parameters

extractor - a callback that will extract results given a ResultSet

Returns:

a never null CompletableFuture object which holds: a result object (if it exists), according to the ResultSetExtractor implementation

query

public <S> CompletableFuture<List<S>> query(@NotNull
                                            String sql,
                                            @Nullable
                                            PreparedStatementSetter pss,
                                            @NotNull
                                            RowMapper<S> rowMapper)

Executes a query using a SQL statement and a PreparedStatementSetter implementation that will bind values to the query. Each row of the ResultSet will be map to a result object via a RowMapper implementation.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

pss - a callback that sets values on the PreparedStatement. If null, the SQL will be treated as static SQL with no bind parameters

rowMapper - a callback that will map one object per ResultSet row

Returns:

a never null CompletableFuture object which holds: a result list containing mapped objects (if they exist)

query

public <S> CompletableFuture<S> query(@NotNull
                                      String sql,
                                      @Nullable
                                      Object[] args,
                                      @NotNull
                                      ResultSetExtractor<S> extractor)

Executes a query given a SQL statement: it will be used to create a PreparedStatement. Then a list of arguments will be bound to the query. The ResultSetExtractor implementation will read the ResultSet.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

args - arguments to bind to the query

extractor - a callback that will extract results given a ResultSet

Returns:

a never null CompletableFuture object which holds: a result object (if it exists), according to the ResultSetExtractor implementation

queryForList

public <S> CompletableFuture<List<S>> queryForList(@NotNull
                                                   String sql,
                                                   @Nullable
                                                   Object[] args,
                                                   @NotNull
                                                   RowMapper<S> rowMapper)

Executes a query given a SQL statement: it will be used to create a PreparedStatement. Then a list of arguments will be bound to the query. Each row of the ResultSet will be map to a result object via a RowMapper implementation.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

args - arguments to bind to the query

rowMapper - a callback that will map one object per ResultSet row

Returns:

a never null CompletableFuture object which holds: a result list containing mapped objects (if they exist)

queryForObject

public <S> CompletableFuture<S> queryForObject(@NotNull
                                               String sql,
                                               Object[] args,
                                               @NotNull
                                               RowMapper<S> rowMapper)

Executes a query given a SQL statement: it will be used to create a PreparedStatement. Then a list of arguments will be bound to the query. Each row of the ResultSet will be map to a result object via a RowMapper implementation.

Note: use of this method is discouraged when the query doesn't supply exactly one row. If more rows are supplied then this method will return only the first one.

Type Parameters:

S - the result type

Parameters:

sql - the query to execute

args - arguments to bind to the query

rowMapper - a callback that will map one object per ResultSet row

Returns:

a never null CompletableFuture object which holds: a mapped result object (if it exist)

getConnection

@Nullable
protected Connection getConnection()

Gets a connection using DataSourceHandler's implementation. This method's failures are fatal and definitely blocks DataTemplate's access operations. If that occurs then an error will be logged.

Returns:

an active connection ready to be used (if it's available)

getFutureConnection

@NotNull
protected CompletableFuture<Connection> getFutureConnection()

Gets a connection using DataSourceHandler's implementation. The connection will be available by accessing the returned CompletableFuture object, with CompletableFuture.whenComplete(BiConsumer) method. Possible exceptions are stored inside that object and they can also be accessed by using whenComplete method.

Returns:

a never null CompletableFuture object which holds: an active connection ready to be used (if it's available)

See Also:

CompletableFuture.whenComplete(BiConsumer), CompletableFuture

closeConnection

protected void closeConnection(@Nullable
                               Connection connection)

Closes a connection using DataSourceHandler's implementation. A failure from this method is not fatal but it will be logged as warning.

Parameters:

connection - the connection to close

closeStatement

protected void closeStatement(@Nullable
                              Statement statement)

Tries to close a statement (accepts PreparedStatement objects). A failure from this method is not fatal but it will be logged as warning.

Parameters:

statement - the statement to close

closeResultSet

protected void closeResultSet(@Nullable
                              ResultSet set)

Tries to close a ResultSet object. A failure from this method is not fatal but it will be logged as warning.

Parameters:

set - the ResultSet to close