io.vertx.sqlclient

Interface Pool

All Superinterfaces:

SqlClient

All Known Subinterfaces:

DB2Pool, JDBCPool, MSSQLPool, MySQLPool, PgPool

public interface Pool
extends SqlClient

A connection pool which reuses a number of SQL connections.

Author:

Julien Viet

Method Summary

Modifier and Type	Method and Description
void	close(Handler<AsyncResult<Void>> handler) Close the pool and release the associated resources.
Pool	connectHandler(Handler<SqlConnection> handler) Set an handler called when the pool has established a connection to the database.
Pool	connectionProvider(java.util.function.Function<Context,Future<SqlConnection>> provider) Replace the default pool connection provider, the new provider returns a future connection for a given Context.
Future<SqlConnection>	getConnection() Like getConnection(Handler) but returns a Future of the asynchronous result
void	getConnection(Handler<AsyncResult<SqlConnection>> handler) Get a connection from the pool.
static Pool	pool(SqlConnectOptions connectOptions) Like pool(SqlConnectOptions, PoolOptions) with default options.
static Pool	pool(SqlConnectOptions database, PoolOptions options) Like pool(Vertx, SqlConnectOptions, PoolOptions) with a Vert.x instance created automatically.
static Pool	pool(Vertx vertx, SqlConnectOptions database, PoolOptions options) Create a connection pool to the database with the given options.
PreparedQuery<RowSet<Row>>	preparedQuery(String sql) Create a prepared query, one of the PreparedQuery.execute(io.vertx.sqlclient.Tuple, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) or PreparedQuery.executeBatch(java.util.List<io.vertx.sqlclient.Tuple>, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) methods must be called to execute the query.
Query<RowSet<Row>>	query(String sql) Create a query, the Query.execute(io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) method must be called to execute the query.
int	size()
default <T> Future<T>	withConnection(java.util.function.Function<SqlConnection,Future<T>> function) Like withTransaction(Function, Handler) but returns a Future of the asynchronous result
default <T> void	withConnection(java.util.function.Function<SqlConnection,Future<T>> function, Handler<AsyncResult<T>> handler) Get a connection from the pool and execute the given function.
default <T> Future<T>	withTransaction(java.util.function.Function<SqlConnection,Future<T>> function) Like withTransaction(Function, Handler) but returns a Future of the asynchronous result
default <T> void	withTransaction(java.util.function.Function<SqlConnection,Future<T>> function, Handler<AsyncResult<T>> handler) Execute the given function within a transaction.

Methods inherited from interface io.vertx.sqlclient.SqlClient

close, preparedQuery

Method Detail

pool

static Pool pool(SqlConnectOptions connectOptions)

Like pool(SqlConnectOptions, PoolOptions) with default options.

pool

static Pool pool(SqlConnectOptions database,
                 PoolOptions options)

Like pool(Vertx, SqlConnectOptions, PoolOptions) with a Vert.x instance created automatically.

pool

static Pool pool(Vertx vertx,
                 SqlConnectOptions database,
                 PoolOptions options)

Create a connection pool to the database with the given options.

A Driver will be selected among the drivers found on the classpath returning true when Driver.acceptsOptions(SqlConnectOptions) applied to the first options of the list.

Parameters:

vertx - the Vertx instance to be used with the connection pool

database - the options used to create the connection pool, such as database hostname

options - the options for creating the pool

Returns:

the connection pool

Throws:

ServiceConfigurationError - if no compatible drivers are found, or if multiple compatible drivers are found

getConnection

void getConnection(Handler<AsyncResult<SqlConnection>> handler)

Get a connection from the pool.

Parameters:

handler - the handler that will get the connection result

getConnection

Future<SqlConnection> getConnection()

Like getConnection(Handler) but returns a Future of the asynchronous result

query

Query<RowSet<Row>> query(String sql)

Create a query, the Query.execute(io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) method must be called to execute the query. A connection is borrowed from the connection pool when the query is executed and then immediately returned to the pool after it completes.

Specified by:

query in interface SqlClient

Returns:

the query

preparedQuery

PreparedQuery<RowSet<Row>> preparedQuery(String sql)

Create a prepared query, one of the PreparedQuery.execute(io.vertx.sqlclient.Tuple, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) or PreparedQuery.executeBatch(java.util.List<io.vertx.sqlclient.Tuple>, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) methods must be called to execute the query. A connection is borrowed from the connection pool when the query is executed and then immediately returned to the pool after it completes.

Specified by:

preparedQuery in interface SqlClient

Returns:

the prepared query

withTransaction

default <T> void withTransaction(java.util.function.Function<SqlConnection,Future<T>> function,
                                 Handler<AsyncResult<T>> handler)

Execute the given function within a transaction.

The function is passed a client executing all operations within a transaction. When the future returned by the function

• succeeds the transaction commits
• fails the transaction rollbacks

The handler is given a success result when the function returns a succeeded futures and the transaction commits. Otherwise it is given a failure result.

Parameters:

function - the code to execute

handler - the result handler

withTransaction

default <T> Future<T> withTransaction(java.util.function.Function<SqlConnection,Future<T>> function)

Like withTransaction(Function, Handler) but returns a Future of the asynchronous result

withConnection

default <T> void withConnection(java.util.function.Function<SqlConnection,Future<T>> function,
                                Handler<AsyncResult<T>> handler)

Get a connection from the pool and execute the given function.

When the future returned by the function completes, the connection is returned to the pool.

The handler is given a success result when the function returns a succeeded futures. Otherwise it is given a failure result.

Parameters:

function - the code to execute

handler - the result handler

withConnection

default <T> Future<T> withConnection(java.util.function.Function<SqlConnection,Future<T>> function)

Like withTransaction(Function, Handler) but returns a Future of the asynchronous result

close

void close(Handler<AsyncResult<Void>> handler)

Close the pool and release the associated resources.

Specified by:

close in interface SqlClient

Parameters:

handler - the completion handler

connectHandler

Pool connectHandler(Handler<SqlConnection> handler)

Set an handler called when the pool has established a connection to the database.

This handler allows interactions with the database before the connection is added to the pool.

When the handler has finished, it must call SqlClient.close() to release the connection to the pool.

Parameters:

handler - the handler

Returns:

a reference to this, so the API can be used fluently

connectionProvider

Pool connectionProvider(java.util.function.Function<Context,Future<SqlConnection>> provider)

Replace the default pool connection provider, the new provider returns a future connection for a given Context.

A ConnectionFactory can be used as connection provider.

Parameters:

provider - the new connection provider

Returns:

a reference to this, so the API can be used fluently

size

int size()

Returns:

the current pool size approximation