Undeprecate Traversal API ()

Co-authored-by: Gemma Lamont<gemma.lamont@neotechnology.com>
Co-authored-by: Nadja Müller <nadja.muller@neotechnology.com>

community/graphdb-api/src/main/java/org/neo4j/graphdb/PathExpanderBuilder.java

@@ -21,6 +21,7 @@ package org.neo4j.graphdb;
 
 import java.util.function.Predicate;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.impl.OrderedByTypeExpander;
 import org.neo4j.graphdb.impl.StandardExpander;
 
@@ -31,6 +32,7 @@ import static org.neo4j.graphdb.Direction.BOTH;
  * <p>
  * See {@link PathExpanders} for a catalog of common expanders.
  */
+@PublicApi
 public class PathExpanderBuilder
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/PathExpanders.java

@@ -22,6 +22,7 @@ package org.neo4j.graphdb;
 import java.io.PrintStream;
 import java.util.function.BiFunction;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.impl.StandardExpander;
 import org.neo4j.graphdb.traversal.BranchState;
 import org.neo4j.graphdb.traversal.Paths;
@@ -31,6 +32,7 @@ import org.neo4j.graphdb.traversal.Paths;
  * <p>
  * Use {@link PathExpanderBuilder} to build specialized {@link PathExpander}s.
  */
+@PublicApi
 public abstract class PathExpanders
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/Transaction.java

@@ -121,18 +121,14 @@ public interface Transaction extends AutoCloseable
      * Factory method for bidirectional traversal descriptions.
      *
      * @return a new {@link BidirectionalTraversalDescription}
-     * @deprecated Not part of public API, can be removed at any moment
      */
-    @Deprecated
     BidirectionalTraversalDescription bidirectionalTraversalDescription();
 
     /**
      * Factory method for unidirectional traversal descriptions.
      *
-     * @deprecated Not part of public API, can be removed at any moment
      * @return a new {@link TraversalDescription}
      */
-    @Deprecated
     TraversalDescription traversalDescription();
 
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BidirectionalTraversalDescription.java

@@ -19,6 +19,7 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Node;
 import org.neo4j.graphdb.Path;
 
@@ -37,6 +38,7 @@ import org.neo4j.graphdb.Path;
  *
  * @see TraversalDescription
  */
+@PublicApi
 public interface BidirectionalTraversalDescription
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BranchCollisionDetector.java

@@ -19,6 +19,7 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Direction;
 import org.neo4j.graphdb.Path;
 
@@ -27,6 +28,7 @@ import org.neo4j.graphdb.Path;
  * they will probably meet somewhere in the middle and the full paths are formed.
  * This is where that detection and path generation takes place.
  */
+@PublicApi
 public interface BranchCollisionDetector
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BranchCollisionPolicies.java

@@ -21,17 +21,21 @@ package org.neo4j.graphdb.traversal;
 
 import java.util.function.Predicate;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Path;
 import org.neo4j.graphdb.impl.traversal.ShortestPathsBranchCollisionDetector;
 import org.neo4j.graphdb.impl.traversal.StandardBranchCollisionDetector;
 
 /**
- * A catalogue of convenient branch collision policies
- *
- * Copied from kernel package so that we can hide kernel from the public API.
+ * A catalogue of convenient branch collision policies, see {@link BranchCollisionPolicy}
  */
+@PublicApi
 public enum BranchCollisionPolicies implements BranchCollisionPolicy
 {
+    /**
+     * This branch collision policy includes all combined paths where the traversers collide, which means that the end node of the startSide and endSide
+     * traverser paths is identical and filters the resulting paths by applying the evaluator and path predicate.
+     */
     STANDARD
     {
         @Override
@@ -40,6 +44,10 @@ public enum BranchCollisionPolicies implements BranchCollisionPolicy
             return new StandardBranchCollisionDetector( evaluator, pathPredicate );
         }
     },
+    /**
+     * This branch collision policy includes only the shortest paths where the traversers collide, which means that the end node of the
+     * startSide and endSide traverser paths is identical and filters the resulting paths by applying the evaluator and path predicate.
+     */
     SHORTEST_PATH
     {
         @Override

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BranchCollisionPolicy.java

@@ -20,12 +20,17 @@
 package org.neo4j.graphdb.traversal;
 
 import java.util.function.Predicate;
+import org.neo4j.annotations.api.PublicApi;
 
 import org.neo4j.graphdb.Path;
 
 /**
- * Copied from kernel package so that we can hide kernel from the public API.
+ * A `BranchCollisionPolicy` defines when a collision is detected and accepted in a bidirectional traversal, see {@link BidirectionalTraversalDescription}.
+ *
+ * Given an evaluator and a path predicate, a `BranchCollisionPolicy` will create a `BranchCollisionDetector`, which will detect collisions between two
+ * traversers and use the `Evaluator` and `Path` predicate to decide whether the resulting path will be included in the result.
  */
+@PublicApi
 public interface BranchCollisionPolicy
 {
     BranchCollisionDetector create( Evaluator evaluator, Predicate<Path> pathPredicate );

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BranchOrderingPolicies.java

@@ -19,15 +19,20 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.PathExpander;
 
 /**
  * A catalog of convenient branch ordering policies.
- *
- * Copied from kernel package so that we can hide kernel from the public API.
  */
+@PublicApi
 public enum BranchOrderingPolicies implements BranchOrderingPolicy
 {
+    /**
+     * This `BranchOrderingPolicy` traverses depth first, visiting the current node, then recursively traversing
+     * depth first the current nodes left subtree, before the right subtree. The pre-order traversal is topologically sorted
+     * as parent nodes are processed before any of its child nodes are done.
+     */
     PREORDER_DEPTH_FIRST
     {
         @Override
@@ -36,6 +41,11 @@ public enum BranchOrderingPolicies implements BranchOrderingPolicy
             return new PreorderDepthFirstSelector( startSource, expander );
         }
     },
+
+    /**
+     * This `BranchOrderingPolicy` traverses depth first, recursively traversing down the current nodes left subtree,
+     * then the right subtree before visiting the current node.
+     */
     POSTORDER_DEPTH_FIRST
     {
         @Override
@@ -44,6 +54,11 @@ public enum BranchOrderingPolicies implements BranchOrderingPolicy
             return new PostorderDepthFirstSelector( startSource, expander );
         }
     },
+
+    /**
+     * This `BranchOrderingPolicy` traverses breadth first, visiting first the current node, then each of its children,
+     * before continuing to their children and so forth. Providing a level order search.
+     */
     PREORDER_BREADTH_FIRST
     {
         @Override
@@ -52,6 +67,11 @@ public enum BranchOrderingPolicies implements BranchOrderingPolicy
             return new PreorderBreadthFirstSelector( startSource, expander );
         }
     },
+
+    /**
+     * This `BranchOrderingPolicy` traverses breadth first, visiting all the leaf nodes of the current node before
+     * visiting their parents. Effectively searching nodes in a reversed level order search to {@link PREORDER_BREADTH_FIRST}
+     */
     POSTORDER_BREADTH_FIRST
     {
         @Override

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BranchOrderingPolicy.java

@@ -19,12 +19,14 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.PathExpander;
 
 /**
  * Creator of {@link BranchSelector} instances with a starting point to base
  * the first decision on.
  */
+@PublicApi
 public interface BranchOrderingPolicy
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/BranchSelector.java

@@ -19,12 +19,15 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
+
 /**
  * Decides "where to go next" in a traversal. It keeps state itself, f.ex. its
  * own current position. Examples of implementations are "depth first" and
  * "breadth first". This is an interface to implement if you'd like to implement
  * f.ex. a "best first" selector based on your own criteria.
  */
+@PublicApi
 public interface BranchSelector
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/Evaluation.java

@@ -19,6 +19,8 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
+
 /**
  * Outcome of {@link Evaluator#evaluate(org.neo4j.graphdb.Path)}. An evaluation
  * can tell the traversal whether or not to continue down that
@@ -27,6 +29,7 @@ package org.neo4j.graphdb.traversal;
  *
  * @see Evaluator
  */
+@PublicApi
 public enum Evaluation
 {
     INCLUDE_AND_CONTINUE( true, true ),

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/Evaluator.java

@@ -19,6 +19,7 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Path;
 
 /**
@@ -32,6 +33,7 @@ import org.neo4j.graphdb.Path;
  * @see Evaluators
  * @see TraversalDescription#evaluator(Evaluator)
  */
+@PublicApi
 public interface Evaluator
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/Evaluators.java

@@ -22,6 +22,7 @@ package org.neo4j.graphdb.traversal;
 import java.util.HashSet;
 import java.util.Set;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Node;
 import org.neo4j.graphdb.Path;
 import org.neo4j.graphdb.Relationship;
@@ -36,6 +37,7 @@ import static org.neo4j.graphdb.traversal.Evaluation.INCLUDE_AND_CONTINUE;
  * @see Evaluator
  * @see TraversalDescription
  */
+@PublicApi
 public abstract class Evaluators
 {
     @SuppressWarnings( "rawtypes" )

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/InitialBranchState.java

@@ -19,6 +19,7 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Path;
 import org.neo4j.graphdb.PathExpander;
 
@@ -27,6 +28,7 @@ import org.neo4j.graphdb.PathExpander;
  *
  * @param <STATE> type of initial state to produce.
  */
+@PublicApi
 public interface InitialBranchState<STATE>
 {
     InitialBranchState<Object> NO_STATE = path -> null;

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/PathEvaluator.java

@@ -19,6 +19,7 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Path;
 
 /**
@@ -33,6 +34,7 @@ import org.neo4j.graphdb.Path;
  * @see Evaluators
  * @see TraversalDescription#evaluator(PathEvaluator)
  */
+@PublicApi
 public interface PathEvaluator<STATE> extends Evaluator
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/Paths.java

@@ -23,6 +23,7 @@ import java.util.Arrays;
 import java.util.Collections;
 import java.util.Iterator;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.DatabaseShutdownException;
 import org.neo4j.graphdb.Direction;
 import org.neo4j.graphdb.Entity;
@@ -34,6 +35,7 @@ import org.neo4j.graphdb.Relationship;
 /**
  * Utilities for {@link org.neo4j.graphdb.Path} objects.
  */
+@PublicApi
 public class Paths
 {
 

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/SideSelector.java

@@ -19,6 +19,7 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
 import org.neo4j.graphdb.Direction;
 
 /**
@@ -26,6 +27,7 @@ import org.neo4j.graphdb.Direction;
  * the next step for. For example an alternating side selector will return alternating
  * start side and end side as long as each side hasn't reached it's end.
  */
+@PublicApi
 public interface SideSelector extends BranchSelector
 {
     /**

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/SideSelectorPolicies.java

@@ -19,13 +19,19 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
+
 /**
  * A catalogue of convenient side selector policies for use in bidirectional traversals.
- *
- * Copied from kernel package so that we can hide kernel from the public API.
  */
+@PublicApi
 public enum SideSelectorPolicies implements SideSelectorPolicy
 {
+    /**
+     * This `SideSelectorPolicy` stops traversal if the combined depth is larger than the given maximum depth. It
+     * will select branches for expansion that are on the same depth as the current branch before moving on to the
+     * next depth.
+     */
     LEVEL
     {
         @Override
@@ -34,6 +40,10 @@ public enum SideSelectorPolicies implements SideSelectorPolicy
             return new LevelSelectorOrderer( start, end, false, maxDepth );
         }
     },
+    /**
+     * This `SideSelectorPolicy` stops as soon as a result is found. It will select branches for expansion that are on
+     * the same depth as the current branch before moving on to the next depth.
+     */
     LEVEL_STOP_DESCENT_ON_RESULT
     {
         @Override
@@ -42,6 +52,9 @@ public enum SideSelectorPolicies implements SideSelectorPolicy
             return new LevelSelectorOrderer( start, end, true, maxDepth );
         }
     },
+    /**
+     * This `SideSelectorPolicy` alternates which branch continues the traversal.
+     */
     ALTERNATING
     {
         @Override

community/graphdb-api/src/main/java/org/neo4j/graphdb/traversal/SideSelectorPolicy.java

@@ -19,9 +19,12 @@
  */
 package org.neo4j.graphdb.traversal;
 
+import org.neo4j.annotations.api.PublicApi;
+
 /**
  * A factory for {@link SideSelector}s. Used during bidirectional traversals.
  */
+@PublicApi
 public interface SideSelectorPolicy
 {
     /**