Release 1.17.0

[yuri-sergiichuk]

This PR does the release of the library version 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 Remove deprecated API #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 Improve environment #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 Always specify a ClassLoader for Resource #566 for more details on the matter.

2. The new SingletonClassTest test abstraction to simplify testing singletons. (see PR Class tests #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 Improve testlib #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 TypeUrl without type prefix #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 Patch imports in types.dart #572 and Allow short relative paths in imports #573)

2. Enum values now also support (distinct) validation options (see Add message casters for Protobuf descriptors #437 and Allow usage of (distinct) option on enums #587)

Infrastructure

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

2. Proto Dart plugin resolves the pub cache better with the new PubCache utility (see PubCache API #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 Improve dependencies management and use new compileOnlyApi scope #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

[codecov]

Codecov Report

Merging #598 (67649eb) into master (4b1fefa) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #598   +/-   ##
=========================================
  Coverage     77.91%   77.91%           
  Complexity     3029     3029           
=========================================
  Files           510      510           
  Lines         11490    11490           
  Branches        667      667           
=========================================
  Hits           8952     8952           
  Misses         2311     2311           
  Partials        227      227           

[alexander-yevsyukov]

Why do we still need JUnit4 and Slf4J? Can we drop these dependencies?

Why do we mention App Engine API dependency in the context of base?

[yuri-sergiichuk]

@alexander-yevsyukov we're forcing these dependencies and while base is ultimately our super dependency and we do not track releases for the config module I'd say it's the best place to mention these updates. I do not plan to mention dependency updates in any other release notes.

No, with our current dependency resolution strategy, we cannot drop these.

[alexander-yevsyukov]

LGTM