kenhuuu commented on code in PR #3448: URL: https://github.com/apache/tinkerpop/pull/3448#discussion_r3365469053
########## docs/src/upgrade/release-4.x.x.asciidoc: ########## @@ -501,10 +501,49 @@ It cannot be passed to `traversal().with(...)`, and mutating its collections has re-query elements against the original graph, extract their ids and call `g.V(id)` or `g.E(id)` against the original `GraphTraversalSource`. +==== Tree No Longer Extends HashMap + +`Tree` no longer extends `HashMap`. It is now a `final` class that holds a `Map` internally and exposes a +tree-shaped API instead of `Map` methods. This is a breaking change for code that treated a `tree()` result as a +`Map`. + +Replacements for the common `Map`-based access patterns: + +[options="header"] +|======================= +|3.x (`Tree` as `Map`) |4.x (`Tree` API) +|`tree.get(key)` |`tree.childAt(key)` (throws if absent) or `tree.findSubtree(key)` (recursive, returns `Optional`) +|`tree.containsKey(key)` |`tree.hasChild(key)` +|`tree.keySet()` |`tree.rootNodes()` +|`tree.size()` |`tree.rootNodes().size()` for root entries, or `tree.nodeCount()` for total nodes +|`getObjectsAtDepth(d)` |`getNodesAtDepth(d)` (now 0-based: depth 0 returns the roots) +|`getLeafObjects()` |`getLeafNodes()` +|======================= + +A few Gremlin patterns that worked only because `Tree` was a `Map` (for example `select(keys)`, `count(local)`, +and `unfold()` applied to a `Tree`) no longer compose. Process the `Tree` result client-side after `next()`, or +reshape the upstream traversal. The old `count(local)` (which returned the root-node count) is replaced by +`rootNodes().size()` for the root count, or `nodeCount()` for the total node count. + +`isLeaf()` no longer throws on an empty tree (it returns `true`), and a `Tree` keeps the long-standing limitation +that sibling branches resolving to the same value collapse into one node; use `path()` or `subgraph()` when full +path structure must be preserved. + + === Upgrading for Providers ==== Graph System Providers +`Tree` no longer extends `HashMap`. Provider code that inspected or rebuilt a `Tree` via `Map` methods Review Comment: This section assumes that the provider uses the reference deserializers. Providers can technically deserialize the tree bytes into whatever class they want. While this information is good as most providers will probably do that, it should probably more of a heads up to providers that do that they should expect changes. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
