Package org.jdbi.v3.core

Class Jdbi

java.lang.Object

org.jdbi.v3.core.Jdbi

All Implemented Interfaces:

Configurable<Jdbi>

public class Jdbi
extends java.lang.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.

Field Summary

Fields

Modifier and Type	Field	Description
private ConfigRegistry	config
private ConnectionFactory	connectionFactory
private static org.slf4j.Logger	LOG
private java.util.concurrent.CopyOnWriteArrayList<JdbiPlugin>	plugins
private java.util.concurrent.atomic.AtomicReference<StatementBuilderFactory>	statementBuilderFactory
private java.lang.ThreadLocal<HandleSupplier>	threadHandleSupplier
private java.util.concurrent.atomic.AtomicReference<TransactionHandler>	transactionhandler

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Jdbi(ConnectionFactory connectionFactory)

Method Summary

Modifier and Type	Method	Description
private <R,E,X extends java.lang.Exception> R	callWithExtension(java.lang.Class<E> extensionType, ExtensionCallback<R,E,X> callback, HandleSupplier handleSupplier)
static Jdbi	create(java.lang.String url)	Creates a new Jdbi instance from a database URL.
static Jdbi	create(java.lang.String url, java.lang.String username, java.lang.String password)	Creates a new Jdbi instance from a database URL.
static Jdbi	create(java.lang.String url, java.util.Properties properties)	Creates a new Jdbi instance from a database URL.
static Jdbi	create(java.sql.Connection connection)	Creates a new Jdbi object from a Connection.
static Jdbi	create(javax.sql.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.
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 java.lang.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 java.lang.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(java.lang.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(java.lang.String url)	Obtain a handle with just a JDBC URL
static Handle	open(java.lang.String url, java.lang.String username, java.lang.String password)	Obtain a handle with just a JDBC URL
static Handle	open(java.lang.String url, java.util.Properties props)	Obtain a handle with just a JDBC URL
static Handle	open(java.sql.Connection connection)	Create a Handle wrapping a particular JDBC Connection
static Handle	open(javax.sql.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	setStatementBuilderFactory(StatementBuilderFactory factory)	Allows customization of how prepared statements are created.
Jdbi	setTransactionHandler(TransactionHandler handler)	Specify the TransactionHandler instance to use.
<E,X extends java.lang.Exception> void	useExtension(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Exception> R	withExtension(java.lang.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 java.lang.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, 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

Field Detail

LOG

private static final org.slf4j.Logger LOG

config

private final ConfigRegistry config

connectionFactory

private final ConnectionFactory connectionFactory

transactionhandler

private final java.util.concurrent.atomic.AtomicReference<TransactionHandler> transactionhandler

statementBuilderFactory

private final java.util.concurrent.atomic.AtomicReference<StatementBuilderFactory> statementBuilderFactory

plugins

private final java.util.concurrent.CopyOnWriteArrayList<JdbiPlugin> plugins

threadHandleSupplier

private final java.lang.ThreadLocal<HandleSupplier> threadHandleSupplier

Constructor Detail

Jdbi

private Jdbi(ConnectionFactory connectionFactory)

Method Detail

create

public static Jdbi create(java.sql.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(javax.sql.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(java.lang.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(java.lang.String url,
                          java.util.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(java.lang.String url,
                          java.lang.String username,
                          java.lang.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(javax.sql.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(java.sql.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(java.lang.String url)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

Returns:

newly opened Handle

open

public static Handle open(java.lang.String url,
                          java.lang.String username,
                          java.lang.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(java.lang.String url,
                          java.util.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

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 java.lang.Exception> R withHandle(HandleCallback<R,X> callback)
                                                     throws X extends java.lang.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 java.lang.Exception

useHandle

public <X extends java.lang.Exception> void useHandle(HandleConsumer<X> consumer)
                                               throws X extends java.lang.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:

consumer - A callback which will receive an open Handle

Throws:

X - any exception thrown by the callback

X extends java.lang.Exception

inTransaction

public <R,X extends java.lang.Exception> R inTransaction(HandleCallback<R,X> callback)
                                                        throws X extends java.lang.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 java.lang.Exception

useTransaction

public <X extends java.lang.Exception> void useTransaction(HandleConsumer<X> callback)
                                                    throws X extends java.lang.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 java.lang.Exception

inTransaction

public <R,X extends java.lang.Exception> R inTransaction(TransactionIsolationLevel level,
                                                               HandleCallback<R,X> callback)
                                                        throws X extends java.lang.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 java.lang.Exception

useTransaction

public <X extends java.lang.Exception> void useTransaction(TransactionIsolationLevel level,
                                                           HandleConsumer<X> callback)
                                                    throws X extends java.lang.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 java.lang.Exception

withExtension

public <R,E,X extends java.lang.Exception> R withExtension(java.lang.Class<E> extensionType,
                                                                       ExtensionCallback<R,E,X> callback)
                                                                throws X extends java.lang.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 java.lang.Exception

callWithExtension

private <R,E,X extends java.lang.Exception> R callWithExtension(java.lang.Class<E> extensionType,
                                                                            ExtensionCallback<R,E,X> callback,
                                                                            HandleSupplier handleSupplier)
                                                                     throws X extends java.lang.Exception

Throws:

X extends java.lang.Exception

useExtension

public <E,X extends java.lang.Exception> void useExtension(java.lang.Class<E> extensionType,
                                                                 ExtensionConsumer<E,X> callback)
                                                          throws X extends java.lang.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 java.lang.Exception

onDemand

public <E> E onDemand(java.lang.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.