[DE-81] Feature/unicode db name (#405)

* unicode db names

* unicode db names tests

* gh actions upd

* gh actions upd

* UnicodeUtils

* fixed gh actions

* fixed gh actions

* initialize by default CursorEntity.extra and CursorEntity.Extras.stats to avoid NPE

* added disclaimer header

* DbName

* deprecated string db names in favour of DbName

* refactor internal use of string db names in favour of DbName

* moved DbName

* fixed links in javadoc

* changelog upd

* fixed db name for GET /_admin/server/id

* testing with preview docker images

* gh actions upd

* gh actions upd

* fixed compilation error

Author: rashtao

.github/workflows/maven.yml

@@ -19,12 +19,12 @@ jobs:
       fail-fast: false
       matrix:
         docker-img:
-          - docker.io/arangodb/arangodb:3.7.15
+          - docker.io/arangodb/arangodb:3.7.16
           - docker.io/arangodb/arangodb:3.8.4
-          - docker.io/arangodb/arangodb-preview:3.9.0-alpha.1
-          - docker.io/arangodb/enterprise:3.7.15
+          - docker.io/arangodb/arangodb-preview:3.9.0-beta.1
+          - docker.io/arangodb/enterprise:3.7.16
           - docker.io/arangodb/enterprise:3.8.4
-          - docker.io/arangodb/enterprise-preview:3.9.0-alpha.1
+          - docker.io/arangodb/enterprise-preview:3.9.0-beta.1
         topology:
           - single
           - cluster
@@ -35,6 +35,17 @@ jobs:
           - 8
         user-language:
           - en
+        include:
+          - docker-img: docker.io/arangodb/arangodb-preview:3.9.0-beta.1
+            topology: single
+            db-ext-names: true
+            java-version: 11
+            user-language: tr
+          - docker-img: docker.io/arangodb/enterprise-preview:3.9.0-beta.1
+            topology: cluster
+            db-ext-names: true
+            java-version: 17
+            user-language: tr
 
     steps:
       - uses: actions/checkout@v2
@@ -75,6 +86,21 @@ jobs:
           name: logs.tgz
           path: ./logs.tgz
 
+  # test encodeURIComponent() and normalize('NFC') comparing to Javascript behavior
+  test-graalvm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          version: 'latest'
+          java-version: '11'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Info
+        run: mvn -version
+      - name: Test
+        run: mvn -e --no-transfer-progress test -Dtest=com.arangodb.util.UnicodeUtilsTest
+
   test-jwt:
     timeout-minutes: 20
     runs-on: ubuntu-latest

ChangeLog.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+- added `DbName` class to represent database names in public API parameters, to ease unicode names normalization (#405)
+
 ## [6.15.0] - 2021-12-29
 
 - JWT authentication (#421)

pom.xml

@@ -219,6 +219,12 @@
             <version>0.9.12</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.graalvm.sdk</groupId>
+            <artifactId>graal-sdk</artifactId>
+            <version>21.2.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <dependencyManagement>

src/main/java/com/arangodb/ArangoDB.java

@@ -20,15 +20,7 @@
 
 package com.arangodb;
 
-import com.arangodb.entity.ArangoDBEngine;
-import com.arangodb.entity.ArangoDBVersion;
-import com.arangodb.entity.LoadBalancingStrategy;
-import com.arangodb.entity.LogEntity;
-import com.arangodb.entity.LogEntriesEntity;
-import com.arangodb.entity.LogLevelEntity;
-import com.arangodb.entity.Permissions;
-import com.arangodb.entity.ServerRole;
-import com.arangodb.entity.UserEntity;
+import com.arangodb.entity.*;
 import com.arangodb.internal.ArangoContext;
 import com.arangodb.internal.ArangoDBImpl;
 import com.arangodb.internal.ArangoDefaults;
@@ -50,10 +42,7 @@
 import com.arangodb.model.LogOptions;
 import com.arangodb.model.UserCreateOptions;
 import com.arangodb.model.UserUpdateOptions;
-import com.arangodb.util.ArangoCursorInitializer;
-import com.arangodb.util.ArangoDeserializer;
-import com.arangodb.util.ArangoSerialization;
-import com.arangodb.util.ArangoSerializer;
+import com.arangodb.util.*;
 import com.arangodb.velocypack.VPack;
 import com.arangodb.velocypack.VPackAnnotationFieldFilter;
 import com.arangodb.velocypack.VPackAnnotationFieldNaming;
@@ -701,8 +690,20 @@ public synchronized ArangoDB build() {
      *
      * @param name Name of the database
      * @return database handler
+     * @deprecated Use {@link #db(DbName)} instead
      */
-    ArangoDatabase db(String name);
+    @Deprecated
+    default ArangoDatabase db(String name) {
+        return db(DbName.of(name));
+    }
+
+    /**
+     * Returns a {@code ArangoDatabase} instance for the given database name.
+     *
+     * @param dbName Name of the database
+     * @return database handler
+     */
+    ArangoDatabase db(DbName dbName);
 
     /**
      * Creates a new database with the given name.
@@ -712,8 +713,23 @@ public synchronized ArangoDB build() {
      * @throws ArangoDBException
      * @see <a href="https://www.arangodb.com/docs/stable/http/database-database-management.html#create-database">API
      * Documentation</a>
+     * @deprecated Use {@link #createDatabase(DbName)} instead
+     */
+    @Deprecated
+    default Boolean createDatabase(String name) throws ArangoDBException {
+        return createDatabase(DbName.of(name));
+    }
+
+    /**
+     * Creates a new database with the given name.
+     *
+     * @param dbName Name of the database to create
+     * @return true if the database was created successfully.
+     * @throws ArangoDBException
+     * @see <a href="https://www.arangodb.com/docs/stable/http/database-database-management.html#create-database">API
+     * Documentation</a>
      */
-    Boolean createDatabase(String name) throws ArangoDBException;
+    Boolean createDatabase(DbName dbName) throws ArangoDBException;
 
     /**
      * Creates a new database with the given name.

src/main/java/com/arangodb/ArangoDatabase.java

@@ -52,8 +52,19 @@ public interface ArangoDatabase extends ArangoSerializationAccessor {
      * Returns the name of the database
      *
      * @return database name
+     * @deprecated Use {@link #dbName()} instead
      */
-    String name();
+    @Deprecated
+    default String name() {
+        return dbName().get();
+    }
+
+    /**
+     * Returns the name of the database
+     *
+     * @return database name
+     */
+    DbName dbName();
 
     /**
      * Returns the server name and version number.

src/main/java/com/arangodb/DbName.java

@@ -0,0 +1,82 @@
+package com.arangodb;
+
+import com.arangodb.internal.ArangoRequestParam;
+import com.arangodb.util.UnicodeUtils;
+
+import java.util.Objects;
+import java.util.function.Supplier;
+
+/**
+ * Class to represent a NFC-normalized database name (as required by ArangoDB extended naming convention).
+ * To instantiate use {@link DbName#of(String)} or {@link DbName#normalize(String)}.
+ *
+ * @see <a href="http://https://www.arangodb.com/docs/stable/data-modeling-naming-conventions-database-names.html">
+ * API Documentation</a>
+ */
+public final class DbName implements Supplier<String> {
+
+    /**
+     * DbName of the "_system" database.
+     */
+    public static final DbName SYSTEM = DbName.of(ArangoRequestParam.SYSTEM);
+
+    private final String value;
+
+    /**
+     * Creates a new {@link DbName} instance with the provided value. If the provided value is not
+     * <a href="https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms">NFC-normalized</a>, throws
+     * {@link IllegalArgumentException}. No transformation is applied to the provided value.
+     * Use {@link #normalize(String)} to create a DbName from a non-NFC-normalized value.
+     *
+     * @param value desired db name
+     * @return the created {@link DbName} instance
+     * @see <a href="https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms">NFC normalization</a>
+     * @see <a href="http://https://www.arangodb.com/docs/stable/data-modeling-naming-conventions-database-names.html">
+     * API Documentation</a>
+     */
+    public static DbName of(final String value) {
+        UnicodeUtils.checkNormalized(value);
+        return new DbName(value);
+    }
+
+    /**
+     * Creates a new {@link DbName} instance with the NFC normal form of the provided value.
+     * Note that the created {@link DbName} will hold a value potentially different from the provided one.
+     *
+     * @param value desired db name
+     * @return the created {@link DbName} instance
+     * @see <a href="https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms">NFC normalization</a>
+     * @see <a href="http://https://www.arangodb.com/docs/stable/data-modeling-naming-conventions-database-names.html">
+     * API Documentation</a>
+     */
+    public static DbName normalize(final String value) {
+        return new DbName(UnicodeUtils.normalize(value));
+    }
+
+    private DbName(final String value) {
+        this.value = value;
+    }
+
+    @Override
+    public String get() {
+        return value;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        DbName dbName = (DbName) o;
+        return Objects.equals(value, dbName.value);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(value);
+    }
+
+    @Override
+    public String toString() {
+        return get();
+    }
+}

src/main/java/com/arangodb/async/ArangoDBAsync.java

@@ -22,6 +22,7 @@
 
 import com.arangodb.ArangoDBException;
 import com.arangodb.ArangoSerializationAccessor;
+import com.arangodb.DbName;
 import com.arangodb.Protocol;
 import com.arangodb.async.internal.ArangoDBAsyncImpl;
 import com.arangodb.async.internal.velocystream.VstCommunicationAsync;
@@ -94,8 +95,20 @@ public interface ArangoDBAsync extends ArangoSerializationAccessor {
      *
      * @param name Name of the database
      * @return database handler
+     * @deprecated Use {@link #db(DbName)} instead
      */
-    ArangoDatabaseAsync db(final String name);
+    @Deprecated
+    default ArangoDatabaseAsync db(final String name) {
+        return db(DbName.of(name));
+    }
+
+    /**
+     * Returns a handler of the database by the given name
+     *
+     * @param dbName Name of the database
+     * @return database handler
+     */
+    ArangoDatabaseAsync db(final DbName dbName);
 
     /**
      * Creates a new database
@@ -104,8 +117,22 @@ public interface ArangoDBAsync extends ArangoSerializationAccessor {
      * @return true if the database was created successfully.
      * @see <a href="https://www.arangodb.com/docs/stable/http/database-database-management.html#create-database">API
      * Documentation</a>
+     * @deprecated Use {@link #createDatabase(DbName)} instead
+     */
+    @Deprecated
+    default CompletableFuture<Boolean> createDatabase(final String name) {
+        return createDatabase(DbName.of(name));
+    }
+
+    /**
+     * Creates a new database
+     *
+     * @param dbName database name
+     * @return true if the database was created successfully.
+     * @see <a href="https://www.arangodb.com/docs/stable/http/database-database-management.html#create-database">API
+     * Documentation</a>
      */
-    CompletableFuture<Boolean> createDatabase(final String name);
+    CompletableFuture<Boolean> createDatabase(final DbName dbName);
 
     /**
      * Creates a new database

src/main/java/com/arangodb/async/ArangoDatabaseAsync.java

@@ -22,6 +22,7 @@
 
 import com.arangodb.ArangoDBException;
 import com.arangodb.ArangoSerializationAccessor;
+import com.arangodb.DbName;
 import com.arangodb.entity.*;
 import com.arangodb.entity.arangosearch.AnalyzerEntity;
 import com.arangodb.entity.arangosearch.analyzer.SearchAnalyzer;
@@ -54,8 +55,19 @@ public interface ArangoDatabaseAsync extends ArangoSerializationAccessor {
      * Returns the name of the database
      *
      * @return database name
+     * @deprecated Use {@link #dbName()} instead
      */
-    String name();
+    @Deprecated
+    default String name() {
+        return dbName().get();
+    }
+
+    /**
+     * Returns the name of the database
+     *
+     * @return database name
+     */
+    DbName dbName();
 
     /**
      * Returns the server name and version number.