More minor fixes, mainly naming and comments.

Signed-off-by: Alexander Lowey-Weber <alexander.weber@here.com>

Author: xeus2001

here-naksha-cli/src/jvmMain/java/com/here/naksha/cli/storages/GeneratingSession.java

@@ -115,7 +115,7 @@ public NakshaCatalog getMapById(@NotNull String mapId) {
 
     @Nullable
     @Override
-    public NakshaCatalog getMapByNumber(int mapNumber) {
+    public NakshaCatalog getMapByNumber(int catalogNumber) {
         throw new NakshaException(NakshaError.UNSUPPORTED_OPERATION, "");
     }
 
@@ -127,7 +127,7 @@ public NakshaCollection getCollectionById(@NotNull NakshaCatalog map, @NotNull S
 
     @Nullable
     @Override
-    public NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog map, int collectionNumber) {
+    public NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog catalog, int collectionNumber) {
         throw new NakshaException(NakshaError.UNSUPPORTED_OPERATION, "");
     }
 

here-naksha-lib-hub/src/jvmMain/java/com/here/naksha/lib/hub/storages/NHAdminStorageReader.java

@@ -114,12 +114,12 @@ public Response executeParallel(@NotNull Request request) {
 
   @Override
   public @Nullable NakshaCatalog getMapById(@NotNull String mapId) {
-    return session.getMapById(mapId);
+    return session.getCatalogById(mapId);
   }
 
   @Override
-  public @Nullable NakshaCatalog getMapByNumber(int mapNumber) {
-    return session.getMapByNumber(mapNumber);
+  public @Nullable NakshaCatalog getMapByNumber(int catalogNumber) {
+    return session.getMapByNumber(catalogNumber);
   }
 
   @Override
@@ -133,8 +133,8 @@ public void loadTuples(@NotNull List<? extends FeatureTuple> featureTuples, int
   }
 
   @Override
-  public @Nullable NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog map, int collectionNumber) {
-    return session.getCollectionByNumber(map, collectionNumber);
+  public @Nullable NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog catalog, int collectionNumber) {
+    return session.getCollectionByNumber(catalog, collectionNumber);
   }
 
   @Override

here-naksha-lib-hub/src/jvmMain/java/com/here/naksha/lib/hub/storages/NHSpaceStorageReader.java

@@ -342,7 +342,7 @@ public Response executeParallel(@NotNull Request request) {
   }
 
   @Override
-  public @Nullable NakshaCatalog getMapByNumber(int mapNumber) {
+  public @Nullable NakshaCatalog getMapByNumber(int catalogNumber) {
     throw NOT_SUPPORTED_ERROR;
   }
 
@@ -357,7 +357,7 @@ public void loadTuples(@NotNull List<? extends FeatureTuple> featureTuples, int
   }
 
   @Override
-  public @Nullable NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog map, int collectionNumber) {
+  public @Nullable NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog catalog, int collectionNumber) {
     throw NOT_SUPPORTED_ERROR;
   }
 

here-naksha-lib-hub/src/jvmTest/java/com/here/naksha/lib/hub/mock/NHAdminReaderMock.java

@@ -284,7 +284,7 @@ public Response executeParallel(@NotNull Request request) {
   }
 
   @Override
-  public @Nullable NakshaCatalog getMapByNumber(int mapNumber) {
+  public @Nullable NakshaCatalog getMapByNumber(int catalogNumber) {
     throw new NakshaException(new NakshaError(NakshaError.UNSUPPORTED_OPERATION, "Not supported by mock yet"));
   }
 
@@ -294,7 +294,7 @@ public Response executeParallel(@NotNull Request request) {
   }
 
   @Override
-  public @Nullable NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog map, int collectionNumber) {
+  public @Nullable NakshaCollection getCollectionByNumber(@NotNull NakshaCatalog catalog, int collectionNumber) {
     throw new NakshaException(new NakshaError(NakshaError.UNSUPPORTED_OPERATION, "Not supported by mock yet"));
   }
 

here-naksha-lib-jbon/src/commonMain/kotlin/naksha/jbon/IDictReader.kt

@@ -9,6 +9,7 @@ import kotlin.js.JsExport
  * @since 3.0
  */
 @JsExport
+@Deprecated("To be removed")
 interface IDictReader {
     /**
      * Retrieve the dictionary with the given identifier.

here-naksha-lib-model/src/commonMain/kotlin/naksha/model/ISession.kt

@@ -110,44 +110,44 @@ interface ISession : AutoCloseable {
     /**
      * Returns the map for the given identifier.
      *
-     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return maps that were created in the current session, but beware that these maps may eventually fail to commit.
-     * @param mapId the map-id for which to return the latest HEAD state.
-     * @return the map; _null_ if no such map exists.
+     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return catalogs that were created in the current session, but beware that these catalogs may eventually fail to commit.
+     * @param catalogId the catalog-id for which to return the latest HEAD state.
+     * @return the catalog; _null_ if no such catalog exists.
      * @since 3.0
      */
-    fun getMapById(mapId: String): NakshaCatalog?
+    fun getCatalogById(catalogId: String): NakshaCatalog?
 
     /**
-     * Returns the map for the given number.
+     * Returns the catalog for the given number.
      *
-     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return maps that were created in the current session, but beware that these maps may eventually fail to commit.
-     * @param mapNumber the map-number for which to return the latest HEAD state.
-     * @return the map; _null_ if no such map exists.
+     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return catalogs that were created in the current session, but beware that these catalogs may eventually fail to commit.
+     * @param catalogNumber the catalog-number for which to return the latest HEAD state.
+     * @return the catalog; _null_ if no such catalog exists.
      * @since 3.0
      */
-    fun getMapByNumber(mapNumber: Int): NakshaCatalog?
+    fun getMapByNumber(catalogNumber: Int): NakshaCatalog?
 
     /**
      * Returns the collection for the given identifier.
      *
-     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return maps that were created in the current session, but beware that these collections may eventually fail to commit.
-     * @param map the map to query.
+     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return collections that were created in the current session, but beware that these collections may eventually fail to commit.
+     * @param catalog the catalog to query.
      * @param collectionId the collection-id for which to return the latest HEAD state.
      * @return the collection; _null_ if no such collection exists.
      * @since 3.0
      */
-    fun getCollectionById(map: NakshaCatalog, collectionId: String): NakshaCollection?
+    fun getCollectionById(catalog: NakshaCatalog, collectionId: String): NakshaCollection?
 
     /**
      * Returns the collection for the given number.
      *
-     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return maps that were created in the current session, but beware that these collections may eventually fail to commit.
-     * @param map the map to query.
+     * This method does only access the internal caching, and may not be up-to-date. If invoked on a [write session][IWriteSession] before committing changes, it will return collections that were created in the current session, but beware that these collections may eventually fail to commit.
+     * @param catalog the catalog to query.
      * @param collectionNumber the collection-number for which to return the latest HEAD state.
      * @return the collection; _null_ if no such collection exists.
      * @since 3.0
      */
-    fun getCollectionByNumber(map: NakshaCatalog, collectionNumber: Int): NakshaCollection?
+    fun getCollectionByNumber(catalog: NakshaCatalog, collectionNumber: Int): NakshaCollection?
 
     /**
      * Load all tuples into the given [feature-tuples][FeatureTuple].

here-naksha-lib-model/src/commonMain/kotlin/naksha/model/IStorage.kt

@@ -145,16 +145,4 @@ interface IStorage : IDictReader {
         val session = newReadSession(options)
         session.use { lambda.call(session) }
     }
-
-    /**
-     * The best feature encoding for the given feature.
-     *
-     * - Throws [NakshaError.UNINITIALIZED], if the storage failed to initialize.
-     * @param feature the feature to encode; _null_ if no specific one is available.
-     * @param context the context in which the encoding happens (for example the [map][naksha.model.objects.NakshaCatalog] or [collection][naksha.model.objects.NakshaCollection]); _null_ if none is available.
-     * @return best [DataEncoding] to use.
-     * @since 3.0
-     */
-    @Deprecated("Will be removed in a future release.")
-    fun getDataEncoding(feature: Any?, context: Any? = null): DataEncoding
 }

here-naksha-lib-model/src/commonMain/kotlin/naksha/model/Naksha.kt

@@ -17,6 +17,7 @@ import kotlin.js.JsExport
 import kotlin.js.JsName
 import kotlin.js.JsStatic
 import kotlin.jvm.JvmField
+import kotlin.jvm.JvmOverloads
 import kotlin.jvm.JvmStatic
 
 /**
@@ -140,14 +141,17 @@ class Naksha private constructor() {
          *
          * **Beware**: Identifiers must not contain upper-case letters, because many storages does not make a difference between upper- and lower-cased letters.
          * @param id the identifier.
+         * @param internal if _true_, then extends the allowed character set to `[a-z_][a-z0-9_:-~$]{31}`.
          * @return _true_ if the identifier is valid; _false_ otherwise.
          * @since 3.0
          * @see [verifyId]
+         * @see [verifyInternalId]
          * @see [MAX_ID_LENGTH]
          */
         @JsStatic
         @JvmStatic
-        fun isValidId(id: String?): Boolean {
+        @JvmOverloads
+        fun isValidId(id: String?, internal: Boolean = false): Boolean {
             if (id.isNullOrEmpty() || "naksha" == id || id.length > MAX_ID_LENGTH) return false
             var i = 0
             var c = id[i++]

here-naksha-lib-model/src/commonMain/kotlin/naksha/model/Tuple.kt

@@ -84,7 +84,7 @@ data class Tuple @JvmOverloads constructor(
             globalBook: IBook?
         ): Tuple {
             val members = collection.useMembers()
-            val processors = session.processors()
+            val processors = session.processors
 
             // Update the tuple-number.
             val tnMember = collection.useMember(StandardMembers.Tn)

here-naksha-lib-model/src/commonMain/kotlin/naksha/model/objects/Member.kt

@@ -18,6 +18,8 @@ import naksha.model.TupleNumber
 import kotlin.js.JsExport
 import kotlin.js.JsName
 
+// TODO: We need an immutable version of this, because this actually allows mutation.
+
 /**
  * A materialized part of a feature.
  *
@@ -191,6 +193,12 @@ open class Member() : AnyObject(), Comparator<Member> {
 
     /**
      * Ensures that the given `other` member is the same as this.
+     *
+     * The purpose of the method is generally to do:
+     * ```kotlin
+     * val member = StandardMember.Id.asSame(someCustomMember)
+     * ```
+     * Which will return the given custom member, ensuring that it still is the standard `id` member, but allows different paths.
      * @param other The member to compare this with.
      * @param comparePath If the path must be the same as well, defaults to _false_.
      * @return The `other` member, if it is the same as this.