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:

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

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

    • otjEmbeddedPostgres

      @Deprecated(since="3.41.2", forRemoval=true) public static JdbiOtjPostgresExtension otjEmbeddedPostgres()
      Deprecated, for removal: This API element is subject to removal in a future version.
      The OtjPostgres project ships its artifact as an automatic module with filename based module name. It is strongly discouraged to ship any JPMS enabled project that depends on automatic modules with filename based module names. We have reached out to the OtjPostgres project and proposed a change that would fix this. If they ship a version that fixes this before we are ready to move to full JPMS support, we will un-deprecate this class, otherwise it will be removed with our switch to JPMS.
      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.
      See Also:

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

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

    • 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