[1.x] Allow to override the default mappings provided by `DsColumnMapping`

[armiol]

This PR reproduces and addresses core-java#1536.

Previously, it was not possible to clear columns of some Proto types, since it was not possible to distinguish between meaningful "default values" set to columns on purpose, and those "default values" which in fact signalized of "no value set".

Changing the API of DsColumnMapping

:exclamation: This is a breaking change.

Previously, SPI users could only extend DsColumnMapping's behavior by overriding this method:

protected void setupCustomMapping(
            ImmutableMap.Builder<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> builder);

It was good enough if one wanted to append their mapping rules. But such an approach did not allow to re-define the existing (framework-default) mapping — since a builder of ImmutableMap was passed, preventing from having duplicate keys.

Now, the API for SPI users implies overriding another method:

@SPI
protected ImmutableMap<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> customMapping()

This one allows to return an immutable map of mappings, combining them into the final result, giving priority to those values which were provided by SPI users.

Please see the documentation for DsColumnMapping for more details.

How to use it

Referring to the original issue, end-users may configure how Timestamp.getDefaultValue() is stored for some column. In the example below, a Datastore-specific null is written for such values to the corresponding property of respective Datastore Entity:

/**
 * A mapping similar to the default one,
 * but telling to store {@link Timestamp}s as {@code null}s.
 */
public final class CustomMapping extends DsColumnMapping {

    @Override
    protected ImmutableMap<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> customMapping() {
        return ImmutableMap.of(Timestamp.class, ofNullableTimestamp());
    }

    @SuppressWarnings("UnnecessaryLambda" /* For brevity */)
    private static ColumnTypeMapping<Timestamp, Value<?>> ofNullableTimestamp() {
        return timestamp -> {
            if (timestamp.equals(Timestamp.getDefaultInstance())) {
                return NullValue.of();
            }
            return TimestampValue.of(
                    ofTimeSecondsAndNanos(timestamp.getSeconds(), timestamp.getNanos())
            );
        };
    }
}

Updates to TestDatastoreStorageFactory

Additionally, this changeset updates the API of TestDatastoreStorageFactory utility to allow access to two features:

1. Creation of a test-only storage factory with some custom mapping.
2. Accessing "raw" DatastoreWrapper via public API, which is useful to verify the actual content of Datastore entities written.

See TestDatastoreStorageFactory for detail, and have a look at the usage example in DsProjectionColumnsTest.

The library version is set to 1.9.1.

[armiol]

@yevhenii-nadtochii PTAL. I feel it won't hurt to have another pair of eyes on this.

[armiol]

@yevhenii-nadtochii

But I would add somewhere in docs to DsColumnMapping.customMapping() that this method is a workaround for AbstractColumnMapping.setupCustomMapping(...). This word pops up when I see these two similar-named methods and their docs, but it is not said explicitly.

For this library, this is not a workaround. DsColumnMapping.setupCustomMapping() is made final, so nobody is now able to override it. The only extension point is DsColumnMapping.customMapping(), which is why it is now explicitly marked with @SPI.

Also, if such is a wish, it is possible to create a descendant from AbstractColumnMapping, in spirit of port-based architecture, and use it to configure DatstoreStorageFactory. It has not changed, but generally speaking that would be strange to see from Spine users.