TreeNode.java
/*
* Copyright 2021 Red Hat, Inc. and/or its affiliates
* and other contributors as indicated by the @author tags.
*
* 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.
*/
package org.keycloak.models.map.storage.tree;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.Predicate;
import java.util.stream.Stream;
/**
* Interface representing a node in a tree that has ID.
* <p>
* Think twice when adding a method here: if added method does not operate purely
* on nodes or a generic tree, it does not belong here.
* @author hmlnarik
*/
public interface TreeNode<Self extends TreeNode<? extends Self>> {
public enum PathOrientation { BOTTOM_FIRST, TOP_FIRST }
/**
* Adds a node as a child of this node, and sets the parent of the {@code node} to this node.
* @param node Future child node. If {@code null} or the node is already amongst the children list, no action is done.
*/
void addChild(Self node);
/**
* Adds a node as a child of this node, and sets the parent of the {@code node} to this node.
* @param index Index at which the specified element is to be inserted
* @param node Future child node. If {@code null} or the node is already amongst the children list, no action is done.
*
*/
void addChild(int index, Self node);
/**
* Returns a node by ID. If there are more nodes with the same ID, any node from those may be returned.
* @param id
* @return
*/
Optional<Self> getChild(String id);
/**
* Returns the children of the current node. Order does matter.
* @return Read-only list of the children. Never returns {@code null}.
*/
List<Self> getChildren();
/**
* Parent-to-this-node edge properties. For example, import/no-import mode or sync mode belongs here.
* @return Returns properties of the edge from the parent to this node. Never returns {@code null}.
*/
Map<String, Object> getEdgeProperties();
/**
* Convenience method for obtaining a single parent-to-this-node edge property.
* @param <V>
* @param key
* @param clazz
* @return {@code Optional} with a property value if it exists. Never returns {@code null}
*/
<V> Optional<V> getEdgeProperty(String key, Class<V> clazz);
/**
* Returns ID of the node, which could match e.g. ID of the component with storage definition.
* @return Node ID
*/
String getId();
/**
* Properties of the this node. In storage context, properties of the single map storage represented by this
* node, for example read-only/read-write flag.
* @return Returns properties of the storage managed in this node. Never returns {@code null}.
*/
Map<String, Object> getNodeProperties();
/**
* Convenience method for obtaining a single property of this node.
* @param <V>
* @param key
* @param clazz
* @return {@code Optional} with a property value if it exists. Never returns {@code null}
*/
<V> Optional<V> getNodeProperty(String key, Class<V> clazz);
/**
* Properties of the whole tree. For example, kind of the stored objects, e.g. realms or clients.
* @return Returns properties of the tree that contains in this node. Never returns {@code null}.
*/
Map<String, Object> getTreeProperties();
/**
* Convenience method for obtaining a single property of tree that this node belongs to.
* @param <V>
* @param key
* @param clazz
* @return {@code Optional} with a property value if it exists. Never returns {@code null}
*/
<V> Optional<V> getTreeProperty(String key, Class<V> clazz);
/**
* Removes the given child node.
* @param node Node to remove
* @return Removed node
*/
Optional<Self> removeChild(Self node);
/**
* Removes child nodes satisfying the given predicate.
* @param node Predicate on node returning {@code true} for each node that should be removed
* @return Number of removed nodes
*/
int removeChild(Predicate<Self> shouldRemove);
/**
* Returns parent node or an empty {@code Optional} if this node is a root node.
* @return See description. Never returns {@code null}.
*/
Optional<Self> getParent();
/**
* Sets the parent node to the given {@code parent}. If this node was a child of another node,
* also removes this node from the children of the previous parent.
* @param parent New parent node or {@code null} if this node should be parentless.
*/
void setParent(Self parent);
/**
* Depth-first search for a node.
* @param visitor Predicate on nodes, returns {@code true} when a search condition is satisfied which terminates the search.
* @return Leftmost first node that matches the predicate, {@code null} when no node matches.
*/
Optional<Self> findFirstDfs(Predicate<Self> visitor);
/**
* Depth-first search for a node that is bottommost from those matching DFS.
* @param visitor Predicate on nodes, returns {@code true} when a search condition is satisfied which terminates the search.
* @return Leftmost and bottommost node that matches the predicate, {@code null} when no node matches.
*/
Optional<Self> findFirstBottommostDfs(Predicate<Self> visitor);
/**
* Breadth-first search for a node.
* @param visitor Predicate on nodes, returns {@code true} when a search condition is satisfied which terminates the search.
* @return First node that matches the predicate, {@code null} when no node matches.
*/
Optional<Self> findFirstBfs(Predicate<Self> visitor);
/**
* Returns the path (list of nodes) from this node to root node.
* @param orientation Determines order of the nodes in the returned list - either this node is first and the root node
* is last, ({@link PathOrientation#BOTTOM_FIRST}) or vice versa ({@link PathOrientation#TOP_FIRST}).
* @return
*/
List<Self> getPathToRoot(PathOrientation orientation);
/**
* Returns a stream of the nodes laying on the path from this node (exclusive) to the root of the tree (inclusive).
* @return
*/
Stream<Self> getParentsStream();
/**
* Calls the given {@code visitor} on each node laying on the path from this node (exclusive) to the root of the tree (inclusive).
* @param visitor
*/
void forEachParent(Consumer<Self> visitor);
/**
* Walks the tree with the given visitor in depth-first search manner.
* @param visitorUponEntry Visitor called upon entry of the node. May be {@code null}, in that case no action is performed.
* @param visitorAfterChildrenVisited Visitor called before exit of the node. May be {@code null}, in that case no action is performed.
*/
void walkDfs(Consumer<Self> visitorUponEntry, Consumer<Self> visitorAfterChildrenVisited);
/**
* Walks the tree with the given visitor in breadth-first search manner.
* @param visitor
*/
void walkBfs(Consumer<Self> visitor);
}