Posted on December 21, 2020

Spine 1.7.0

Base

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.

Core Java

This release brings numerous API improvements, as well as fixes and infrastructure updates to the framework.

Breaking Changes

1. The BlackBoxContext-based tests now fail if a runtime exception was thrown within the signal handlers.

   In order to address #1314, we’ve decided to enforce the fail-fast approach within the BBC tests done in #1322. From now on, if a test case had any runtime exceptions thrown from signal handlers the test is failed by the BBC. While it may be a breaking change for some, we believe it worth fixing such issues right away than hiding them under the carpet.

   If one requires to fall back to the previous behavior, the BBC instance can be configured using the newly introduced tolerateFailures method.

2. The grand_origin field is no longer set to a default instance for the signal Origin if no grand origin is present (see #1341 for details).

3. The ServerEnvironment API is improved and changed as a result of the #1315 and related discussions in a series of PRs (#1327, #1331, #1336).

   The previously deprecated configure...() API is removed in favor of the new fluent when().use() API.

   So now, instead of smth like this:

    ServerEnvironment.use(productionStorageFactory, Production.class)
                     .use(testingStorageFactory, Tests.class)
                     .use(memoizingTracerFactory, Production.class)
   

   One should use the following snippet:

    ServerEnvironment.when(Production.class)
                     .use(productionStorageFactory)
                     .use(memoizingTracerFactory);
    ServerEnvironment.when(Tests.class)
                     .use(testingStorageFactory);
   

API Changes

1. Change type validation requirements are relaxed for primitive type changes.

   The new_value field is no longer a required one for StringChange and BytesChange types. See #1307 for details.

2. Introduced simplified unicast() methods in the EventRouting.

   The new unicast() API allows simplifying and prettifying the even routing for the cases where a singular ID is used.

   Now, instead of smth like this:

     @OverridingMethodsMustInvokeSuper
     @Override
     protected void setupEventRouting(EventRouting<AirportId> routing) {
         super.setupEventRouting(routing);
         routing.route(FlightScheduled.class, (e, ctx)-> EventRoute.withId(e.getAirport()));
     }
   

   One can use the following API:

     @OverridingMethodsMustInvokeSuper
     @Override
     protected void setupEventRouting(EventRouting<AirportId> routing) {
         super.setupEventRouting(routing);
         routing.unicast(FlightScheduled.class, FlightScheduled::getAirport)
     }
   

   To find out more details on the new API please check #1317.

3. Added localDate and localDateTime helpers to the WithTime interface.

   This feature allows accessing localDate and localDateTime methods from within all the signals. From now on, if one requires a Java LocalDate or LocalDateTime instances over the Protobuf Timestamp or Java Instant that were previously available for signals, they may use the new API to simplify such a conversion and access to the signals timestamp field.

   See #1319 for additional details.

Fixes

1. Improved multitenant delivery support by ensuring the tenant is properly propagated within the delivery (see #1308).

2. Fixed a typo in the io.spine.client.Client shutdownTimeout method (see #1339).

3. Fixed dispatching of rejections caused by a particular command (see #1318 and #1343).

Infrastructure

1. 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 #1340).

Compare v1.6.0 and v1.7.0.

Bootstrap

This release brings the support of Spine components in version 1.7.0.

Dart support

This release brings experimental support for configuring spine-dart and Protobuf code generation for Dart projects.

For the Dart project setup instructions please see #74.

Compare v1.6.0 and v1.7.0.

Web

A public release of web-related Spine libraries.

Breaking Changes

1. The default grand_origin value must not be set for the signal Origin for the filtering anymore.

   With the #160 and upgrade to the newest version of the spine-server, the default (empty) grand_origin instance must not be set anymore. This change is already done for the JS client, but if one is using a custom solution, she must not set the default grand_origin.

2. The firebase-web artifact no longer provides the appengine-sdk dependency (see #153 and #155).

API Changes

1. New web test utilities.

   The testutil-web artifact now provides new test utilities that simplify the creation of pre-configured servlet requests and responses.

   If one needs an immutable HTTP request or response, she may use the KnownRequest and KnownResponse entries respectively. They allow setting a constant request or response data and headers that are not gonna be changed while the entry is being used.

   If it is required to verify that a response is modified by the underlying code, one may use the MemoizingResponse that records actions applied to it and allows getting back the modifications.

   If none of these matches the requirements, the MockedRequest and MockedResponse interfaces provide default no-op overrides for the respective HttpServletRequest and HttpServletResponse interfaces and could be implemented to match specific needs.

   See #159 for additional details.

Fixes

1. Fixed keep-up and cancellation of Firebase subscriptions from the spine-web client (see #154).

Infrastructure

1. 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 #159).

Dependency upgrades

• base64-js: 1.3.0 -> 1.5.1
• google-protobuf: 3.8.0 -> 3.13.0
• isomorphic-fetch: 2.2.1 -> 3.0.0
• uuid: 3.4.0 -> 8.3.2

Compare v1.6.0 and v1.7.0.

Google Cloud Java

A public release of GCP-related Spine libraries.

Infrastructure

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 #158).

Dependency upgrades

• Cloud Datastore: 1.102.2 -> 1.105.3
• Cloud Pub/Sub protos: 1.89.0 -> 1.92.1
• Cloud Trace: 0.109.3-beta -> 1.2.8

Compare v1.6.0 and v1.7.0.

JDBC Storage

A public release of the Spine spine-rdbms library.

Infrastructure

The library now does not use implementation for compile-only annotations like errorprone annotations but uses the newly introduced compileOnlyApi configuration for such dependencies (see #152).

Dependency upgrades

• Query DSL SQL: 4.2.2 -> 4.4.0
• HikariCP: 3.4.2 -> 3.4.5
• HSQL DB: 2.5.0 -> 2.5.1

Compare v1.6.0 and v1.7.0.

Time

A public release of the Spine time library.

The library now does not use implementation for compile-only annotations like errorprone annotations but uses the newly introduced compileOnlyApi configuration for such dependencies (see #105).

Compare v1.6.0 and v1.7.0.