Package org.jdbi.v3.testing.junit5

Class JdbiExtension

java.lang.Object

org.jdbi.v3.testing.junit5.JdbiExtension

All Implemented Interfaces:

AfterAllCallback, AfterEachCallback, BeforeAllCallback, BeforeEachCallback, Extension, ParameterResolver

Direct Known Subclasses:

JdbiExternalPostgresExtension, JdbiGenericExtension, JdbiH2Extension, JdbiOtjPostgresExtension, JdbiPostgresExtension, JdbiSqliteExtension, JdbiTestcontainersExtension

public abstract class JdbiExtension
extends Object
implements BeforeAllCallback, AfterAllCallback, BeforeEachCallback, AfterEachCallback, ParameterResolver

Common functionality for all JUnit 5 extensions.

Subclasses can be used with the @ExtendWith annotation to declare an extension if they provide a public no-args constructor.

When using declarative registration, test methods can declare a Jdbi and/or a Handle parameter which is injected through this extension. The getJdbi() is used to obtain the Jdbi object and getSharedHandle()} is used for the Handle instance.

Programmatic registration is preferred as this allows further customization of each extension.

See Also:

• JdbiH2Extension
• JdbiPostgresExtension
• JdbiSqliteExtension
• JdbiExternalPostgresExtension
• JdbiOtjPostgresExtension

Method Summary

Modifier and Type	Method	Description
void	afterAll(ExtensionContext context)
void	afterEach(ExtensionContext context)
final <T> T	attach(Class<T> extension)	Convenience method to attach an extension (such as a SqlObject) to the shared handle.
void	beforeAll(ExtensionContext context)
void	beforeEach(ExtensionContext context)
final JdbiExtension	enableLeakChecker(boolean enable)	Enable tracking of cleanable resources and handles when running tests.
static JdbiExtension	externalPostgres(String hostname, Integer port, String database, String username, String password)	Creates an extension that uses an external (outside the scope of an unit test class) postgres database.
final Jdbi	getJdbi()	Returns a Jdbi instance linked to the data source used by this extension.
final Handle	getSharedHandle()	Returns a shared Handle used by the extension.
abstract String	getUrl()	Returns a JDBC url representing the data source used by this extension.
static JdbiExtension	h2()	Creates a new extension using the H2 database.
final JdbiExtension	installPlugins()	When creating the Jdbi instance, call the Jdbi.installPlugins() method, which loads all plugins discovered by the ServiceLoader API.
final Handle	openHandle()	Open a new Handle to the used data source.
static JdbiOtjPostgresExtension	otjEmbeddedPostgres()	Creates a new extension using a managed, embedded postgres database.
static JdbiExtension	postgres(de.softwareforge.testing.postgres.junit5.EmbeddedPgExtension pg)	Creates a new extension using a managed, embedded postgres database.
Object	resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext)
static JdbiExtension	sqlite()	Creates a new extension using the SQLite database.
boolean	supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext)
final <C extends JdbiConfig<C>> JdbiExtension	withConfig(Class<C> configClass, Consumer<C> configurer)	Set a JdbiConfig parameter when creating the Jdbi instance.
final JdbiExtension	withInitializer(JdbiExtensionInitializer initializer)	Sets a JdbiExtensionInitializer to initialize the Jdbi instance or the attached data source before running a test.
final JdbiExtension	withPlugin(JdbiPlugin plugin)	Install a JdbiPlugin when creating the Jdbi instance.
final JdbiExtension	withPlugins(JdbiPlugin... pluginList)	Install multiple JdbiPlugins when creating the Jdbi instance.

Methods inherited from class java.lang.Object

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

Method Details

postgres

public static JdbiExtension postgres(de.softwareforge.testing.postgres.junit5.EmbeddedPgExtension pg)

Creates a new extension using a managed, embedded postgres database. Using this method requires the de.softwareforge.testing:pg-embedded component and the postgres JDBC driver on the class path.

It references an embedded pg extension, which must be added to the class independently and can be managed as a per-class extension, not a per-method extension:

     @RegisterExtension
     public static EmbeddedPgExtension pg = MultiDatabaseBuilder.instanceWithDefaults().build();

     @RegisterExtension
     public JdbiExtension postgres = JdbiExtension.postgres(pg);
 

This is the most efficient way to run multiple tests within the same class that use a postgres database.

Parameters:

pg - Reference to an embedded postgres database. This extension must be separately added to the test class.

Returns:

A JdbiExtension connected to a managed postgres data source.

See Also:

• JdbiPostgresExtension

externalPostgres

public static JdbiExtension externalPostgres(@Nonnull
 String hostname,
 @Nullable
 Integer port,
 @Nonnull
 String database,
 @Nullable
 String username,
 @Nullable
 String password)

Creates an extension that uses an external (outside the scope of an unit test class) postgres database. Using this method requires the postgres JDBC driver on the classpath.

Parameters:

hostname - Hostname of the database.

port - Port of the database. Can be null, in that case the default port is used.

database - Database name.

username - Username to access the database. Can be null.

password - Password to access the database. Can be null.

Returns:

A JdbiExtension connected to an external postgres data source.

See Also:

• JdbiExternalPostgresExtension

otjEmbeddedPostgres

public static JdbiOtjPostgresExtension otjEmbeddedPostgres()

Creates a new extension using a managed, embedded postgres database. Using this method requires the com.opentable.components:otj-pg-embedded component and the postgres JDBC driver on the class path.

     @RegisterExtension
     public JdbiExtension postgres = JdbiExtension.otjEmbeddedPostgres();
 

Compared to the postgres(EmbeddedPgExtension) method, this extension spins up a new postgres instance for each test method and is slower. It should only be used to migrate existing code that uses the JUnit 4 JdbiRule quickly to JUnit 5.

Returns:

A JdbiExtension connected to a managed postgres data source.

h2

public static JdbiExtension h2()

Creates a new extension using the H2 database. Each call to this method creates a new database which is transient and in-memory. Using this method requires the com.h2database:h2 component on the classpath.

     @RegisterExtension
     public JdbiExtension h2 = JdbiExtension.h2();
 

Returns:

A JdbiExtension connected to a managed h2 data source.

See Also:

• JdbiH2Extension

sqlite

public static JdbiExtension sqlite()

Creates a new extension using the SQLite database. Each call to this method creates a new database which is transient and in-memory. Using this method requires the org.xerial:sqlite-jdbc component on the classpath.

     @RegisterExtension
     public JdbiExtension sqlite = JdbiExtension.sqlite();
 

Returns:

A JdbiExtension connected to a managed sqlite data source.

See Also:

• JdbiSqliteExtension

getJdbi

public final Jdbi getJdbi()

Returns a Jdbi instance linked to the data source used by this extension. There is only a single Jdbi instance and multiple calls to this method return the same instance.

Returns:

A Jdbi instance.

getUrl

public abstract String getUrl()

Returns a JDBC url representing the data source used by this extension. This url is database-specific and may or may not be used to connect to the data source outside testing code that uses this extension (e.g. the JdbiSqliteExtension returns a constant uri for all database instances).

Returns:

A string representing the JDBC URL.

getSharedHandle

public final Handle getSharedHandle()

Returns a shared Handle used by the extension. This handle exists during the lifetime of the extension and is connected to the data source used by the extension. Multiple calls to this method always return the same instance.

Returns:

A Handle instance.

installPlugins

public final JdbiExtension installPlugins()

When creating the Jdbi instance, call the Jdbi.installPlugins() method, which loads all plugins discovered by the ServiceLoader API.

Returns:

The extension itself for chaining method calls.

enableLeakChecker

public final JdbiExtension enableLeakChecker(boolean enable)

Enable tracking of cleanable resources and handles when running tests. This is useful to find code paths where JDBI managed resources are not correctly handled and "leak" out.

Parameters:

enable - If true, enables the leak checker, otherwise disables it.

withPlugin

public final JdbiExtension withPlugin(JdbiPlugin plugin)

Install a JdbiPlugin when creating the Jdbi instance.

Parameters:

plugin - A plugin to install.

Returns:

The extension itself for chaining method calls.

withPlugins

public final JdbiExtension withPlugins(JdbiPlugin... pluginList)

Install multiple JdbiPlugins when creating the Jdbi instance.

Parameters:

pluginList - One or more JdbiPlugin instances.

Returns:

The extension itself for chaining method calls.

withInitializer

public final JdbiExtension withInitializer(JdbiExtensionInitializer initializer)

Sets a JdbiExtensionInitializer to initialize the Jdbi instance or the attached data source before running a test.

Returns:

The extension itself for chaining method calls.

openHandle

public final Handle openHandle()

Open a new Handle to the used data source. Multiple calls to this method return multiple instances that are all connected to the same data source.

Returns:

A Handle object. The handle must be closed to release the database connection.

withConfig

public final <C extends JdbiConfig<C>>
JdbiExtension withConfig(Class<C> configClass,
 Consumer<C> configurer)

Set a JdbiConfig parameter when creating the Jdbi instance. Any JdbiConfig type can be referenced in this method call.

     @RegisterExtension
     public JdbiExtension h2Extension = JdbiExtension.h2().withPlugin(new SqlObjectPlugin())
             .withConfig(RowMappers.class, r -> r.register(Foo.class, new FooMapper());
 

Type Parameters:

C - The config type. Must extend JdbiConfig.

Parameters:

configClass - A class instance which must implement JdbiConfig.

configurer - A Consumer to access the JdbiConfig instance.

Returns:

The extension itself for chaining method calls.

attach

public final <T> T attach(Class<T> extension)

Convenience method to attach an extension (such as a SqlObject) to the shared handle.

beforeEach

public void beforeEach(ExtensionContext context)
                throws Exception

Specified by:

beforeEach in interface BeforeEachCallback

Throws:

Exception

beforeAll

public void beforeAll(ExtensionContext context)
               throws Exception

Specified by:

beforeAll in interface BeforeAllCallback

Throws:

Exception

afterEach

public void afterEach(ExtensionContext context)
               throws Exception

Specified by:

afterEach in interface AfterEachCallback

Throws:

Exception

afterAll

public void afterAll(ExtensionContext context)
              throws Exception

Specified by:

afterAll in interface AfterAllCallback

Throws:

Exception

supportsParameter

public boolean supportsParameter(ParameterContext parameterContext,
 ExtensionContext extensionContext)

Specified by:

supportsParameter in interface ParameterResolver

resolveParameter

public Object resolveParameter(ParameterContext parameterContext,
 ExtensionContext extensionContext)

Specified by:

resolveParameter in interface ParameterResolver