Package org.jdbi.v3.core

Class Jdbi

java.lang.Object

org.jdbi.v3.core.Jdbi

All Implemented Interfaces:

Configurable<Jdbi>

public class Jdbi
extends Object
implements Configurable<Jdbi>

Main entry point; configurable wrapper around a JDBC DataSource. Use it to obtain Handle instances and provide configuration for all handles obtained from it.

Method Summary

Modifier and Type	Method	Description
static Jdbi	create(String url)	Creates a new Jdbi instance from a database URL.
static Jdbi	create(String url, String username, String password)	Creates a new Jdbi instance from a database URL.
static Jdbi	create(String url, Properties properties)	Creates a new Jdbi instance from a database URL.
static Jdbi	create(Connection connection)	Creates a new Jdbi object from a Connection.
static Jdbi	create(DataSource dataSource)	Creates a new Jdbi object from a DataSource.
static Jdbi	create(ConnectionFactory connectionFactory)	Factory used to allow for obtaining a Connection in a customized manner.
ConfigRegistry	getConfig()	Returns the configuration registry associated with this object.
HandleCallbackDecorator	getHandleCallbackDecorator()	Returns the HandleCallbackDecorator.
final HandleScope	getHandleScope()	Returns the internal HandleScope object.
StatementBuilderFactory	getStatementBuilderFactory()	Returns the current StatementBuilderFactory.
TransactionHandler	getTransactionHandler()	Returns the TransactionHandler.
Jdbi	installPlugin(JdbiPlugin plugin)	Install a given JdbiPlugin instance that will configure any provided Handle instances.
Jdbi	installPlugins()	Use the ServiceLoader API to detect and install plugins automagically.
<R, X extends Exception> R	inTransaction(HandleCallback<R,X> callback)	A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<R, X extends Exception> R	inTransaction(TransactionIsolationLevel level, HandleCallback<R,X> callback)	A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<E> E	onDemand(Class<E> extensionType)	Creates an extension instance that uses the current Jdbi instance for database operations.
Handle	open()	Obtain a Handle to the data source wrapped by this Jdbi instance.
static Handle	open(String url)	Obtain a handle with just a JDBC URL
static Handle	open(String url, String username, String password)	Obtain a handle with just a JDBC URL
static Handle	open(String url, Properties props)	Obtain a handle with just a JDBC URL
static Handle	open(Connection connection)	Create a Handle wrapping a particular JDBC Connection
static Handle	open(DataSource dataSource)	Convenience method used to obtain a handle from a specific data source
static Handle	open(ConnectionFactory connectionFactory)	Convenience method used to obtain a handle from a ConnectionFactory.
Jdbi	setHandleCallbackDecorator(HandleCallbackDecorator handleCallbackDecorator)	Specify the HandleCallbackDecorator instance to use.
final void	setHandleScope(HandleScope handleScope)	Set the HandleScope object.
Jdbi	setStatementBuilderFactory(StatementBuilderFactory factory)	Allows customization of how prepared statements are created.
Jdbi	setTransactionHandler(TransactionHandler handler)	Specify the TransactionHandler instance to use.
<E, X extends Exception> void	useExtension(Class<E> extensionType, ExtensionConsumer<E,X> callback)	A convenience method which opens an extension of the given type, and yields it to a callback.
<X extends Exception> void	useHandle(HandleConsumer<X> consumer)	A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<X extends Exception> void	useTransaction(HandleConsumer<X> callback)	A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<X extends Exception> void	useTransaction(TransactionIsolationLevel level, HandleConsumer<X> callback)	A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<R, E, X extends Exception> R	withExtension(Class<E> extensionType, ExtensionCallback<R,E,X> callback)	A convenience method which opens an extension of the given type, yields it to a callback, and returns the result of the callback.
<R, X extends Exception> R	withHandle(HandleCallback<R,X> callback)	A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.jdbi.v3.core.config.Configurable

addCustomizer, configure, define, getConfig, registerArgument, registerArgument, registerArrayType, registerArrayType, registerArrayType, registerArrayType, registerCodecFactory, registerCollector, registerCollector, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerExtension, registerRowMapper, registerRowMapper, registerRowMapper, registerRowMapper, setMapKeyColumn, setMapValueColumn, setSqlArrayArgumentStrategy, setSqlLogger, setSqlParser, setTemplateEngine, setTimingCollector

Method Details

create

public static Jdbi create(Connection connection)

Creates a new Jdbi object from a Connection.

Parameters:

connection - A Connection object.

Returns:

A Jdbi instance that uses a single database connection.

create

public static Jdbi create(DataSource dataSource)

Creates a new Jdbi object from a DataSource.

Parameters:

dataSource - the data source.

Returns:

a Jdbi which uses the given data source as a connection factory.

create

public static Jdbi create(ConnectionFactory connectionFactory)

Factory used to allow for obtaining a Connection in a customized manner.

The ConnectionFactory.openConnection() method will be invoked to obtain a connection instance whenever a Handle is opened.

Parameters:

connectionFactory - Provides JDBC connections to Handle instances

Returns:

a Jdbi which uses the given connection factory.

create

public static Jdbi create(String url)

Creates a new Jdbi instance from a database URL.

Parameters:

url - A JDBC URL for connections.

Returns:

a Jdbi which usesDriverManager as a connection factory.

create

public static Jdbi create(String url,
 Properties properties)

Creates a new Jdbi instance from a database URL.

Parameters:

url - JDBC URL for connections

properties - Properties to pass to DriverManager.getConnection(url, props) for each new handle

Returns:

a Jdbi which uses DriverManager as a connection factory.

create

public static Jdbi create(String url,
 String username,
 String password)

Creates a new Jdbi instance from a database URL.

Parameters:

url - JDBC URL for connections

username - User name for connection authentication

password - Password for connection authentication

Returns:

a Jdbi which uses DriverManager as a connection factory.

open

public static Handle open(DataSource dataSource)

Convenience method used to obtain a handle from a specific data source

Parameters:

dataSource - the JDBC data source.

Returns:

Handle using a Connection obtained from the provided DataSource

open

public static Handle open(ConnectionFactory connectionFactory)

Convenience method used to obtain a handle from a ConnectionFactory.

Parameters:

connectionFactory - the connection factory

Returns:

Handle using a Connection obtained from the provided connection factory

open

public static Handle open(Connection connection)

Create a Handle wrapping a particular JDBC Connection

Parameters:

connection - the JDBC connection

Returns:

Handle bound to connection

open

public static Handle open(String url)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

Returns:

newly opened Handle

open

public static Handle open(String url,
 String username,
 String password)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

username - JDBC username for authentication

password - JDBC password for authentication

Returns:

newly opened Handle

open

public static Handle open(String url,
 Properties props)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

props - JDBC properties

Returns:

newly opened Handle

installPlugins

public Jdbi installPlugins()

Use the ServiceLoader API to detect and install plugins automagically. Some people consider this feature dangerous; some consider it essential -- use at your own risk.

Returns:

this

installPlugin

public Jdbi installPlugin(JdbiPlugin plugin)

Install a given JdbiPlugin instance that will configure any provided Handle instances.

Parameters:

plugin - the plugin to install

Returns:

this

setStatementBuilderFactory

public Jdbi setStatementBuilderFactory(StatementBuilderFactory factory)

Allows customization of how prepared statements are created. When a Handle is created against this Jdbi instance the factory will be used to create a StatementBuilder for that specific handle. When the handle is closed, the StatementBuilder's close method will be invoked.

Parameters:

factory - the new statement builder factory.

Returns:

this

getStatementBuilderFactory

public StatementBuilderFactory getStatementBuilderFactory()

Returns the current StatementBuilderFactory.

Returns:

the current StatementBuilderFactory

getConfig

public ConfigRegistry getConfig()

Description copied from interface: Configurable

Returns the configuration registry associated with this object.

Specified by:

getConfig in interface Configurable<Jdbi>

Returns:

the configuration registry associated with this object.

setTransactionHandler

public Jdbi setTransactionHandler(TransactionHandler handler)

Specify the TransactionHandler instance to use. This allows overriding transaction semantics, or mapping into different transaction management systems.

The default version uses local transactions on the database Connection instances obtained.

Parameters:

handler - The TransactionHandler to use for all Handle instances obtained from this Jdbi

Returns:

this

getTransactionHandler

public TransactionHandler getTransactionHandler()

Returns the TransactionHandler.

Returns:

the TransactionHandler

setHandleCallbackDecorator

@Alpha
public Jdbi setHandleCallbackDecorator(HandleCallbackDecorator handleCallbackDecorator)

Specify the HandleCallbackDecorator instance to use. This allows overriding callbacks for useHandle(org.jdbi.v3.core.HandleConsumer<X>), withHandle(org.jdbi.v3.core.HandleCallback<R, X>), useTransaction(HandleConsumer) and inTransaction(HandleCallback). The default version is a pass-through that returns the callback unchanged.

Parameters:

handleCallbackDecorator - The HandleCallbackDecorator to use for all useHandle(org.jdbi.v3.core.HandleConsumer<X>), withHandle(org.jdbi.v3.core.HandleCallback<R, X>), useTransaction(HandleConsumer) and inTransaction(HandleCallback) from this Jdbi. Must not be null

Returns:

this

getHandleCallbackDecorator

@Alpha
public HandleCallbackDecorator getHandleCallbackDecorator()

Returns the HandleCallbackDecorator.

Returns:

the HandleCallbackDecorator

getHandleScope

public final HandleScope getHandleScope()

Returns the internal HandleScope object. The Jdbi instance uses this to provide handles in a given scope. The default scope is per-thread, so every thread manages its own handle.
This is an internal method and not part of the public API!

Returns:

A HandleScope object

setHandleScope

@Alpha
public final void setHandleScope(HandleScope handleScope)

Set the HandleScope object. The Jdbi instance uses this to provide handles in a given scope.

Parameters:

handleScope - A HandleScope object. Must not be null!

open

public Handle open()

Obtain a Handle to the data source wrapped by this Jdbi instance. You own this expensive resource and are required to close it or risk leaks. Using a try-with-resources block is recommended.

Returns:

an open Handle instance

See Also:

• useHandle(HandleConsumer)
• withHandle(HandleCallback)

withHandle

public <R,
X extends Exception> R withHandle(HandleCallback<R,X> callback)
                                      throws X

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.

Type Parameters:

R - type returned by the callback

X - exception type thrown by the callback, if any.

Parameters:

callback - A callback which will receive an open Handle

Returns:

the value returned by callback

Throws:

X - any exception thrown by the callback

useHandle

public <X extends Exception> void useHandle(HandleConsumer<X> consumer)
                                     throws X

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.

Type Parameters:

X - exception type thrown by the callback, if any.

Parameters:

consumer - A callback which will receive an open Handle

Throws:

X - any exception thrown by the callback

inTransaction

public <R,
X extends Exception> R inTransaction(HandleCallback<R,X> callback)
                                         throws X

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

Type Parameters:

R - type returned by the callback

X - exception type thrown by the callback, if any.

Parameters:

callback - A callback which will receive an open Handle, in a transaction

Returns:

the value returned by callback

Throws:

X - any exception thrown by the callback

useTransaction

public <X extends Exception> void useTransaction(HandleConsumer<X> callback)
                                          throws X

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

Type Parameters:

X - exception type thrown by the callback, if any.

Parameters:

callback - A callback which will receive an open Handle, in a transaction

Throws:

X - any exception thrown by the callback

inTransaction

public <R,
X extends Exception> R inTransaction(TransactionIsolationLevel level,
 HandleCallback<R,X> callback)
                                         throws X

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

This form accepts a transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.

Type Parameters:

R - type returned by the callback

X - exception type thrown by the callback, if any.

Parameters:

level - the transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.

callback - A callback which will receive an open Handle, in a transaction

Returns:

the value returned by callback

Throws:

X - any exception thrown by the callback

useTransaction

public <X extends Exception> void useTransaction(TransactionIsolationLevel level,
 HandleConsumer<X> callback)
                                          throws X

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

This form accepts a transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.

Type Parameters:

X - exception type thrown by the callback, if any.

Parameters:

level - the transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.

callback - A callback which will receive an open Handle, in a transaction

Throws:

X - any exception thrown by the callback

withExtension

public <R,
E,
X extends Exception> R withExtension(Class<E> extensionType,
 ExtensionCallback<R,E,X> callback)
                                            throws X

A convenience method which opens an extension of the given type, yields it to a callback, and returns the result of the callback. A handle is opened if needed by the extension, and closed before returning to the caller.

Type Parameters:

R - the return type

E - the extension type

X - the exception type optionally thrown by the callback

Parameters:

extensionType - the type of extension.

callback - a callback which will receive the extension.

Returns:

the value returned by the callback.

Throws:

NoSuchExtensionException - if no ExtensionFactory is registered which supports the given extension type.

X - if thrown by the callback.

useExtension

public <E,
X extends Exception> void useExtension(Class<E> extensionType,
 ExtensionConsumer<E,X> callback)
                                           throws X

A convenience method which opens an extension of the given type, and yields it to a callback. A handle is opened if needed by the extention, and closed before returning to the caller.

Type Parameters:

E - the extension type

X - the exception type optionally thrown by the callback

Parameters:

extensionType - the type of extension

callback - a callback which will receive the extension

Throws:

NoSuchExtensionException - if no ExtensionFactory is registered which supports the given extension type.

X - if thrown by the callback.

onDemand

public <E> E onDemand(Class<E> extensionType)

Creates an extension instance that uses the current Jdbi instance for database operations.

Type Parameters:

E - the extension type

Parameters:

extensionType - the type of extension. Must be a public interface type.

Returns:

an extension which opens and closes handles (as needed) for individual method calls. Only public interface types may be used as on-demand extensions.