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 and Description
static Jdbi	create(Connection connection)
static Jdbi	create(ConnectionFactory connectionFactory) Factory used to allow for obtaining a Connection in a customized manner.
static Jdbi	create(DataSource dataSource)
static Jdbi	create(String url)
static Jdbi	create(String url, Properties properties)
static Jdbi	create(String url, String username, String password)
ConfigRegistry	getConfig() Returns the configuration registry associated with this object.
StatementBuilderFactory	getStatementBuilderFactory()
TransactionHandler	getTransactionHandler()
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)
Handle	open() Obtain a Handle to the data source wrapped by this Jdbi instance.
static Handle	open(Connection connection) Create a Handle wrapping a particular JDBC Connection
static Handle	open(ConnectionFactory connectionFactory) Convenience method used to obtain a handle from a ConnectionFactory.
static Handle	open(DataSource dataSource) Convenience method used to obtain a handle from a specific data source
static Handle	open(String url) 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(String url, String username, String password) Obtain a handle with just a JDBC URL
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> 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(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

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

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

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

Method Detail

create

public static Jdbi create(Connection connection)

Parameters:

connection - db connection

Returns:

a Jdbi which works on single connection

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(DataSource dataSource)

Parameters:

dataSource - the data source.

Returns:

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

create

public static Jdbi create(String url)

Parameters:

url - JDBC URL for connections

Returns:

a Jdbi which uses DriverManager as a connection factory.

create

public static Jdbi create(String url,
                          Properties properties)

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)

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.

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.

getStatementBuilderFactory

public StatementBuilderFactory getStatementBuilderFactory()

Returns:

the current StatementBuilderFactory

getTransactionHandler

public TransactionHandler getTransactionHandler()

Returns:

the TransactionHandler

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

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

inTransaction

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

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

X extends Exception

inTransaction

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

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

X extends Exception

onDemand

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

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.

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)

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(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(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(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,
                          Properties props)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

props - JDBC properties

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

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

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

useExtension

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

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.

X extends Exception

useHandle

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

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:

callback - A callback which will receive an open Handle

Throws:

X - any exception thrown by the callback

X extends Exception

useTransaction

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

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

X extends Exception

useTransaction

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

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

X extends Exception

withExtension

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

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.

X extends Exception

withHandle

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

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

X extends Exception