Backport Cleaner and ArrayIndex (#333)

Also: Change JSON time converter to UTC

common/main/cpp/com_couchbase_lite_internal_core_impl_NativeC4Collection.h

@@ -108,6 +108,15 @@ JNIEXPORT void
 JNICALL Java_com_couchbase_lite_internal_core_impl_NativeC4Collection_createValueIndex
         (JNIEnv *, jclass, jlong, jstring, jint, jstring);
 
+/*
+ * Class:     com_couchbase_lite_internal_core_impl_NativeC4Collection
+ * Method:    createArrayIndex
+ * Signature: (JLjava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
+ */
+JNIEXPORT void JNICALL
+Java_com_couchbase_lite_internal_core_impl_NativeC4Collection_createArrayIndex
+        (JNIEnv *, jclass, jlong, jstring, jstring, jstring);
+
 /*
  * Class:     com_couchbase_lite_internal_core_impl_NativeC4Collection
  * Method:    createFullTextIndex

common/main/cpp/native_c4collection.cc

@@ -265,6 +265,27 @@ Java_com_couchbase_lite_internal_core_impl_NativeC4Collection_createValueIndex(
     createIndex(env, coll, kC4ValueIndex, jName, (C4QueryLanguage) qLanguage, jqueryExpressions, options);
 }
 
+/*
+ * Class:     com_couchbase_lite_internal_core_impl_NativeC4Collection
+ * Method:    createArrayIndex
+ * Signature: (JLjava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
+ */
+JNIEXPORT void JNICALL
+Java_com_couchbase_lite_internal_core_impl_NativeC4Collection_createArrayIndex(
+        JNIEnv *env,
+        jclass ignore,
+        jlong coll,
+        jstring jName,
+        jstring jpath,
+        jstring jqueryExpressions) {
+    jstringSlice path(env, jpath);
+
+    C4IndexOptions options = {};
+    //options.path = path.c_str();
+
+    createIndex(env, coll, kC4ArrayIndex, jName, kC4N1QLQuery, jqueryExpressions, options);
+}
+
 /*
  * Class:     com_couchbase_lite_internal_core_impl_NativeC4Collection
  * Method:    createFullTextIndex

common/main/java/com/couchbase/lite/ArrayIndexConfiguration.java

@@ -0,0 +1,97 @@
+//
+// Copyright (c) 2024 Couchbase, Inc 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
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License 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.couchbase.lite;
+
+import androidx.annotation.NonNull;
+
+import java.util.Arrays;
+import java.util.List;
+
+import com.couchbase.lite.internal.core.C4Collection;
+import com.couchbase.lite.internal.utils.Preconditions;
+
+
+/**
+ * Configuration for indexing property values within nested arrays
+ * in documents, intended for use with the UNNEST query.
+ */
+public final class ArrayIndexConfiguration extends IndexConfiguration {
+    private final String path;
+
+    /**
+     * Initializes the configuration with paths to the nested array
+     * and the expressions for the values within the arrays to be indexed.
+     *
+     * @param path        Path to the array, which can be nested to be indexed.
+     *                    Use "[]" to represent a property that is an array of each
+     *                    nested array level. For a single array or the last level
+     *                    array, the "[]" is optional. For instance, use
+     *                    "contacts[].phones" to specify an array of phones within each
+     *                    contact.
+     * @param expressions An optional list of strings, where each string
+     *                    represents an expression defining the values within the array
+     *                    to be indexed. If the array specified by the path contains
+     *                    scalar values, this parameter can be null.
+     */
+    public ArrayIndexConfiguration(@NonNull String path, @NonNull String... expressions) {
+        this(path, Arrays.asList(expressions));
+    }
+
+    /**
+     * Initializes the configuration with paths to the nested array with
+     * no expressions constraining the values within the arrays to be indexed.
+     *
+     * @param path Path to the array, which can be nested to be indexed.
+     *             Use "[]" to represent a property that is an array of each
+     *             nested array level. For a single array or the last level
+     *             array, the "[]" is optional. For instance, use
+     *             "contacts[].phones" to specify an array of phones within each
+     *             contact.
+     */
+    public ArrayIndexConfiguration(@NonNull String path) { this(path, Arrays.asList("")); }
+
+    /**
+     * Initializes the configuration with paths to the nested array
+     * and the expressions for the values within the arrays to be indexed.
+     *
+     * @param path        Path to the array, which can be nested to be indexed.
+     *                    Use "[]" to represent a property that is an array of each
+     *                    nested array level. For a single array or the last level
+     *                    array, the "[]" is optional. For instance, use
+     *                    "contacts[].phones" to specify an array of phones within each
+     *                    contact.
+     * @param expressions An optional list of strings, where each string
+     *                    represents an expression defining the values within the array
+     *                    to be indexed. If the array specified by the path contains
+     *                    scalar values, this parameter can be null.
+     */
+    public ArrayIndexConfiguration(@NonNull String path, @NonNull List<String> expressions) {
+        super(expressions);
+        this.path = Preconditions.assertNotNull(path, "path");
+    }
+
+    /**
+     * Path to the array, which can be nested.
+     */
+    @NonNull
+    public String getPath() { return path; }
+
+    @Override
+    void createIndex(@NonNull String name, @NonNull C4Collection c4Collection)
+        throws LiteCoreException, CouchbaseLiteException {
+        c4Collection.createArrayIndex(name, path, getIndexSpec());
+    }
+}

common/main/java/com/couchbase/lite/FullTextIndexConfiguration.java

@@ -38,7 +38,7 @@ public final class FullTextIndexConfiguration extends IndexConfiguration {
 
     public FullTextIndexConfiguration(@NonNull String... expressions) { this(Arrays.asList(expressions)); }
 
-    FullTextIndexConfiguration(@NonNull List<String> expressions) { super(expressions); }
+    public FullTextIndexConfiguration(@NonNull List<String> expressions) { super(expressions); }
 
     /**
      * The language code which is an ISO-639 language such as "en", "fr", etc.

common/main/java/com/couchbase/lite/IndexConfiguration.java

@@ -33,14 +33,15 @@ public abstract class IndexConfiguration extends AbstractIndex {
     IndexConfiguration(@NonNull String... expressions) { this(Arrays.asList(expressions)); }
 
     IndexConfiguration(@NonNull List<String> expressions) {
-        this.expressions = Preconditions.assertNotEmpty(
-            Fn.filterToList(expressions, s -> !StringUtils.isEmpty(s)),
-            "expression list");
+        this.expressions = Fn.filterToList(Preconditions.assertNotEmpty(expressions, "expressions"), s -> s != null);
+        if (expressions.size() != this.expressions.size()) {
+            throw new IllegalArgumentException("Null expressions are not legal");
+        }
     }
 
     @NonNull
-    public List<String> getExpressions() { return new ArrayList<>(expressions); }
+    public final List<String> getExpressions() { return new ArrayList<>(expressions); }
 
     @NonNull
-    String getIndexSpec() { return StringUtils.join(",", expressions); }
+    final String getIndexSpec() { return StringUtils.join(",", expressions); }
 }

common/main/java/com/couchbase/lite/ValueIndexConfiguration.java

@@ -30,7 +30,7 @@
 public final class ValueIndexConfiguration extends IndexConfiguration {
     public ValueIndexConfiguration(@NonNull String... expressions) { this(Arrays.asList(expressions)); }
 
-    ValueIndexConfiguration(@NonNull List<String> expressions) { super(expressions); }
+    public ValueIndexConfiguration(@NonNull List<String> expressions) { super(expressions); }
 
     @Override
     void createIndex(@NonNull String name, @NonNull C4Collection c4Collection) throws LiteCoreException {

common/main/java/com/couchbase/lite/internal/core/C4Collection.java

@@ -49,6 +49,8 @@ long nCreateCollection(long c4Db, @NonNull String scope, @NonNull String collect
 
         void nCreateValueIndex(long peer, String name, int queryLanguage, String indexSpec) throws LiteCoreException;
 
+        void nCreateArrayIndex(long peer, String name, String path, String indexSpec) throws LiteCoreException;
+
         void nCreateFullTextIndex(
             long peer,
             String name,
@@ -91,6 +93,7 @@ public static C4Collection create(@NonNull C4Database c4db, @NonNull String scop
         return create(NATIVE_IMPL, c4db, scope, collection);
     }
 
+    @GuardedBy("dbLock")
     @Nullable
     public static C4Collection get(@NonNull C4Database c4db, @NonNull String scope, @NonNull String collection)
         throws LiteCoreException {
@@ -119,6 +122,7 @@ static C4Collection create(
     }
 
     @VisibleForTesting
+    @GuardedBy("dbLock")
     @Nullable
     static C4Collection get(
         @NonNull NativeImpl impl,
@@ -240,6 +244,10 @@ public void createValueIndex(String name, int queryLanguage, String indexSpec) t
         withPeer(peer -> impl.nCreateValueIndex(peer, name, queryLanguage, indexSpec));
     }
 
+    public void createArrayIndex(String name, String path, String indexSpec) throws LiteCoreException {
+        withPeer(peer -> impl.nCreateArrayIndex(peer, name, path, indexSpec));
+    }
+
     public void createFullTextIndex(
         String name,
         int queryLanguage,