feat(model-api): INode.addNewChildren with better performance for bulk imports

It can create multiple children at the same time, allowing the copy-on-write
implementation to update the parent node only once instead of creating
a new version of the node for each added child.

Author: slisson

bulk-model-sync-lib/src/commonMain/kotlin/org/modelix/model/sync/bulk/ModelImporter.kt

@@ -122,6 +122,17 @@ class ModelImporter(private val root: INode, private val continueOnError: Boolea
             val expectedNodes = data.children.filter { it.role == role }
             val existingNodes = node.getChildren(role).toList()
 
+            // optimization that uses the bulk operation .addNewChildren
+            if (existingNodes.isEmpty() && expectedNodes.all { originalIdToExisting[it.originalId()] == null }) {
+                node.addNewChildren(role, -1, expectedNodes.map { it.concept?.let { ConceptReference(it) } }).zip(expectedNodes).forEach { (newChild, expected) ->
+                    val expectedId = checkNotNull(expected.originalId()) { "Specified node '$expected' has no id" }
+                    newChild.setPropertyValue(NodeData.idPropertyKey, expectedId)
+                    originalIdToExisting[expectedId] = newChild
+                    syncNode(newChild, expected)
+                }
+                continue
+            }
+
             // optimization for when there is no change in the child list
             // size check first to avoid querying the original ID
             if (expectedNodes.size == existingNodes.size && expectedNodes.map { it.originalId() } == existingNodes.map { it.originalId() }) {

model-api/src/commonMain/kotlin/org/modelix/model/api/INode.kt

@@ -117,6 +117,10 @@ interface INode {
         return addNewChild(role, index, concept?.resolve())
     }
 
+    fun addNewChildren(role: String?, index: Int, concepts: List<IConceptReference?>): List<INode> {
+        return concepts.map { addNewChild(role, index, it) }
+    }
+
     /**
      * Removes the given node from this node's children.
      *

model-api/src/commonMain/kotlin/org/modelix/model/api/IWriteTransaction.kt

@@ -102,6 +102,9 @@ interface IWriteTransaction : ITransaction {
      */
     fun addNewChild(parentId: Long, role: String?, index: Int, childId: Long, concept: IConceptReference?)
 
+    fun addNewChildren(parentId: Long, role: String?, index: Int, concepts: Array<IConceptReference?>): LongArray
+    fun addNewChildren(parentId: Long, role: String?, index: Int, childIds: LongArray, concepts: Array<IConceptReference?>)
+
     /**
      * Deletes the given node.
      *

model-api/src/commonMain/kotlin/org/modelix/model/api/PNodeAdapter.kt

@@ -68,6 +68,12 @@ open class PNodeAdapter(val nodeId: Long, val branch: IBranch) : INode, INodeEx
         return PNodeAdapter(branch.writeTransaction.addNewChild(nodeId, role, index, concept), branch)
     }
 
+    override fun addNewChildren(role: String?, index: Int, concepts: List<IConceptReference?>): List<INode> {
+        return branch.writeTransaction.addNewChildren(nodeId, role, index, concepts.toTypedArray()).map {
+            PNodeAdapter(it, branch)
+        }
+    }
+
     override fun addNewChild(role: IChildLink, index: Int, concept: IConcept?): INode {
         return PNodeAdapter(branch.writeTransaction.addNewChild(nodeId, role.key(this), index, concept), branch)
     }

model-api/src/commonMain/kotlin/org/modelix/model/api/PNodeReference.kt

@@ -27,9 +27,47 @@ data class PNodeReference(val id: Long, val branchId: String) : INodeReference {
 
     fun toLocal() = LocalPNodeReference(id)
 
+    override fun serialize(): String {
+        return "${id.toString(16)}@$branchId"
+    }
+
     override fun toString(): String {
         return "PNodeReference_${id.toString(16)}@$branchId"
     }
+
+    companion object {
+        fun deserialize(serialized: String): PNodeReference {
+            return requireNotNull(tryDeserialize(serialized)) {
+                "Not a valid PNodeReference: $serialized"
+            }
+        }
+        fun tryDeserialize(serialized: String): PNodeReference? {
+            if (serialized.startsWith("pnode:") && serialized.contains('@')) {
+                val withoutPrefix = serialized.substringAfter("pnode:")
+                val parts = withoutPrefix.split('@', limit = 2)
+                if (parts.size != 2) return null
+                val nodeId = parts[0].toLongOrNull(16) ?: return null
+                return PNodeReference(nodeId, parts[1])
+            } else if (serialized.startsWith("modelix:") && serialized.contains('/')) {
+                // This would be a nicer serialization format that isn't used yet, but supporting it already will make
+                // future changes easier without breaking old versions of this library.
+                //
+                // Example:    modelix:25038f9e-e8ad-470a-9ae8-6978ed172184/1a5003b818f
+                // Old format: pnode:1a5003b818f@25038f9e-e8ad-470a-9ae8-6978ed172184
+                //
+                // The 'modelix' prefix is more intuitive for a node stored inside a Modelix repository.
+                // Having the repository ID first also feels more natural.
+                val withoutPrefix = serialized.substringAfter("modelix:")
+                val nodeIdStr = withoutPrefix.substringAfterLast('/')
+                val branchId = withoutPrefix.substringBeforeLast('/')
+                val nodeId = nodeIdStr.toLongOrNull(16)
+                if (nodeId != null && branchId.isNotEmpty()) {
+                    return PNodeReference(nodeId, branchId)
+                }
+            }
+            return null
+        }
+    }
 }
 
 object PNodeReferenceSerializer : INodeReferenceSerializerEx {

model-api/src/commonMain/kotlin/org/modelix/model/api/TreePointer.kt

@@ -117,6 +117,27 @@ class TreePointer(private var tree_: ITree, val idGenerator: IIdGenerator = IdGe
         tree = tree.addNewChild(parentId, role, index, childId, concept)
     }
 
+    override fun addNewChildren(
+        parentId: Long,
+        role: String?,
+        index: Int,
+        concepts: Array<IConceptReference?>,
+    ): LongArray {
+        val newIds = concepts.map { idGenerator.generate() }.toLongArray()
+        addNewChildren(parentId, role, index, newIds, concepts)
+        return newIds
+    }
+
+    override fun addNewChildren(
+        parentId: Long,
+        role: String?,
+        index: Int,
+        childIds: LongArray,
+        concepts: Array<IConceptReference?>,
+    ) {
+        tree = tree.addNewChildren(parentId, role, index, childIds, concepts)
+    }
+
     override fun deleteNode(nodeId: Long) {
         tree = tree.deleteNode(nodeId)
     }

model-api/src/commonMain/kotlin/org/modelix/model/api/WriteTransaction.kt

@@ -79,6 +79,18 @@ class WriteTransaction(_tree: ITree, branch: IBranch, idGenerator: IIdGenerator)
         tree = tree.addNewChild(parentId, role, index, childId, concept)
     }
 
+    override fun addNewChildren(parentId: Long, role: String?, index: Int, childIds: LongArray, concepts: Array<IConceptReference?>) {
+        checkNotClosed()
+        tree = tree.addNewChildren(parentId, role, index, childIds, concepts)
+    }
+
+    override fun addNewChildren(parentId: Long, role: String?, index: Int, concepts: Array<IConceptReference?>): LongArray {
+        checkNotClosed()
+        val newIds = concepts.map { idGenerator.generate() }.toLongArray()
+        addNewChildren(parentId, role, index, newIds, concepts)
+        return newIds
+    }
+
     override fun deleteNode(nodeId: Long) {
         checkNotClosed()
         tree.getAllChildren(nodeId).forEach { deleteNode(it) }

model-api/src/commonTest/kotlin/ReferenceSerializationTests.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2023.
+ *
+ * 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
+ *
+ * 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.
+ */
+
+import org.modelix.model.api.PNodeReference
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class ReferenceSerializationTests {
+
+    @Test
+    fun deserializePNodeReferenceOldFormat() {
+        assertEquals(
+            PNodeReference(0xabcd1234, "2bfd9f5e-95d0-11ee-b9d1-0242ac120002"),
+            PNodeReference.deserialize("pnode:abcd1234@2bfd9f5e-95d0-11ee-b9d1-0242ac120002"),
+        )
+    }
+
+    @Test
+    fun deserializePNodeReferenceNewFormat() {
+        assertEquals(
+            PNodeReference(0xabcd1234, "2bfd9f5e-95d0-11ee-b9d1-0242ac120002"),
+            PNodeReference.deserialize("modelix:2bfd9f5e-95d0-11ee-b9d1-0242ac120002/abcd1234"),
+        )
+    }
+}

model-client/src/commonMain/kotlin/org/modelix/model/AutoTransactionsBranch.kt

@@ -69,6 +69,10 @@ class AutoWriteTransaction(branch: IBranch) : AutoTransaction(branch), IWriteTra
         branch.computeWriteT { it.addNewChild(parentId, role, index, concept) }
     override fun addNewChild(parentId: Long, role: String?, index: Int, childId: Long, concept: IConcept?) =
         branch.computeWriteT { it.addNewChild(parentId, role, index, childId, concept) }
+    override fun addNewChildren(parentId: Long, role: String?, index: Int, concepts: Array<IConceptReference?>) =
+        branch.computeWriteT { it.addNewChildren(parentId, role, index, concepts) }
+    override fun addNewChildren(parentId: Long, role: String?, index: Int, childIds: LongArray, concepts: Array<IConceptReference?>) =
+        branch.computeWriteT { it.addNewChildren(parentId, role, index, childIds, concepts) }
     override fun addNewChild(
         parentId: Long,
         role: String?,

model-client/src/commonMain/kotlin/org/modelix/model/IncrementalBranch.kt

@@ -280,6 +280,34 @@ class IncrementalBranch(val branch: IBranch) : IBranch, IBranchWrapper {
             return childId
         }
 
+        override fun addNewChildren(
+            parentId: Long,
+            role: String?,
+            index: Int,
+            concepts: Array<IConceptReference?>,
+        ): LongArray {
+            val childIds = transaction.addNewChildren(parentId, role, index, concepts)
+            modified(ChildrenDependency(this@IncrementalBranch, parentId, role))
+            childIds.forEach {
+                modified(UnclassifiedNodeDependency(this@IncrementalBranch, it)) // see .containsNode
+            }
+            return childIds
+        }
+
+        override fun addNewChildren(
+            parentId: Long,
+            role: String?,
+            index: Int,
+            childIds: LongArray,
+            concepts: Array<IConceptReference?>,
+        ) {
+            transaction.addNewChildren(parentId, role, index, childIds, concepts)
+            modified(ChildrenDependency(this@IncrementalBranch, parentId, role))
+            childIds.forEach {
+                modified(UnclassifiedNodeDependency(this@IncrementalBranch, it)) // see .containsNode
+            }
+        }
+
         override fun addNewChild(parentId: Long, role: String?, index: Int, childId: Long, concept: IConcept?) {
             transaction.addNewChild(parentId, role, index, childId, concept)
             modified(ChildrenDependency(this@IncrementalBranch, parentId, role))