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 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:

    • 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.