feature: resolve conflicts according to strategies (#904)

The DataStore's sync engine will periodically try to publish local
changes up to AppSync. If AppSync already has a copy of the model
instance, a versioning conflict may occur. In this case, AppSync may
return a `ConflictUnhandledError` to the client, in the GraphQL response
error list.

As a customer, you can supply a handler to define custom logic when such
a conflict occurs. To do so, you provide a `DataStoreConflictHandler` to
the `DataStoreConfiguration` when constructing the `AWSDataStorePlugin`:

```java
DataStoreConfiguration config = DataStoreConfiguration.builder()
    .dataStoreConflictHandler(DataStoreConflictHandler.alwaysApplyRemote())
    .build();
Amplify.addPlugin(new AWSDataStorePlugin(config));
```

The ultimate goal of the user-provided handler will be to identify a
`ConflictResolutionDecision`, to be used to address the conflict:

1. `ConflictResolutionDecision.applyRemote()`:
   Just accept the remote copy of the data, and overwrite whatever we
   have locally
2. `ConflictResolutionDecision.retryLocal()`:
   Try to publish the local mutation again. If it fails a second time,
   surface an error, and do not rety additional times.
3. `ConflictResolutionDecision.retry(T userProvidedModel)`:
   Try to publish a new version of the model up to AppSync.
   If using this decision, please take care to ensure the model ID
   matches the ID of the data in conflict.

In the above configuration example, the
`DataStoreConflictHandler.alwaysApplyRemote()` configures a handler that
always chosen to accept the server's version of the data. A similar
`DataStoreConfigurationHandler.alwaysRetryLocal()` is also provided for
convenience. Fully-custom handlers may be provided as well, by
implementing the `DataSToreConfigurationHandler` interface's single
method, `onConflictDetected`.

Once you have elected a strategy in the handler, the DataStore's sync
engine will take over and fulfill the strategy you've requested. Prior
to the current commit, the conflict handler didn't actually do anything
on your behalf -- you were expected to code all resolution logic
directly in your handler. This is no longer necessary.

Resolves: #841

Author: jamesonwilliams

aws-api-appsync/build.gradle

@@ -29,6 +29,7 @@ dependencies {
         // https://github.com/robolectric/robolectric/issues/5245
         exclude group: 'com.google.auto.service', module: 'auto-service'
     }
+    testImplementation dependency.jsonassert
     testImplementation project(path: ':testmodels')
     testImplementation project(path: ':testutils')
 }

aws-api-appsync/src/main/java/com/amplifyframework/datastore/appsync/ModelWithMetadataDeserializer.java renamed to aws-api-appsync/src/main/java/com/amplifyframework/datastore/appsync/ModelWithMetadataAdapter.java

@@ -23,23 +23,29 @@
 import com.google.gson.JsonDeserializationContext;
 import com.google.gson.JsonDeserializer;
 import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
 import com.google.gson.JsonParseException;
+import com.google.gson.JsonSerializationContext;
+import com.google.gson.JsonSerializer;
 
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
+import java.util.Map;
 import java.util.Objects;
 
 /**
  * Deserializes JSON into {@link ModelWithMetadata}.
  */
-public final class ModelWithMetadataDeserializer implements JsonDeserializer<ModelWithMetadata<? extends Model>> {
+public final class ModelWithMetadataAdapter implements
+        JsonDeserializer<ModelWithMetadata<? extends Model>>,
+        JsonSerializer<ModelWithMetadata<? extends Model>> {
     /**
      * Register this deserializer into a {@link GsonBuilder}.
      * @param builder A {@link GsonBuilder}
      */
     public static void register(@NonNull GsonBuilder builder) {
         Objects.requireNonNull(builder);
-        builder.registerTypeAdapter(ModelWithMetadata.class, new ModelWithMetadataDeserializer());
+        builder.registerTypeAdapter(ModelWithMetadata.class, new ModelWithMetadataAdapter());
     }
 
     @Override
@@ -58,4 +64,24 @@ public ModelWithMetadata<? extends Model> deserialize(
         ModelMetadata metadata = context.deserialize(json, ModelMetadata.class);
         return new ModelWithMetadata<>(model, metadata);
     }
+
+    @Override
+    public JsonElement serialize(
+            ModelWithMetadata<? extends Model> src, Type typeOfSrc, JsonSerializationContext context) {
+        JsonObject result = new JsonObject();
+
+        // Flatten out the fields of the model and its metadata into a flat key-value map.
+        // To do this, serialize each individually, and then add the key/value pairs for each
+        // object into a new container.
+        JsonObject serializedMetadata = (JsonObject) context.serialize(src.getSyncMetadata());
+        for (Map.Entry<java.lang.String, JsonElement> entry : serializedMetadata.entrySet()) {
+            result.add(entry.getKey(), entry.getValue());
+        }
+        JsonObject serializedModel = (JsonObject) context.serialize(src.getModel());
+        for (Map.Entry<java.lang.String, JsonElement> entry : serializedModel.entrySet()) {
+            result.add(entry.getKey(), entry.getValue());
+        }
+
+        return result;
+    }
 }

aws-api-appsync/src/main/java/com/amplifyframework/util/GsonFactory.java

@@ -19,7 +19,7 @@
 import com.amplifyframework.core.model.query.predicate.GsonPredicateAdapters;
 import com.amplifyframework.core.model.temporal.GsonTemporalAdapters;
 import com.amplifyframework.core.model.types.GsonJavaTypeAdapters;
-import com.amplifyframework.datastore.appsync.ModelWithMetadataDeserializer;
+import com.amplifyframework.datastore.appsync.ModelWithMetadataAdapter;
 
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
@@ -50,7 +50,7 @@ private static Gson create() {
         GsonJavaTypeAdapters.register(builder);
         GsonPredicateAdapters.register(builder);
         GsonResponseAdapters.register(builder);
-        ModelWithMetadataDeserializer.register(builder);
+        ModelWithMetadataAdapter.register(builder);
         return builder.create();
     }
 }

aws-api-appsync/src/test/java/com/amplifyframework/datastore/appsync/ModelWithMetadataAdapterTest.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2020 Amazon.com, Inc. or its affiliates. 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.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package com.amplifyframework.datastore.appsync;
+
+import com.amplifyframework.core.model.temporal.GsonTemporalAdapters;
+import com.amplifyframework.core.model.temporal.Temporal;
+import com.amplifyframework.testmodels.commentsblog.BlogOwner;
+import com.amplifyframework.testutils.Resources;
+import com.amplifyframework.util.TypeMaker;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import org.json.JSONException;
+import org.json.JSONObject;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+import org.skyscreamer.jsonassert.JSONAssert;
+
+import java.lang.reflect.Type;
+import java.util.UUID;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Tests the {@link ModelWithMetadataAdapter}.
+ */
+public final class ModelWithMetadataAdapterTest {
+    private Gson gson;
+
+    /**
+     * We test the {@link ModelWithMetadataAdapter} through a vanilla Gson instance.
+     */
+    @Before
+    public void setup() {
+        GsonBuilder builder = new GsonBuilder();
+        ModelWithMetadataAdapter.register(builder);
+        GsonTemporalAdapters.register(builder);
+        this.gson = builder.create();
+    }
+
+    /**
+     * The Gson adapter can be used to serialize a ModelWithMetadata to JSON.
+     * @throws JSONException From JSONAssert.assert(...) call, if invalid JSON
+     *                       is provided in either position
+     */
+    @Test
+    public void adapterCanSerializeMwm() throws JSONException {
+        Temporal.Timestamp lastChangedAt = Temporal.Timestamp.now();
+        String modelId = UUID.randomUUID().toString();
+        ModelMetadata metadata = new ModelMetadata(modelId, false, 4, lastChangedAt);
+        BlogOwner model = BlogOwner.builder()
+            .name("Blog Owner")
+            .build();
+        ModelWithMetadata<BlogOwner> mwm = new ModelWithMetadata<>(model, metadata);
+
+        String expected = new JSONObject()
+            .put("id", model.getId())
+            .put("name", model.getName())
+            .put("_lastChangedAt", metadata.getLastChangedAt().getSecondsSinceEpoch())
+            .put("_deleted", metadata.isDeleted())
+            .put("_version", metadata.getVersion())
+            .toString();
+        String actual = gson.toJson(mwm);
+        JSONAssert.assertEquals(expected, actual, true);
+    }
+
+    /**
+     * The Gson adapter can be used to deserialize JSON into a ModelWithMetadata object.
+     */
+    @Test
+    public void adapterCanDeserializeJsonIntoMwm() {
+        // Arrange expected value
+        BlogOwner model = BlogOwner.builder()
+            .name("Tony Danielsen")
+            .id("45a5f600-8aa8-41ac-a529-aed75036f5be")
+            .build();
+        Temporal.Timestamp lastChangedAt = new Temporal.Timestamp(1594858827, TimeUnit.SECONDS);
+        ModelMetadata metadata = new ModelMetadata(model.getId(), false, 3, lastChangedAt);
+        ModelWithMetadata<BlogOwner> expected = new ModelWithMetadata<>(model, metadata);
+
+        // Arrange some JSON, and then try to deserialize it
+        String json = Resources.readAsString("blog-owner-with-metadata.json");
+        Type type = TypeMaker.getParameterizedType(ModelWithMetadata.class, BlogOwner.class);
+        ModelWithMetadata<BlogOwner> actual = gson.fromJson(json, type);
+
+        // Assert that the deserialized output matches out expected value
+        Assert.assertEquals(expected, actual);
+    }
+}

aws-api-appsync/src/test/resources/blog-owner-with-metadata.json

@@ -0,0 +1,8 @@
+{
+    "id": "45a5f600-8aa8-41ac-a529-aed75036f5be",
+    "name": "Tony Danielsen",
+    "_lastChangedAt": 1594858827,
+    "_version": 3,
+    "_deleted": false
+}
+

aws-datastore/src/main/java/com/amplifyframework/datastore/ApplyRemoteConflictHandler.java

@@ -108,7 +108,7 @@ public static DataStoreConfiguration defaults() throws DataStoreException {
         DataStoreErrorHandler errorHandler = DefaultDataStoreErrorHandler.instance();
         return builder()
             .errorHandler(errorHandler)
-            .conflictHandler(ApplyRemoteConflictHandler.instance(errorHandler))
+            .conflictHandler(DataStoreConflictHandler.alwaysApplyRemote())
             .syncInterval(DEFAULT_SYNC_INTERVAL_MINUTES, TimeUnit.MINUTES)
             .syncPageSize(DEFAULT_SYNC_PAGE_SIZE)
             .syncMaxRecords(DEFAULT_SYNC_MAX_RECORDS)
@@ -236,7 +236,7 @@ public static final class Builder {
 
         private Builder() {
             this.errorHandler = DefaultDataStoreErrorHandler.instance();
-            this.conflictHandler = ApplyRemoteConflictHandler.instance(errorHandler);
+            this.conflictHandler = DataStoreConflictHandler.alwaysApplyRemote();
             this.ensureDefaults = false;
         }
 
@@ -378,7 +378,7 @@ public DataStoreConfiguration build() throws DataStoreException {
                     DefaultDataStoreErrorHandler.instance());
                 conflictHandler = getValueOrDefault(
                     conflictHandler,
-                    ApplyRemoteConflictHandler.instance(errorHandler));
+                    DataStoreConflictHandler.alwaysApplyRemote());
                 syncIntervalInMinutes = getValueOrDefault(syncIntervalInMinutes, DEFAULT_SYNC_INTERVAL_MINUTES);
                 syncMaxRecords = getValueOrDefault(syncMaxRecords, DEFAULT_SYNC_MAX_RECORDS);
                 syncPageSize = getValueOrDefault(syncPageSize, DEFAULT_SYNC_PAGE_SIZE);