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

.github/workflows/build-on-ubuntu.yml

@@ -19,9 +19,9 @@ jobs:
 
       # This operation is specific to `gcloud-java` repository only.
       - name: Decrypt the credentials for the Spine-Dev service account
-        run: ./scripts/decrypt.sh "$SPINE_DEV_KEY" ./.github/keys/spine-dev.json.gpg ./spine-dev.json
+        run: ./config/scripts/decrypt.sh "$SPINE_DEV_CI_KEY" ./.github/keys/spine-dev-framework-ci.json.gpg ./spine-dev.json
         env:
-          SPINE_DEV_KEY: ${{ secrets.SPINE_DEV_KEY }}
+          SPINE_DEV_CI_KEY: ${{ secrets.SPINE_DEV_CI_KEY }}
 
         # The OS-managed Google Cloud SDK does not provide a Datastore emulator.
       - name: Remove the OS-managed Google Cloud SDK

README.md

@@ -16,16 +16,16 @@ Gradle:
 ```kotlin
 dependencies {
     // Datastore Storage support library.
-    implementation("io.spine.gcloud:spine-datastore:1.8.0")
+    implementation("io.spine.gcloud:spine-datastore:1.9.1")
 
     // Pub/Sub messaging support library.
-    implementation("io.spine.gcloud:spine-pubsub:1.8.0")
+    implementation("io.spine.gcloud:spine-pubsub:1.9.1")
 
     // Stackdriver Trace support library.
-    implementation("io.spine.gcloud:spine-stackdriver-trace:1.8.0")
+    implementation("io.spine.gcloud:spine-stackdriver-trace:1.9.1")
 
     // Datastore-related test utilities (if needed).
-    implementation("io.spine.gcloud:testutil-gcloud:1.8.0")
+    implementation("io.spine.gcloud:testutil-gcloud:1.9.1")
 }
 ```
 

datastore/src/main/java/io/spine/server/storage/datastore/DsColumnMapping.java

@@ -39,11 +39,16 @@
 import com.google.protobuf.ByteString;
 import com.google.protobuf.Message;
 import com.google.protobuf.Timestamp;
+import io.spine.annotation.SPI;
 import io.spine.core.Version;
 import io.spine.server.entity.storage.AbstractColumnMapping;
+import io.spine.server.entity.storage.ColumnMapping;
 import io.spine.server.entity.storage.ColumnTypeMapping;
 import io.spine.string.Stringifiers;
 
+import java.util.HashMap;
+import java.util.Map;
+
 import static com.google.cloud.Timestamp.ofTimeSecondsAndNanos;
 
 /**
@@ -52,16 +57,57 @@
  * <p>All column values are stored as Datastore {@link Value}-s.
  *
  * <p>Users of the storage can extend this class to specify their own column mapping for the
- * selected types.
+ * selected types. See {@link DsColumnMapping#customMapping() DsColumnMapping.customMapping()}.
+ *
+ * @see DatastoreStorageFactory.Builder#setColumnMapping(ColumnMapping)
  */
 public class DsColumnMapping extends AbstractColumnMapping<Value<?>> {
 
+    private static final Map<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> defaults
+            = ImmutableMap.of(Timestamp.class, ofTimestamp(),
+                              Version.class, ofVersion());
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Merges the default column mapping rules with those provided by SPI users.
+     * In case there are duplicate mappings for some column type, the value provided
+     * by SPI users is used.
+     *
+     * @apiNote This method is made {@code final}, as it is designed
+     *         to use {@code ImmutableMap.Builder}, which does not allow to override values.
+     *         Therefore, it is not possible for SPI users to provide their own mapping rules
+     *         for types such as {@code Timestamp}, for which this class already has
+     *         a default mapping. SPI users should override
+     *         {@link #customMapping() DsColumnMapping.customMapping()} instead.
+     */
     @Override
-    protected void
+    protected final void
     setupCustomMapping(
             ImmutableMap.Builder<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> builder) {
-        builder.put(Timestamp.class, ofTimestamp());
-        builder.put(Version.class, ofVersion());
+        Map<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> merged = new HashMap<>();
+        ImmutableMap<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> custom = customMapping();
+        merged.putAll(defaults);
+        merged.putAll(custom);
+        builder.putAll(merged);
+    }
+
+    /**
+     * Returns the custom column mapping rules.
+     *
+     * <p>This method is designed for SPI users in order to be able to re-define
+     * and-or append their custom mapping. As by default, {@code DsColumnMapping}
+     * provides rules for {@link Timestamp} and {@link Version}, SPI users may
+     * choose to either override these defaults by returning their own mapping for these types,
+     * or supply even more mapping rules.
+     *
+     * <p>By default, this method returns an empty map.
+     *
+     * @return custom column mappings, per Java class of column
+     */
+    @SPI
+    protected ImmutableMap<Class<?>, ColumnTypeMapping<?, ? extends Value<?>>> customMapping() {
+        return ImmutableMap.of();
     }
 
     @Override
@@ -120,16 +166,26 @@ protected ColumnTypeMapping<Message, StringValue> ofMessage() {
         return o -> NullValue.of();
     }
 
-    @SuppressWarnings({"ProtoTimestampGetSecondsGetNano", "UnnecessaryLambda"})
-    // This behavior is intended.
-    private static ColumnTypeMapping<Timestamp, TimestampValue> ofTimestamp() {
+    /**
+     * Returns the default mapping from {@link Timestamp} to {@link TimestampValue}.
+     */
+    @SuppressWarnings({
+            "ProtoTimestampGetSecondsGetNano" /* In order to create exact value. */,
+            "UnnecessaryLambda" /* For brevity.*/,
+            "WeakerAccess" /* To allow access for SPI users. */})
+    protected static ColumnTypeMapping<Timestamp, TimestampValue> ofTimestamp() {
         return timestamp -> TimestampValue.of(
                 ofTimeSecondsAndNanos(timestamp.getSeconds(), timestamp.getNanos())
         );
     }
 
-    @SuppressWarnings("UnnecessaryLambda")
-    private static ColumnTypeMapping<Version, LongValue> ofVersion() {
+    /**
+     * Returns the default mapping from {@link Version} to {@link LongValue}.
+     */
+    @SuppressWarnings({
+            "UnnecessaryLambda" /* For brevity.*/,
+            "WeakerAccess" /* To allow access for SPI users. */})
+    protected static ColumnTypeMapping<Version, LongValue> ofVersion() {
         return version -> LongValue.of(version.getNumber());
     }
 }

datastore/src/test/java/io/spine/server/storage/datastore/DsProjectionColumnsTest.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2023, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.server.storage.datastore;
+
+import com.google.cloud.datastore.Key;
+import com.google.protobuf.Timestamp;
+import io.spine.core.Version;
+import io.spine.server.ContextSpec;
+import io.spine.server.projection.ProjectionStorage;
+import io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.CustomMapping;
+import io.spine.test.datastore.College;
+import io.spine.test.datastore.CollegeId;
+import io.spine.testing.server.storage.datastore.TestDatastoreStorageFactory;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static com.google.common.truth.Truth.assertThat;
+import static io.spine.server.storage.datastore.RecordId.ofEntityId;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.COLLEGE_CLS;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.COLLEGE_KIND;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.clearAdmission;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.futureFromNow;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.newCollege;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.newId;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.someVersion;
+import static io.spine.server.storage.datastore.given.DsProjectionColumnsTestEnv.writeAndReadDeadline;
+import static io.spine.server.storage.datastore.given.TestEnvironment.singleTenantSpec;
+import static io.spine.testing.server.storage.datastore.TestDatastoreStorageFactory.local;
+
+@DisplayName("When dealing with `Projection` columns, `DsProjectionStorage` should")
+final class DsProjectionColumnsTest {
+
+    private static final TestDatastoreStorageFactory datastoreFactory = local(new CustomMapping());
+
+    @Test
+    @DisplayName("allow clearing the column values " +
+            "if the column mapping used returns Datastore-specific `null` " +
+            "for their values")
+    void clearTimestampColumns() {
+        ContextSpec spec = singleTenantSpec();
+        ProjectionStorage<CollegeId> storage =
+                datastoreFactory.createProjectionStorage(spec, COLLEGE_CLS);
+        DatastoreWrapper datastore = datastoreFactory.createDatastoreWrapper(false);
+
+        CollegeId id = newId();
+        Key key = datastore.keyFor(COLLEGE_KIND, ofEntityId(id));
+        Version version = someVersion();
+
+        Timestamp admissionDeadline = futureFromNow();
+        College college = newCollege(id, admissionDeadline);
+
+        com.google.cloud.Timestamp storedDeadline =
+                writeAndReadDeadline(college, version, storage, datastore, key);
+        assertThat(storedDeadline).isNotNull();
+
+        College collegeNoAdmission = clearAdmission(college);
+        com.google.cloud.Timestamp presumablyEmptyDeadline =
+                writeAndReadDeadline(collegeNoAdmission, version, storage, datastore, key);
+        assertThat(presumablyEmptyDeadline)
+                .isNull();
+    }
+}