Events in delta API

bulk/repo-access-api.adoc

@@ -10,7 +10,7 @@ include::../shared/issue-footnotes.adoc[]
 :toc: preamble
 :toclevels: 2
 
-The bulk API *version 2024.1* is used to store and retrieve nodes in batches at the moment of invocation.{fn-org25}
+The bulk API *version 2025.1* is used to store and retrieve nodes in batches at the moment of invocation.{fn-org25}
 It is intended for CRUD operations on (larger) sets of nodes.
 it is *not* intended as a delta-oriented API that takes "modification commands" as arguments.
 
@@ -87,7 +87,7 @@ A repository also MAY disallow re-using previously deleted node ids.
 [[client-ids]]
 == Client ids
 Each <<{arch}.adoc#client, client>> MUST  provide a unique _client id_ when connecting to the repository.{fn-org241}
-The client id is an <<{serialization}.adoc#id, id>>-compatible string.
+The client id is an <<{m3}.adoc#identifiers, identifier>>-compatible string.
 A client MAY connect more than once to the same repository at the same time with the same client id.
 It is out of scope of LionWeb to guarantee the uniqueness of the client id.
 The repository does not apply any uniqueness checks.
@@ -181,12 +181,12 @@ We call this part of the reponse [[Response.success]]`success` flag.
 Besides the main response, the repository can reply each command with zero or more additional [[Response.messages]]`messages`.{fn-org236}
 Each message MUST have the following properties:
 
-* [[message.kind]]`kind` is an <<{serialization}.adoc#id, id>>-compatible string identifying the message type.
+* [[message.kind]]`kind` is an <<{m3}.adoc#identifiers, identifier>>-compatible string identifying the message type.
 Some message kinds are pre-defined in this specification.
 A repository MAY reply with other, additional message kinds.
 * [[message.message]]`message` is a human-readable string describing the message.
 * [[message.data]]`data` is a flat map with arbitrary keys and values.
-All values MUST be strings, the keys MUST be <<{serialization}.adoc#id, id>>-compatible.
+All values MUST be strings, the keys MUST be <<{m3}.adoc#identifiers, identifier>>-compatible.
 A _kind_ might imply presence of specific keys in `data`.
 
 [[message-kinds-global]]
@@ -220,6 +220,11 @@ A _kind_ might imply presence of specific keys in `data`.
 [[apis]]
 == Commands
 
+Each _modifying_ command MUST contain a _[[commandId, commmand id]]command id_.{fn-org313}
+It has the same format as <<{m3}.adoc#identifiers, node ids>> and must be unique for all changes of this client.
+
+Modifying commands are <<createPartitions>>, <<deletePartitions>>, and <<store>>.
+
 [[listPartitions, listPartitions]]
 [[partitions, listPartitions]]
 === listPartitions: List available partitions
@@ -254,6 +259,8 @@ Nodes MUST use <<unknown-node-ids>>.
 ==== Parameters
 [[createPartitions.nodes]]
 `nodes`:: {chunk} containing all nodes we want to add as new partitions.
+[[createPartitions.commandId]]
+`commandId`:: <<commandId>> of this command.
 
 ==== Response
 Does not contain a `chunk`.
@@ -308,6 +315,8 @@ All (transitive) annotations and children become <<orphan, orphans>>.
 ==== Parameters:
 [[deletePartitions.nodeIds]]
 `nodeIds`:: List of node ids to delete.
+[[deletePartitions.commandId]]
+`commandId`:: <<commandId>> of this command.
 
 ==== Response
 Does not contain a chunk.
@@ -417,6 +426,8 @@ We do not support different modes.{fn-org230}
 ==== Parameters
 [[store.nodes]]
 `nodes`:: {chunk} containing all nodes to store to the repository.
+[[store.commandId]]
+`commandId`:: <<commandId>> of this command.
 
 ==== Semantics
 After completing this call, all sent nodes MUST have exactly the sent contents in the repository.

delta/commandEventOverview/addAnnotation.adoc

@@ -0,0 +1,37 @@
+|
+[plantuml, addAnnotation-before, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class "previous\nSibling" as previousSibling
+class " " as dummy <<h>>
+class "next\nSibling" as nextSibling
+
+parent *--> previousSibling: <<annotations>>\n[index - 1]
+parent *-[hidden]-> dummy #Blue: <<annotations>>\n[index]
+parent *--> nextSibling: <<annotations>>\n[index]
+----
+|
+[plantuml,addAnnotation-after,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class "previous\nSibling" as previousSibling
+class "newAnnotation:\nRemark" as newAnnotation #LightSkyBlue {
+  text:String="ok"
+}
+class "next\nSibling" as nextSibling
+
+class descendant #LightSkyBlue
+
+parent *--> previousSibling: <<annotations>>\n[index - 1]
+parent *--> newAnnotation #Blue: <<annotations>>\n[index]
+parent *--> nextSibling: <<annotations>>\n[index + 1]
+
+newAnnotation *--> descendant #Blue
+previousSibling <.. descendant #Blue
+----

delta/commandEventOverview/addChild.adoc

@@ -0,0 +1,37 @@
+|
+[plantuml, addChild-before, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class "previous\nSibling" as previousSibling
+class " " as newChild<<h>>
+class "next\nSibling" as nextSibling
+
+parent *--> previousSibling: containment\n[index - 1]
+parent *-[hidden]-> newChild #Blue: containment\n[index]
+parent *--> nextSibling: containment\n[index]
+----
+|
+[plantuml, addChild-after, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class "previous\nSibling" as previousSibling
+class "newChild:Car" as newChild #LightSkyBlue {
+  length:Integer=19
+}
+class "next\nSibling" as nextSibling
+
+class descendant #LightSkyBlue
+
+parent *--> previousSibling: containment\n[index - 1]
+parent *--> newChild #Blue: containment\n[index]
+parent *--> nextSibling: containment\n[index + 1]
+
+newChild *--> descendant #Blue
+previousSibling <.. descendant #Blue
+----

delta/commandEventOverview/addPartition.adoc

@@ -0,0 +1,13 @@
+|
+_nothing_
+|
+[plantuml, addPartition, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class newPartition:Person <<Partition>> #LightSkyBlue {
+  name: String = "John"
+  age: Integer = 23
+  alive: Boolean = true
+}
+----

delta/commandEventOverview/addProperty.adoc

@@ -0,0 +1,17 @@
+|
+[plantuml, addProperty-before, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class "node"
+----
+|
+[plantuml, addProperty-after, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class "node" {
+  <color: #blue>property = newValue</color>
+}
+----
+

delta/commandEventOverview/addReference.adoc

@@ -0,0 +1,30 @@
+|
+[plantuml,addReference-before,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class "previous\nEntry" as previousEntry
+class newTarget
+class "next\nEntry" as nextEntry
+
+parent ..> previousEntry: reference\n[index - 1]
+parent .[hidden].> newTarget #Blue: reference\n[index]
+parent ..> nextEntry: reference\n[index]
+----
+|
+[plantuml,addReference-after,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class "previous\nEntry" as previousEntry
+class newTarget
+class "next\nEntry" as nextEntry
+
+parent ..> previousEntry: reference\n[index - 1]
+parent .[thickness=2].> newTarget #Blue: reference\n[index]\n<color #blue>{new</color>\n<color #blue>ResolveInfo}</color>
+parent ..> nextEntry: reference\n[index + 1]
+----

delta/commandEventOverview/addReferenceResolveInfo.adoc

@@ -0,0 +1,22 @@
+|
+[plantuml,addReferenceResolveInfo-before,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class target
+
+parent ..> target: reference\n[index]\n<color #red>{null}</color>
+----
+|
+[plantuml,addReferenceResolveInfo-after,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class target
+
+parent ..> target: reference\n[index]\n<color #blue>{newResolveInfo}</color>
+----

delta/commandEventOverview/addReferenceTarget.adoc

@@ -0,0 +1,24 @@
+|
+[plantuml,addReferenceTarget-before,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class " " as target<<h>>
+class newTarget
+
+parent ..> target: reference\n[index]\n{resolveInfo}
+target -[hidden]-> newTarget
+----
+|
+[plantuml,addReferenceTarget-after,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class newTarget
+
+parent .[thickness=2].> newTarget #blue: reference\n[index]\n{resolveInfo}
+----

delta/commandEventOverview/changeClassifier.adoc

@@ -0,0 +1,14 @@
+|
+[plantuml, changeClassifier-before, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class "node:<color #red>oldClassifier</color>"
+----
+|
+[plantuml, changeClassifier-after, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class "node:<color #blue>newClassifier</color>"
+----

delta/commandEventOverview/changeProperty.adoc

@@ -0,0 +1,18 @@
+|
+[plantuml, changeProperty-before, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class "node" {
+  property = <color #red>oldValue</color>
+}
+----
+|
+[plantuml, changeProperty-after, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class "node" {
+  property = <color #blue>newValue</color>
+}
+----

delta/commandEventOverview/changeReference.adoc

@@ -0,0 +1,40 @@
+|
+[plantuml,changeReference-before,svg]
+----
+!include commandEventOverviewStyle.puml
+left to right direction
+
+class parent
+
+class "previous\nEntry" as previousEntry
+class "replaced\nTarget" as replacedTarget
+class "new\nTarget" as newTarget
+class "next\nEntry" as nextEntry
+
+parent ..> previousEntry: reference\n[index - 1]
+parent .[thickness=2].> replacedTarget #red: reference\n[index]\n<color #red>{replaced</color>\n<color #red>ResolveInfo}</color>
+parent .[hidden].> newTarget: reference\n[index]\n{new\nResolveInfo}
+parent ..> nextEntry: reference\n[index + 1]
+
+previousEntry -[hidden]> replacedTarget
+----
+|
+[plantuml, changeReference-after, svg]
+----
+!include commandEventOverviewStyle.puml
+left to right direction
+
+class parent
+
+class "previous\nEntry" as previousEntry
+class "replaced\nTarget" as replacedTarget
+class "new\nTarget" as newTarget
+class "next\nEntry" as nextEntry
+
+parent ..> previousEntry: reference\n[index - 1]
+parent .[hidden].> replacedTarget #red: reference\n[index]\n<color #red>{replaced</color>\n<color #red>ResolveInfo}</color>
+parent .[thickness=2].> newTarget #blue: reference\n[index]\n<color #blue>{new</color>\n<color #blue>ResolveInfo}</color>
+parent ..> nextEntry: reference\n[index + 1]
+
+previousEntry -[hidden]> replacedTarget
+----

delta/commandEventOverview/changeReferenceResolveInfo.adoc

@@ -0,0 +1,22 @@
+|
+[plantuml,changeReferenceResolveInfo-before,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class target
+
+parent ..> target: reference\n[index]\n<color #red>{oldResolveInfo}</color>
+----
+|
+[plantuml, changeReferenceResolveInfo-after, svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class target
+
+parent ..> target: reference\n[index]\n<color #blue>{newResolveInfo}</color>
+----

delta/commandEventOverview/changeReferenceTarget.adoc

@@ -0,0 +1,26 @@
+|
+[plantuml,changeReferenceTarget-before,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class oldTarget
+class newTarget
+
+parent .[thickness=2].> oldTarget #red: reference\n[index]\n{resolveInfo}
+parent .[hidden].> newTarget
+----
+|
+[plantuml,changeReferenceTarget-after,svg]
+----
+!include commandEventOverviewStyle.puml
+
+class parent
+
+class oldTarget
+class newTarget
+
+parent .[hidden].> oldTarget
+parent .[thickness=2].> newTarget #blue: reference\n[index]\n{resolveInfo}
+----