This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch v3
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/v3 by this push:
new 86d747e3ac5 CAUSEWAY-2297: work on simplified tree model (part 6)
86d747e3ac5 is described below
commit 86d747e3ac5e487c22e203fb1b1896556eb5b825
Author: Andi Huber <[email protected]>
AuthorDate: Wed Dec 11 13:02:23 2024 +0100
CAUSEWAY-2297: work on simplified tree model (part 6)
- additional javadoc
---
.../causeway/applib/graph/tree/TreeAdapter.java | 1 +
.../graph/tree/TreeAdapterWithConverter.java | 6 ++
.../causeway/applib/graph/tree/TreeConverter.java | 20 ++++--
.../apache/causeway/applib/graph/tree/Trees.adoc | 77 ++++++++++++++++++++--
.../wicket/ui/components/tree/TreeProvider.java | 3 +-
5 files changed, 94 insertions(+), 13 deletions(-)
diff --git
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapter.java
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapter.java
index 68cb08c971f..db06ace2243 100644
---
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapter.java
+++
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapter.java
@@ -85,6 +85,7 @@ public interface TreeAdapter<T> {
: childNode;
}
+ /** converts this {@code TreeAdapter<T>} to an equivalent {@code
TreeAdapter<R>} */
default <R> TreeAdapter<R> convert(final TreeConverter<T, R> converter) {
return new TreeAdapterWithConverter<T, R>(this, converter);
}
diff --git
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapterWithConverter.java
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapterWithConverter.java
index e5fa6534521..fac1be2759c 100644
---
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapterWithConverter.java
+++
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeAdapterWithConverter.java
@@ -26,6 +26,12 @@ import org.springframework.lang.Nullable;
import org.apache.causeway.commons.functional.IndexedFunction;
+/**
+ * Acts as a TreeAdapter facade by wrapping an underlying {@link TreeAdapter}
+ * and translating the node type back and forth using a {@link TreeConverter}.
+ * @param <U> underlying tree node generic type
+ * @param <T> tree node generic type of this facade
+ */
record TreeAdapterWithConverter<U, T>(
TreeAdapter<U> underlyingAdapter,
TreeConverter<U, T> converter)
diff --git
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeConverter.java
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeConverter.java
index f73b092c6e6..9a46952de2c 100644
---
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeConverter.java
+++
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/TreeConverter.java
@@ -18,9 +18,21 @@
*/
package org.apache.causeway.applib.graph.tree;
+/**
+ * @param <U> underlying tree generic type
+ * @param <T> converted tree generic type
+ */
public interface TreeConverter<U, T> {
-
- public T fromUnderlyingNode(U value, T parentNode, int siblingIndex);
- public U toUnderlyingNode(T value);
-
+
+ /**
+ * Creates a converted node value from the (underlying) node value, also
providing context,
+ * that is, passing in the resulting node's parent-node and the resulting
node's sibling index.
+ */
+ T fromUnderlyingNode(U value, T parentNode, int siblingIndex);
+
+ /**
+ * Recovers the original (underlying) node value from given converted node
value.
+ */
+ U toUnderlyingNode(T value);
+
}
diff --git
a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/Trees.adoc
b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/Trees.adoc
index 52a07bbde69..7d5e96a4c22 100644
--- a/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/Trees.adoc
+++ b/api/applib/src/main/java/org/apache/causeway/applib/graph/tree/Trees.adoc
@@ -11,6 +11,20 @@ Their purpose is rather to document diagrams and design
decisions close to the r
And also for code authors to quickly get an overview or refresher on the
topic.
****
+== TreeAdapter
+
+A `TreeAdapter` provides the parent/child relationship information between
pojos to derive a tree-structure.
+
+[NOTE]
+====
+The model deliberately does *not* reflect a doubly linked tree, that is,
+we don't directly provide a link from a node to its parent node.
+(To define a tree, parent references are not strictly required.)
+
+For tree data structures in general, referencing parents would introduce
circular references,
+which don't play well with immutable data structures or serialization.
+====
+
[plantuml,fig-TreeModel-1,svg]
.Tree Model
----
@@ -20,6 +34,7 @@ interface TreeAdapter<T> {
childCountOf(T): int
childrenOf(T): Stream<T>
resolveRelative(T, TreePath): Optional<T>
+ convert(TreeConverter<T, R>): TreeAdapter<R>
}
interface TreeConverter<U, T> {
@@ -27,19 +42,67 @@ interface TreeConverter<U, T> {
toUnderlyingNode(T value): U
}
-class TreeAdapterWithConverter<U, T> << (R,#FF7700) record >>{
+class TreeAdapterWithConverter<U, T> << (R,#FF7700) internal >>{
underlyingAdapter(): TreeAdapter<U>
converter(): TreeConverter<U, T>
}
-TreeAdapterWithConverter -|> TreeAdapter
+TreeAdapter <|- TreeAdapterWithConverter: facade
+TreeAdapter ..> TreeConverter: uses for conversion
@enduml
----
-== TreeAdapter
+The internal `TreeAdapterWithConverter` acts as a `TreeAdapter` facade by
wrapping an underlying `TreeAdapter`
+and translating the node type back and forth using a `TreeConverter`.
+
+== TreeProvider (Wicket Viewer)
+
+`TreeAdapterRecord` is Wicket's `ITreeProvider` implemented for a tree of
`TreeNodeMemento`(s).
+
+[plantuml,fig-TreeModel-2,svg]
+.Tree Provider (Wicket Viewer)
+----
+@startuml
+
+class TreeNodeMemento << (R,#FF7700) serializable >>{
+ bookmark: Bookmark
+ treePath: TreePath
+}
-provides the parent/child relationship information between pojos to derive a
tree-structure.
-It is deliberately *not* modeled as a doubly linked tree, that is,
-we don't directly provide a link from a node to its parent node, as this would
introduce circular references,
-which don't play well with immutable data structures or serialization.
\ No newline at end of file
+class TreeAdapterRecord<T> << (R,#FF7700) serializable>>{
+ treeAdapter: TreeAdapter
+}
+
+class TreeProvider << (R,#FF7700) serializable>>{
+}
+
+TreeProvider --> TreeNodeMemento: primaryValue
+TreeProvider --> TreeAdapterRecord: treeAdapterRecord
+
+@enduml
+----
+
+Only constraint for the tree node values is that those need to be
_bookmarkable_.
+The `TreeProvider` is then simply made of 2 parts:
+
+ . the root node (in its serializable form)
+ . the TreeAdapter (wrapped in a serializable container)
+
+The fact that `TreeProvider` also implements `TreeConverter` is just an
implementation detail.
+
+[source,java]
+----
+record TreeProvider(
+ /** tree's single root */
+ TreeNodeMemento primaryValue,
+ TreeAdapterRecord<Object> treeAdapterRecord)
+implements
+ ITreeProvider<TreeNodeMemento>,
+ TreeConverter<Object, TreeNodeMemento> {
+ //..
+}
+----
+
+
+
diff --git
a/viewers/wicket/ui/src/main/java/org/apache/causeway/viewer/wicket/ui/components/tree/TreeProvider.java
b/viewers/wicket/ui/src/main/java/org/apache/causeway/viewer/wicket/ui/components/tree/TreeProvider.java
index 8c13ad05348..84cd3e46709 100644
---
a/viewers/wicket/ui/src/main/java/org/apache/causeway/viewer/wicket/ui/components/tree/TreeProvider.java
+++
b/viewers/wicket/ui/src/main/java/org/apache/causeway/viewer/wicket/ui/components/tree/TreeProvider.java
@@ -35,7 +35,7 @@ import
org.apache.causeway.core.metamodel.tree.TreeAdapterRecord;
import org.apache.causeway.core.metamodel.tree.TreeNodeMemento;
/**
- * Wicket's {@link ITreeProvider} implemented for Causeway.
+ * Wicket's {@link ITreeProvider} implemented for a tree of {@link
TreeNodeMemento}.
*/
record TreeProvider(
/** tree's single root */
@@ -101,5 +101,4 @@ implements
private TreeAdapter<TreeNodeMemento> treeAdapter() {
return treeAdapterRecord.treeAdapter().convert(this);
}
-
}
\ No newline at end of file
