1.7.0

This release brings internal API improvements, better support for the tooling and Dart as well as improvements to the Environment and tests APIs.

Breaking Changes

1. Removed deprecated APIs in the UtilityClassTest class.

   Please use subject() over removed getUtilityClass().

2. Removed deprecated methods in the Validate utility.

   Please consider migrating to mirrored methods in Preconditions2 and check out the related PR #596.

3. Removed deprecated methods in the Environment utility and introduced a new CustomEnvironmentType abstraction for custom environments.

   Consider changing your custom environments parent class from EnvironmentType to CustomEnvironmentType. And when registering new environments please use Environment.register(Class<? extends CustomEnvironmentType>) or the previously accessible method with an environment instance argument.

   Please use Environment.instance().is(Tests.class) over the previously deprecated and now removed Environment.isTests().

   Please use Environment.instance().is(Production.class) over the previously deprecated and now removed Environment.isProduction().

   To set a custom environment please use the Environment.setTo(Class<? extends EnvironmentType>) over the previously available method with an environment instance argument. Also, use the same method over the previously deprecated and now removed Environment.setToTests() and Environment.setToProduction().

   Consult PR #594 for extra details on the improvements and removals of the deprecated APIs.

4. MethodFactory and NestedClassFactory interfaces are extracted into a separate spine-tools-api artifact.

   In case you were implementing a custom MethodFactory or NestedClassFactory, please consider adding the spine-tools-api dependency to the respective module.

   You can use the following snippet to add the dependency to your Gradle project:

   dependencies {
       implementation("io.spine.tools:spine-tools-api:1.7.0")
   }

API changes

On top of the breaking changes here are some minor API changes introduced in the release.

1. Resource.file(String) is deprecated in favor of Resource.file(String, ClassLoader).

   It is always recommended to provide a particular ClassLoader instance to achieve predictable and reproducible access to resources while using the Resource utility. Please consult PR #566 for more details on the matter.

2. The new SingletonClassTest test abstraction to simplify testing singletons. (see PR #583 for details).

3. Improved test assertions support with the new Assertions and TempDir utilities available in the testlib project.

   The Assertions utility provides convenient assertions to verify that one of the exceptions was thrown by introducing the following methods:

   /**
    * Asserts that running the passed executable causes {@link IllegalArgumentException}.
    */
   @CanIgnoreReturnValue
   public static IllegalArgumentException assertIllegalArgument(Executable e)
   
   /**
    * Asserts that running the passed executable causes {@link IllegalStateException}.
    */
   @CanIgnoreReturnValue
   public static IllegalStateException assertIllegalState(Executable e)
   
   /**
    * Asserts that running the passed executable causes {@link UnknownTypeException}.
    */
   @CanIgnoreReturnValue
   public static UnknownTypeException assertUnknownType(Executable e)
   
   /**
    * Asserts that running the passed executable cases {@link NullPointerException}.
    */
   @CanIgnoreReturnValue
   public static NullPointerException assertNpe(Executable e)

   The TempDir provides a replacement for the deprecated com.google.common.io.Files#createTempDir().

   Please consult PR #585 for additional details.

4. The TypeUrl prefix is the Protobuf file declaration may now be empty.

   One may now specify an empty (type_url_prefix) option in the Protobuf if she does not intend to use
   the type URLs.

   The following declaration is now fully legit:

   syntax = "proto3";
   
   package spine.test.type;
   
   import "spine/options.proto";
   
   option (type_url_prefix) = "";
   option java_package = "io.spine.test.type";
   option java_outer_classname = "NoPrefixProto";
   option java_multiple_files = true;
   
   message TypeWithoutPrefix {
     string value = 1;
   }

   PR #588 provides more information on the matter.

5. The Diags utility now provides additional Collectors for commonly used diagnostics.

   The new Diags.toEnumeration() joins the item's string representation with a comma followed by a space character.

   ImmutableList<String> list = ImmutableList.of("foo", "bar", "baz");
   String output = list.stream().collect(Diags.toEnumeration());
   System.out.println(output); // prints "foo, bar, baz"

   The Diags.toEnumerationBackticked wraps each item's string representation into backticks and then joins to the result string with a comma followed by a space character.

   ImmutableList<String> list = ImmutableList.of("foo", "bar", "baz");
   String output = list.stream().collect(Diags.toEnumerationBackticked());
   System.out.println(output); // prints "`foo`, `bar`, `baz`"

Fixes

1. Gradle Proto Dart plugin now resolves relative imports. (see #572 and #573)

2. Enum values now also support (distinct) validation options (see #437 and #587)

Infrastructure

1. Spine Protoc plugin is now started by the Gradle Protobuf plugin without custom launch scripts (see #586 for details).

2. Proto Dart plugin resolves the pub cache better with the new PubCache utility (see #589).

3. The libraries now do not use implementation for compile-only annotations like errorprone annotations but use the newly introduced compileOnlyApi configuration for such dependencies (see #597).

Dependency upgrades

• Checker framework: 3.3.0 -> 3.7.1
• Error Prone: 2.3.4 -> 2.4.0
• Error Prone Gradle plugin: 1.2.1 -> 1.3.0
• Protubuf: 3.11.4 -> 3.13.0
• Protobuf Gradle plugin: 0.8.12 -> 0.8.13
• App Engine API: 1.9.79 -> 1.9.82
• Guava: 29.0-jre -> 30.0-jre
• jUnit 4: 4.12 -> 4.13.1
• jUnit Jupiter: 5.6.2 -> 5.7.0
• jUnit Platform: 1.6.2 -> 1.7.0
• jUnit Pioneer: 0.4.2. -> 1.0.0
• Truth: 1.0.1 -> 1.1
• Java Poet: 1.12.1 -> 1.13.0
• Auto Service: 1.0-rc6 -> 1.0-rc7
• Animal Sniffer: 1.18 -> 1.19
• OAuth JWT: 3.10.3 -> 3.11.0
• AssertK: 0.22 -> 0.23
• SLF4J: 1.7.29 -> 1.7.30

Compare v1.6.0 and v1.7.0.