From e34846c3a64897bacbbc4dff600cc01d2c812d8d Mon Sep 17 00:00:00 2001 From: "Henning P. Schmiedehausen" Date: Wed, 15 Dec 2021 18:33:18 -0800 Subject: [PATCH] add since 3.0 tags --- .../postgres/embedded/DatabaseInfo.java | 1 + .../postgres/embedded/DatabaseManager.java | 13 +++++++--- .../postgres/embedded/EmbeddedPostgres.java | 26 ++++++++++++------- .../embedded/EmbeddedPostgresPreparer.java | 1 + .../postgres/embedded/FlywayPreparer.java | 8 +++--- .../embedded/NativeBinaryLocator.java | 5 +++- .../embedded/NativeBinaryManager.java | 2 ++ .../TarXzCompressedBinaryManager.java | 6 +++-- .../embedded/ZonkyIOPostgresLocator.java | 2 ++ .../postgres/junit5/EmbeddedPgExtension.java | 6 +++-- .../postgres/junit5/MultiDatabaseBuilder.java | 6 +++-- .../junit5/RequirePostgresVersion.java | 2 +- .../junit5/SingleDatabaseBuilder.java | 6 +++-- 13 files changed, 57 insertions(+), 27 deletions(-) diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseInfo.java b/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseInfo.java index 80384a2..d0bbd37 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseInfo.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseInfo.java @@ -75,6 +75,7 @@ public abstract class DatabaseInfo { * PostgreSQL JDBC driver documentation for a comprehensive list. * * @return Map of key-value pairs representing data source connection properties. + * @since 3.0 */ @NonNull public abstract ImmutableMap connectionProperties(); diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseManager.java b/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseManager.java index adaeff6..cebc774 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseManager.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/DatabaseManager.java @@ -65,7 +65,7 @@ private DatabaseManager(Set> databasePrepar } /** - * Creates a new {@link Builder} instance that will create a new database on each call to {@link #getDatabaseInfo()}. + * Creates a new {@link Builder} instance that will create a new database on each call to {@link DatabaseManager#getDatabaseInfo()}. * * @return A builder instance. */ @@ -75,7 +75,8 @@ public static Builder multiDatabases() { } /** - * Creates a new {@link Builder} instance that will return a connection to the same database on each call to {@link #getDatabaseInfo()}. + * Creates a new {@link Builder} instance that will return a connection to the same database on each call to {@link + * DatabaseManager#getDatabaseInfo()}. * * @return A builder instance. */ @@ -277,7 +278,7 @@ protected Builder(boolean multiMode) { } /** - * @deprecated Use {@link #withDatabasePreparer(EmbeddedPostgresPreparer)}. + * @deprecated Use {@link DatabaseManager.Builder#withDatabasePreparer(EmbeddedPostgresPreparer)}. */ @Deprecated @NonNull @@ -293,6 +294,7 @@ public Builder withPreparer(@NonNull DatabasePreparer databasePreparer) { * * @param databasePreparer A {@link EmbeddedPostgresPreparer} instance. Must not be null. * @return This object instance. + * @since 3.0 */ @NonNull public Builder withDatabasePreparer(@NonNull EmbeddedPostgresPreparer databasePreparer) { @@ -307,6 +309,7 @@ public Builder withDatabasePreparer(@NonNull EmbeddedPostgresPreparer} instances. Must not be null. * @return This object instance. + * @since 3.0 */ @NonNull public Builder withDatabasePreparers(@NonNull Set> databasePreparers) { @@ -320,6 +323,7 @@ public Builder withDatabasePreparers(@NonNull Set} instance. Must not be null. * @return This object instance. + * @since 3.0 */ @NonNull public Builder withInstancePreparer(@NonNull EmbeddedPostgresPreparer instancePreparer) { @@ -333,6 +337,7 @@ public Builder withInstancePreparer(@NonNull EmbeddedPostgresPreparer} instances. Must not be null. * @return This object instance. + * @since 3.0 */ @NonNull public Builder withInstancePreparers(@NonNull Set> instancePreparers) { @@ -341,7 +346,7 @@ public Builder withInstancePreparers(@NonNull SetPostgres versioning * policy. - * * @since 4.1 */ public String getPostgresVersion() throws IOException { @@ -799,7 +798,7 @@ public Builder addServerConfiguration(@NonNull String key, @NonNull String value } /** - * @deprecated Use {@link #addInitDbConfiguration(String, String)}. + * @deprecated Use {@link Builder#addInitDbConfiguration(String, String)}. */ @Deprecated @NonNull @@ -821,6 +820,7 @@ public Builder addLocaleConfiguration(@NonNull String key, @NonNull String value * @param value initdb parameter value. Must not be null. When the empty string is used as the value, the resulting command line parameter will not have * a equal sign and a value assigned. * @return The builder itself. + * @since 3.0 */ @NonNull public Builder addInitDbConfiguration(@NonNull String key, @NonNull String value) { @@ -855,6 +855,7 @@ public Builder addConnectionProperty(@NonNull String key, @NonNull String value) * @param installationBaseDirectory The directory to unpack the postgres distribution. The current user must be able to create and write this directory. * Must not be null. * @return The builder itself. + * @since 3.0 */ @NonNull public Builder setInstallationBaseDirectory(@NonNull File installationBaseDirectory) { @@ -880,12 +881,14 @@ public Builder setPort(int port) { /** * Set the version of the PostgreSQL server. This value is passed to the default binary manager which will try to resolve this version from existing - * Maven artifacts. The value is ignored if {@link #setNativeBinaryManager(NativeBinaryManager)} is called. + * Maven artifacts. The value is ignored if {@link Builder#setNativeBinaryManager(NativeBinaryManager)} is called. *

* Not every PostgreSQL version is supported by pg-embedded. Some older versions lack the necessary options for the command line parameters and will * fail at startup. Currently, every version 10 or newer should be working. * * @param serverVersion A partial or full version. Valid values are e.g. "12" or "11.3". + * @return The builder itself. + * @since 3.0 */ @NonNull public Builder setServerVersion(@NonNull String serverVersion) { @@ -920,11 +923,12 @@ public Builder setOutputRedirector(@NonNull ProcessBuilder.Redirect outputRedire /** * Sets the {@link NativeBinaryManager} that provides the location of the postgres installation. Explicitly setting a binary manager overrides the - * installation base directory location set with {@link #setInstallationBaseDirectory(File)} as this is only used by the default binary manager. Calling - * {@link #setInstallationBaseDirectory(File)} after this method undoes setting the binary manager. + * installation base directory location set with {@link Builder#setInstallationBaseDirectory(File)} as this is only used by the default binary manager. + * Calling {@link Builder#setInstallationBaseDirectory(File)} after this method undoes setting the binary manager. * * @param nativeBinaryManager A {@link NativeBinaryManager} implementation. Must not be null. * @return The builder itself. + * @since 3.0 */ @NonNull public Builder setNativeBinaryManager(@NonNull NativeBinaryManager nativeBinaryManager) { @@ -935,10 +939,12 @@ public Builder setNativeBinaryManager(@NonNull NativeBinaryManager nativeBinaryM /** * Use a locally installed PostgreSQL server for tests. The tests will still spin up a new instance and locate the data in the data directory but it * will use the locally installed binaries for starting and stopping. Calling this method sets a binary manager, so it overrides {@link - * #setNativeBinaryManager(NativeBinaryManager)}. Calling this method makes the builder ignore the {@link #setInstallationBaseDirectory(File)} setting. + * Builder#setNativeBinaryManager(NativeBinaryManager)}. Calling this method makes the builder ignore the {@link + * Builder#setInstallationBaseDirectory(File)} setting. * * @param directory A local directory that contains a standard PostgreSQL installation. The directory must exist and read and executable. * @return The builder itself. + * @since 3.0 */ @NonNull public Builder useLocalPostgresInstallation(@NonNull File directory) { diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/EmbeddedPostgresPreparer.java b/src/main/java/de/softwareforge/testing/postgres/embedded/EmbeddedPostgresPreparer.java index f174630..4a19cf1 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/EmbeddedPostgresPreparer.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/EmbeddedPostgresPreparer.java @@ -24,6 +24,7 @@ * Allows e.g. for preparation of data sources, postgres instances and other places where additional degrees of customization are needed. * * @param The object type to be prepared. + * @since 3.0 */ @FunctionalInterface public interface EmbeddedPostgresPreparer { diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/FlywayPreparer.java b/src/main/java/de/softwareforge/testing/postgres/embedded/FlywayPreparer.java index 7833ed2..84ee7f6 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/FlywayPreparer.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/FlywayPreparer.java @@ -52,8 +52,8 @@ public static FlywayPreparer forClasspathLocation(String... locations) { } /** - * Create a new, uninitialized preparer instance. Use {@link #addCustomizer(Consumer)} to modify the configuration for the {@link FluentConfiguration} - * object. + * Create a new, uninitialized preparer instance. Use {@link FlywayPreparer#addCustomizer(Consumer)} to modify the configuration for the {@link + * FluentConfiguration} object. */ public FlywayPreparer() { } @@ -64,6 +64,7 @@ public FlywayPreparer() { * * @param customizer A {@link Consumer} instance. Must not be null. * @return This object. + * @since 3.0 */ @NonNull public FlywayPreparer addCustomizer(@NonNull Consumer customizer) { @@ -79,6 +80,7 @@ public FlywayPreparer addCustomizer(@NonNull Consumer custo * * @param customizers A set of {@link Consumer} instances. Must not be null. * @return This object. + * @since 3.0 */ @NonNull public FlywayPreparer addCustomizers(@NonNull Set> customizers) { @@ -89,7 +91,7 @@ public FlywayPreparer addCustomizers(@NonNull Set> } /** - * @deprecated Use {@link #addCustomizer(Consumer)}. + * @deprecated Use {@link FlywayPreparer#addCustomizer(Consumer)}. */ @Deprecated @NonNull diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryLocator.java b/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryLocator.java index 4bba253..6ae253c 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryLocator.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryLocator.java @@ -29,7 +29,10 @@ /** * Locates a native binary on the Filesystem. If necessary, it should download the binary first from the network. *

- * Implementations of this class must implement {@link Object#hashCode()} and {@link Object#equals(Object)} and *should* implement {@link Object#toString()}. + * Implementations of this class must implement {@link Object#hashCode()} and {@link Object#equals(Object)} and should implement {@link + * Object#toString()}. + * + * @since 3.0 */ public interface NativeBinaryLocator { diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryManager.java b/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryManager.java index 2b53966..a4403b5 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryManager.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/NativeBinaryManager.java @@ -20,6 +20,8 @@ /** * Returns an installation location for a native binary. The implementation is responsible for locating and optionally unpacking installing the binary. + * + * @since 3.0 */ @FunctionalInterface public interface NativeBinaryManager { diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/TarXzCompressedBinaryManager.java b/src/main/java/de/softwareforge/testing/postgres/embedded/TarXzCompressedBinaryManager.java index f689961..4a1f0b1 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/TarXzCompressedBinaryManager.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/TarXzCompressedBinaryManager.java @@ -47,6 +47,8 @@ /** * Loads a native binary installation and returns the location of it. + * + * @since 3.0 */ public final class TarXzCompressedBinaryManager implements NativeBinaryManager { @@ -66,8 +68,8 @@ public final class TarXzCompressedBinaryManager implements NativeBinaryManager { *

* The implementation of {@link NativeBinaryLocator} to locate the stream that gets unpacked must satisfy the following criteria: *

    - *
  • It must implement {@link #equals(Object)} and {@link #hashCode()}.
    • - *
  • It should implement {@link #toString()} to return meaningful information about the locator.
    • + *
  • It must override {@link Object#equals(Object)} and {@link Object#hashCode()}.
    • + *
  • It should implement {@link Object#toString()} to return meaningful information about the locator.
    • *
  • It must allow multiple calls to {@link NativeBinaryLocator#getInputStream()} which all return the same, byte-identical contents. * The operation should be cheap as it may be called multiple times.
    • *
diff --git a/src/main/java/de/softwareforge/testing/postgres/embedded/ZonkyIOPostgresLocator.java b/src/main/java/de/softwareforge/testing/postgres/embedded/ZonkyIOPostgresLocator.java index ffd1f68..78a8945 100644 --- a/src/main/java/de/softwareforge/testing/postgres/embedded/ZonkyIOPostgresLocator.java +++ b/src/main/java/de/softwareforge/testing/postgres/embedded/ZonkyIOPostgresLocator.java @@ -43,6 +43,8 @@ * io.zonky.test.postgres:embedded-postgres-binaries-<os>-<arch>. *

* See The Zonky IO github page for more details. + * + * @since 3.0 */ public final class ZonkyIOPostgresLocator implements NativeBinaryLocator { diff --git a/src/main/java/de/softwareforge/testing/postgres/junit5/EmbeddedPgExtension.java b/src/main/java/de/softwareforge/testing/postgres/junit5/EmbeddedPgExtension.java index 40eb71f..227b8ab 100644 --- a/src/main/java/de/softwareforge/testing/postgres/junit5/EmbeddedPgExtension.java +++ b/src/main/java/de/softwareforge/testing/postgres/junit5/EmbeddedPgExtension.java @@ -47,8 +47,8 @@ * This extension can provide the {@link EmbeddedPostgres} instance, a {@link DatabaseInfo} or a {@link DataSource} object as test parameters. * *

    - *
  • Using a {@link DatabaseInfo} parameter is equivalent to calling {@link #createDatabaseInfo()}.
    • - *
  • Using a {@link DataSource} parameter is equivalent to calling {@link #createDataSource()}.
    • + *
  • Using a {@link DatabaseInfo} parameter is equivalent to calling {@link EmbeddedPgExtension#createDatabaseInfo()}.
    • + *
  • Using a {@link DataSource} parameter is equivalent to calling {@link EmbeddedPgExtension#createDataSource()}.
    • *
*/ public final class EmbeddedPgExtension implements BeforeAllCallback, AfterAllCallback, BeforeEachCallback, AfterEachCallback, ParameterResolver { @@ -95,6 +95,8 @@ static EmbeddedPgExtensionBuilder singleDatabase() { * @RegisterExtension * public static EmbeddedPgExtension pg = MultiDatabaseBuilder.instanceWithDefaults().build(); * } + * + * @since 3.0 */ public EmbeddedPgExtension() { this(new DatabaseManagerBuilder(true).withInstancePreparer(EmbeddedPostgres.Builder::withDefaults)); diff --git a/src/main/java/de/softwareforge/testing/postgres/junit5/MultiDatabaseBuilder.java b/src/main/java/de/softwareforge/testing/postgres/junit5/MultiDatabaseBuilder.java index 75ae478..298b8b1 100644 --- a/src/main/java/de/softwareforge/testing/postgres/junit5/MultiDatabaseBuilder.java +++ b/src/main/java/de/softwareforge/testing/postgres/junit5/MultiDatabaseBuilder.java @@ -52,7 +52,7 @@ public static DatabaseManager.Builder instanceWithDefaults( } /** - * @deprecated Use {@link #preparedInstance(EmbeddedPostgresPreparer)}. + * @deprecated Use {@link MultiDatabaseBuilder#preparedInstance(EmbeddedPostgresPreparer)}. */ @Deprecated @NonNull @@ -61,7 +61,7 @@ public static DatabaseManager.Builder preparedInstance(@Non } /** - * @deprecated Use {@link #preparedInstanceWithDefaults(EmbeddedPostgresPreparer)}. + * @deprecated Use {@link MultiDatabaseBuilder#preparedInstanceWithDefaults(EmbeddedPostgresPreparer)}. */ @Deprecated @NonNull @@ -74,6 +74,7 @@ public static DatabaseManager.Builder preparedInstanceWithD * * @param databasePreparer A {@link EmbeddedPostgresPreparer} instance. Must not be null. * @return A {@link DatabaseManager.Builder} instance that can be customized further. + * @since 3.0 */ @NonNull public static DatabaseManager.Builder preparedInstance(@NonNull EmbeddedPostgresPreparer databasePreparer) { @@ -86,6 +87,7 @@ public static DatabaseManager.Builder preparedInstance(@Non * * @param databasePreparer A {@link EmbeddedPostgresPreparer} instance. Must not be null. * @return A {@link DatabaseManager.Builder} instance that can be customized further. + * @since 3.0 */ @NonNull public static DatabaseManager.Builder preparedInstanceWithDefaults(@NonNull EmbeddedPostgresPreparer databasePreparer) { diff --git a/src/main/java/de/softwareforge/testing/postgres/junit5/RequirePostgresVersion.java b/src/main/java/de/softwareforge/testing/postgres/junit5/RequirePostgresVersion.java index cbf8897..0faad09 100644 --- a/src/main/java/de/softwareforge/testing/postgres/junit5/RequirePostgresVersion.java +++ b/src/main/java/de/softwareforge/testing/postgres/junit5/RequirePostgresVersion.java @@ -21,7 +21,7 @@ import org.junit.jupiter.api.extension.ExtendWith; /** - * {@code @RequirePostgresVersion} signals the annotated test class or method that it only should execute if the PostgreSQL server is within a specific range. + * {@code RequirePostgresVersion} signals the annotated test class or method that it only should execute if the PostgreSQL server is within a specific range. * If the version is outside the range, the annotated test class or method is skipped. *

* PostgreSQL versions are interpreted as described in the Versioning Policy and structured as diff --git a/src/main/java/de/softwareforge/testing/postgres/junit5/SingleDatabaseBuilder.java b/src/main/java/de/softwareforge/testing/postgres/junit5/SingleDatabaseBuilder.java index 51c8887..b4c613b 100644 --- a/src/main/java/de/softwareforge/testing/postgres/junit5/SingleDatabaseBuilder.java +++ b/src/main/java/de/softwareforge/testing/postgres/junit5/SingleDatabaseBuilder.java @@ -53,7 +53,7 @@ public static DatabaseManager.Builder instanceWithDefaults( } /** - * @deprecated Use {@link #preparedInstance(EmbeddedPostgresPreparer)}. + * @deprecated Use {@link SingleDatabaseBuilder#preparedInstance(EmbeddedPostgresPreparer)}. */ @Deprecated @NonNull @@ -62,7 +62,7 @@ public static DatabaseManager.Builder preparedInstance(@Non } /** - * @deprecated Use {@link #preparedInstanceWithDefaults(EmbeddedPostgresPreparer)}. + * @deprecated Use {@link SingleDatabaseBuilder#preparedInstanceWithDefaults(EmbeddedPostgresPreparer)}. */ @Deprecated @NonNull @@ -75,6 +75,7 @@ public static DatabaseManager.Builder preparedInstanceWithD * * @param databasePreparer A {@link EmbeddedPostgresPreparer} instance. Must not be null. * @return A {@link DatabaseManager.Builder} instance that can be customized further. + * @since 3.0 */ @NonNull public static DatabaseManager.Builder preparedInstance(@NonNull EmbeddedPostgresPreparer databasePreparer) { @@ -87,6 +88,7 @@ public static DatabaseManager.Builder preparedInstance(@Non * * @param databasePreparer A {@link EmbeddedPostgresPreparer} instance. Must not be null. * @return A {@link DatabaseManager.Builder} instance that can be customized further. + * @since 3.0 */ @NonNull public static DatabaseManager.Builder preparedInstanceWithDefaults(@NonNull EmbeddedPostgresPreparer databasePreparer) {