Package com.almworks.jira.structure.api.forest.raw

Class ArrayForest

Object
ArrayForest
All Implemented Interfaces:
LongIntIterable, Forest, Iterable<LongIntIterator>
public class ArrayForest extends Object implements Forest
Mutable inheritor of Forest class. ArrayForest is a data structure that implements Forest. Any modifications to the ArrayForest are only applied to that instance in memory.

Under-After Coordinates

When a specific position in the forest needs to be defined for mutating operations such as move or insert, under-after coordinates are used. (If operation addresses a specific row, the row ID is used instead.)

Under-after coordinates contain under value, which identifies the parent row of the specified position (the depth and the subtree). If under is 0, the position is at the top (root row).

The other parameter, after coordinate, defines the location of the inserted row amongst siblings - the rows at the same depth under the same parent. If after is 0, it means that the position should be the first under the specified parent.

Note: moving a row after itself, i.e. when the under coordinate is equal to the row's parent row and the after coordinate is equal to the row itself, is allowed and does not change the position of the row.

Methods from this class don't not modify the forest stored in the database for a structure. To make modifications of the structure's forest, apply forest changes with ForestSource.apply(ForestAction).

This class in not thread-safe.

Author:
Igor Sereda
See Also:

  • Constructor Details

    • ArrayForest

      public ArrayForest()

    • ArrayForest

      public ArrayForest(long row)
      Creates a singular tree. Singular tree cannot be stored (the row is a standalone row), but can be used between operations on other trees.
      Parameters:
      row - row ID of the root

    • ArrayForest

      public ArrayForest(WritableLongList rows, WritableIntList depths, boolean reuseLists)
      Constructs a forest based on the given rows and depths.

      Row list and depth list must conform to the RowTree invariants. If invariants are violated, then either an error is thrown (if assertions are on), or further behavior is undefined.

      Parameters:
      rows - list of row IDs
      depths - list of corresponding depths
      reuseLists - if true, passed instances of List can be used by this RowTree (otherwise a copy is made)

    • ArrayForest

      public ArrayForest(LongList rows, IntList depths)

    • ArrayForest

      public ArrayForest(Forest copyFrom)

  • Method Details

    • set

      public final Forest set(WritableLongList rows, WritableIntList depths, boolean reuseLists)

      Replaces the contents of this forest with the values passed in the parameters.

      The passed lists must satisfy the invariant conditions listed in Forest, otherwise the results are undefined.

      Parameters:
      rows - new row list
      depths - new depths list
      reuseLists - if true, the passed arrays may be used by the forest without copying the data. In that case, the calling code must not use these lists after this method call.
      Returns:
      this forest

    • set

      public Forest set(LongList rows, IntList depths)

      Replaces the contents of this forest with the values passed in the parameters.

      The passed lists must satisfy the invariant conditions listed in Forest, otherwise the results are undefined.

      Parameters:
      rows - new row list
      depths - new depths list
      Returns:
      this forest

    • getDiagnostics

      public String getDiagnostics()

    • getDiagnostics

      public static String getDiagnostics(Forest f)
      Checks whether RowTree invariants hold.
      Returns:
      null if all invariants are true, otherwise return a message with description of the problem

    • containsRow

      public boolean containsRow(long row)
      Description copied from interface: Forest

      Can be used to check if the forest contains a specific row.

      Execution of this method may take O(size()) time.

      Specified by:
      containsRow in interface Forest
      Parameters:
      row - the row ID to search for
      Returns:
      true if the forest contains the specified row

    • mergeForest

      public void mergeForest(Forest forest, long under, long after) throws StructureException
      Convenience method to call mergeForest(Forest, long, long, ForestChangeEventHandler) without event handler.
      Parameters:
      forest - the merged forest
      under - the parent of the merged forest, or 0 if the forest rows should be placed at the root level
      after - the preceding sibling of the merged forest, or 0 to place forest as the first child
      Throws:
      StructureException - if the operation cannot be completed because it requires an invalid move

    • addForest

      public void addForest(long under, long after, Forest forest)

    • clear

      public void clear()

    • mergeForest

      public void mergeForest(Forest forest, long under, long after, @Nullable ForestChangeEventHandler eventHandler) throws StructureException

      Merges another forest into this forest. After the method has executed, this forest will contain all rows from forest in the same topology under the specified positions: the root rows from forest will be positioned as defined by under-after coordinates (see Forest for the explanation of under-after coordinates), and non-root rows from forest will have the same parent rows as in forest.

      This forest and the merged forest may have the same rows. In that case the rows are moved within this forest and placed at the position required by this operation.

      When StructureException is thrown from this method, the state of this forest is unknown - due to the fact that merge splits into several atomic updates and the exception may be thrown after some of the updates have taken place.

      Parameters:
      forest - the merged forest
      under - the parent of the merged forest, or 0 if the forest rows should be placed at the root level
      after - the preceding sibling of the merged forest, or 0 to place forest as the first child
      eventHandler - an optional event handler to get notifications about changes being applied - may be called several times because merge could be split into series of moves and additions.
      Throws:
      StructureException - if the operation cannot be completed because it requires an invalid move

    • addRow

      public boolean addRow(long row, long under, long after) throws StructureException

      Adds a single row at the specified position.

      If the row is already in the structure, this method moves it to the specified position.

      Parameters:
      row - row to be added
      under - the parent of the row, or 0 if the row should be placed at the forest root level
      after - the preceding sibling of the row, or 0 to place row as the first child
      Returns:
      true if the forest has been changed
      Throws:
      StructureException - if under is not in the forest or if a similar problem happens

    • addForestMutuallyExclusive

      public void addForestMutuallyExclusive(Forest forest, long under, long after) throws StructureException
      Adds a forest to this forest. Works faster than addForest(long, long, Forest) and mergeForest(Forest, long, long) when the added forest is guaranteed to be mutually exclusive with this forest, i.e. when it contains only row IDs not present in this forest. If this is not the case, the result of the operation is undefined.
      Parameters:
      forest - the forest to add
      under - the parent of the added forest, or 0 if the forest rows should be placed at the root level
      after - the preceding sibling of the added forest, or 0 to place forest as the first child
      Throws:
      StructureException - if under is not in the forest or if a similar problem happens

    • removeSubtree

      @NotNull public Forest removeSubtree(long row, ForestChangeEventHandler eventHandler)
      Removes a subtree from this forest.

      This method will create a new RowTree with row at its root and all sub-rows, properly outdented.

      Parameters:
      row - row ID of the root of the subtree to be removed
      Returns:
      null if this tree does not contain row, otherwise an RowTree with the row as the root

    • removeSubtreeAtIndex

      @NotNull public Forest removeSubtreeAtIndex(int index, @Nullable ForestChangeEventHandler eventHandler)

      Removes a sub-tree with rooted at the specified index from this forest.

      Parameters:
      index - the index of the root of the sub-tree to be removed
      eventHandler - optional handler of the forest events
      Returns:
      forest with the removed rows, or empty forest if index is negative

    • subtree

      @NotNull public Forest subtree(long row)
      Description copied from interface: Forest
      Creates a forest that contains the specified row and all its sub-rows from this forest.
      Specified by:
      subtree in interface Forest
      Parameters:
      row - the root of the sub-tree
      Returns:
      a new forest that contains a copy of the sub-tree rooted at row, or an empty forest if the row is not in this forest

    • subtreeAtIndex

      @NotNull public Forest subtreeAtIndex(int index)
      Description copied from interface: Forest
      Creates a forest that contains the specified row and all its sub-rows from this forest.
      Specified by:
      subtreeAtIndex in interface Forest
      Parameters:
      index - index of the root of the sub-tree
      Returns:
      a new forest that contains a copy of the sub-tree rooted at row at index, or an empty forest if the index is negative

    • getSubtreeEnd

      public int getSubtreeEnd(int index)
      Description copied from interface: Forest

      The method looks for the end of a subtree rooted at the specified index.

      A subtree rooted at index k is a sub-sequence in the forest starting at position k and containing all following elements that have depth d > depth[k].

      The result of this method is the next index after the last element of this subsequence. More specifically, the result is the first element after [k] that has depth d <= depth[k].

      When the subtree ends with the whole forest, the return value is equal to Forest.size().

      If index is a negative number, the returned value is 0. If index is greater or equal than size(), the returned value is equal to size().

      Specified by:
      getSubtreeEnd in interface Forest
      Parameters:
      index - the index of the root row of the subtree
      Returns:
      the index of the row that follows the last row of the subtree, or the size of the forest in case the subtree is at the end of it

    • copySubforest

      @Nullable public ArrayForest copySubforest(long row)
      Specified by:
      copySubforest in interface Forest

    • copySubforestAtIndex

      @Nullable public ArrayForest copySubforestAtIndex(int k)
      Specified by:
      copySubforestAtIndex in interface Forest

    • getRows

      @NotNull public LongList getRows()
      Description copied from interface: Forest
      Returns a non-modifiable list of rows, in the order they appear in the forest. The size of the list is equal to the value returned by Forest.size().
      Specified by:
      getRows in interface Forest
      Returns:
      list of IDs of rows contained in the forest

    • getDepths

      @NotNull public IntList getDepths()
      Description copied from interface: Forest
      Returns a non-modifiable list of depths, in the order the rows appear in the forest. The size of the list is equal to the value returned by Forest.size() and the i-th element of this list corresponds to the row ID at the i-th position in the list returned by Forest.getRows().
      Specified by:
      getDepths in interface Forest
      Returns:
      list of depths of rows contained in the forest, parallel to the rows list

    • getRow

      public long getRow(int index)
      Description copied from interface: Forest
      Gets the ID of the row at the specified position in the forest.
      Specified by:
      getRow in interface Forest
      Parameters:
      index - the index of the forest entry
      Returns:
      row ID at the specified index

    • getDepth

      public int getDepth(int index)
      Description copied from interface: Forest
      Gets the depth of the row at the specified position in the forest.
      Specified by:
      getDepth in interface Forest
      Parameters:
      index - the index of the forest entry
      Returns:
      depth at the specified index, value is always >= 0 and satisfies the invariants for the Forest

    • getParent

      public long getParent(long row)
      Description copied from interface: Forest
      Gets the parent row of the specified row.
      Specified by:
      getParent in interface Forest
      Parameters:
      row - child row
      Returns:
      parent row, or 0 if the child row is a root row or not found in the forest

    • getParentIndex

      public int getParentIndex(int index)
      Description copied from interface: Forest

      Searches the forest for the index of a "parent row". If the row at the specified index is a root row (has depth of 0), returns -1.

      If index is negative, returns -1.

      Specified by:
      getParentIndex in interface Forest
      Parameters:
      index - index of a child row
      Returns:
      -1 if the row at index is a root row, or index k of the parent row, such as that k = MAX(k in [0, index-1] that has depth[k] == depth[index] - 1)

    • getPathIndexAtDepth

      public int getPathIndexAtDepth(int index, int depth)
      Description copied from interface: Forest

      Given row at the specified index, traverses its "path" upwards - that is, looks for all parent rows up to the topmost root parent, and returns an index of the parent that has the specified depth.

      If the required depth is equal to the depth of the row at the specified index, returns index.

      If index is a negative value, returns -1. If row at the specified index has less depth than the required value, returns -1.

      Specified by:
      getPathIndexAtDepth in interface Forest
      Parameters:
      index - index of the row
      depth - required depth of the [grand-] parent row
      Returns:
      the index of the [grand-] parent row on the "path" to the specified row that has the specified depth, or -1 if not found

    • getPrecedingSiblingIndex

      public int getPrecedingSiblingIndex(int index)
      Description copied from interface: Forest
      Gets the index of the row that immediately precedes the row at the given index in the list of children of its parent.
      Specified by:
      getPrecedingSiblingIndex in interface Forest
      Parameters:
      index - row index
      Returns:
      index of immediately preceding sibling, or -1 if row at index is not found in the forest or is the first root or the first child of its parent row

    • getPrecedingSiblingForIndex

      public long getPrecedingSiblingForIndex(int index)
      Description copied from interface: Forest
      Gets the row that immediately precedes the one with the given index in the list of children of its parent.
      Specified by:
      getPrecedingSiblingForIndex in interface Forest
      Parameters:
      index - row index
      Returns:
      immediately preceding sibling, or 0 if there is none

    • getPrecedingSibling

      public long getPrecedingSibling(long row)
      Description copied from interface: Forest
      Gets the row that immediately precedes the specified row in the list of children of the specified row's parent.
      Specified by:
      getPrecedingSibling in interface Forest
      Parameters:
      row - a row
      Returns:
      immediately preceding sibling (row that has the same parent and same depth), or 0 if row is not found in the forest or is the first root or the first child of its parent row

    • getPrecedingSiblings

      @NotNull public LongArray getPrecedingSiblings(long row)
      Description copied from interface: Forest
      Returns the array of all rows that come before the given row in the list of children of its parent, in the same order as they appear in the forest.
      Specified by:
      getPrecedingSiblings in interface Forest
      Parameters:
      row - a row
      Returns:
      array of all preceding siblings, empty if row has none or is not in the forest

    • getPrecedingSiblingsForIndex

      @NotNull public LongArray getPrecedingSiblingsForIndex(int index)
      Description copied from interface: Forest
      Returns the array of all rows that come before the given row in the list of children of its parent, in the same order as they appear in the forest.
      Specified by:
      getPrecedingSiblingsForIndex in interface Forest
      Parameters:
      index - row index
      Returns:
      array of all preceding siblings, empty if row at index has none or index is negative

    • getNextSiblingIndex

      public int getNextSiblingIndex(int index)
      Description copied from interface: Forest
      Gets the index of the row that immediately follows the row at the given index in the list of children of its parent.
      Specified by:
      getNextSiblingIndex in interface Forest
      Parameters:
      index - row index
      Returns:
      index of immediately following sibling, or -1 if row at index is not found in the forest or is the last root or the last child of its parent row

    • getNextSiblingForIndex

      public long getNextSiblingForIndex(int index)
      Description copied from interface: Forest
      Gets the row that immediately follows the one with the given index in the list of children of its parent.
      Specified by:
      getNextSiblingForIndex in interface Forest
      Parameters:
      index - row index
      Returns:
      immediately following sibling, or 0 if there is none

    • getNextSibling

      public long getNextSibling(long row)
      Description copied from interface: Forest
      Gets the row that immediately follows the specified row in the list of children of the specified row's parent.
      Specified by:
      getNextSibling in interface Forest
      Parameters:
      row - a row
      Returns:
      immediately following sibling (row that has the same parent and same depth), or 0 if row is not found in the forest or is the last root or the last child of its parent row

    • getChildren

      @NotNull public LongArray getChildren(long row)
      Description copied from interface: Forest

      Creates an array with all direct sub-rows of the specified row.

      The returned array is writable and owned by the calling code.

      If row is not in the forest or does not have children, empty array is returned.

      Specified by:
      getChildren in interface Forest
      Parameters:
      row - the parent row, you can pass 0 to get the roots.
      Returns:
      array of all sub-rows of the specified row that have depth equal to the parent depth + 1

    • getChildrenAtIndex

      @NotNull public LongArray getChildrenAtIndex(int index)
      Description copied from interface: Forest

      Creates an array with all direct sub-rows of the row at the specified index.

      The returned array is writable and owned by the calling code.

      If the specified row does not have children, or if the index is negative, empty array is returned.

      Specified by:
      getChildrenAtIndex in interface Forest
      Parameters:
      index - the index of the parent row
      Returns:
      array of all sub-rows of the specified row that have depth equal to the parent depth + 1

    • getChildrenIndicesIterator

      @NotNull public IntIterator getChildrenIndicesIterator(int index)
      Description copied from interface: Forest

      Returns an iterator over indices of all direct sub-rows of the row at the specified index.

      This method is a lazy variant of Forest.getChildrenAtIndex(int): the underlying data structure is scanned as you advance the returned iterator. This allows to save on an extra scan, and on copying to the result array.

      Another difference is that this method returns indices, not the rows themselves.

      Specified by:
      getChildrenIndicesIterator in interface Forest
      Parameters:
      index - the index of the parent row, in the interval [-1; forest.size()); if -1, will iterate over roots
      Returns:
      iterator over indices of all sub-rows of the specified row that have depth equal to the parent depth + 1, or over indices of roots if index is -1

    • getRoots

      @NotNull public LongArray getRoots()
      Description copied from interface: Forest
      Returns an array of all root rows in the forest (those that have depth of 0).
      Specified by:
      getRoots in interface Forest
      Returns:
      an array of all root rows in the forest (those that have depth of 0)

    • filter

      @NotNull public ArrayForest filter(La<Long,?> filter)
      Description copied from interface: Forest

      Filters this forest by hiding rows that do not pass the filter condition. The resulting forest contains only the rows that pass the condition (all of them).

      The topology of the resulting forest may differ from the original forest - that is, a row may have a different parent in the resulting forest. This happens when a row that has sub-rows is filtered out - in that case, its sub-tree is substituted instead of the parent row. This is different from Forest.filterSoft(com.almworks.jira.structure.api.util.La<java.lang.Long, ?>) method, which preserves the topology.

      This forest is not modified by this method. If all rows pass the condition, then this forest is returned as the result. If filtering has taken place, a new forest is returned.

      The filter method is called once for every row in the forest, and a truthy result (as defined in La.accepts(T)) indicates that the row passes the filter.

      Specified by:
      filter in interface Forest
      Parameters:
      filter - filter that returns a truthy value if the row with given ID is allowed to be present in the resulting forest. Null means "no filtering" - this forest is returned
      Returns:
      a filtered forest (or this forest if all rows satisfy the filter)
      See Also:

    • filterSoft

      @NotNull public ArrayForest filterSoft(La<Long,?> filter)
      Description copied from interface: Forest

      Filters this forest by excluding rows that do not pass the filter condition. All rows that contain sub-rows that have passed the filter are also preserved. The resulting forest contains sub-sequence of the original forest with rows having the same parents and depths.

      Unlike Forest.filter(com.almworks.jira.structure.api.util.La<java.lang.Long, ?>) method, this method preserves the topology of the original forest - all rows in the resulting forest have the same root path as they do in the original forest.

      This forest is not modified by this method. If all rows pass the condition, then this forest is returned as the result. If filtering has taken place, a new forest is returned.

      The filter method is called once for every row in the forest, and a truthy result (as defined in La.accepts(T)) indicates that the row passes the filter.

      Note: if you need to filter by hierarchy-based or JQL constraints, see StructureQuery.

      Specified by:
      filterSoft in interface Forest
      Parameters:
      filter - filter that returns a truthy value if a row with given ID should be present in the resulting forest Null means "no filtering" - this forest is returned
      Returns:
      a filtered forest (or this forest if all rows satisfy the filter)

    • filterHardest

      @NotNull public ArrayForest filterHardest(La<Long,?> filter)
      Description copied from interface: Forest

      Filters this forest by excluding rows that do not pass the filter condition. All sub-rows of rows that have not passed the filter are also removed. The resulting forest contains only rows that pass the condition, but possibly not all of them.

      Unlike Forest.filter(com.almworks.jira.structure.api.util.La<java.lang.Long, ?>) method, this method preserves the topology of the original forest - all rows in the resulting forest have the same root path as they do in the original forest. However, unlike Forest.filterSoft(com.almworks.jira.structure.api.util.La<java.lang.Long, ?>) it achieves that by not including those matching rows that would change the hierarchy.

      This forest is not modified by this method. If all rows pass the condition, then this forest is returned as the result. If filtering has taken place, a new forest is returned.

      The filter method is called once for every row in the forest, and a truthy result (as defined in La.accepts(T)) indicates that the row passes the filter.

      Specified by:
      filterHardest in interface Forest
      Parameters:
      filter - filter that returns a truthy value if a row with given ID should be present in the resulting forest Null means "no filtering" - this forest is returned
      Returns:
      a filtered forest (or this forest if all rows satisfy the filter)

    • makeImmutable

      @NotNull public ArrayForest makeImmutable()
      Makes this instance non-modifiable
      Returns:
      row tree with the same data (backed by different collections), which cannot be modified

    • isImmutable

      public boolean isImmutable()
      Description copied from interface: Forest
      Returns true if the forest is immutable.
      Specified by:
      isImmutable in interface Forest
      See Also:

    • ensureImmutability

      @NotNull public static Forest ensureImmutability(@NotNull Forest forest)

    • size

      public int size()
      Gets the number of rows in this tree.
      Specified by:
      size in interface Forest
      Returns:
      the number of rows, also the size of lists returned by getRows() and getDepths()

    • copy

      @NotNull public ArrayForest copy()
      Description copied from interface: Forest
      Creates an exact copy of this forest.
      Specified by:
      copy in interface Forest
      Returns:
      a copy of this forest

    • moveSubtree

      public boolean moveSubtree(long row, long under, long after) throws StructureException
      Convenience method to call moveSubtree(long, long, long, ForestChangeEventHandler) without event handler.
      Parameters:
      row - the root row of the sub-tree being moved
      under - the new parent of the sub-tree, or 0 if the sub-tree should be placed at the forest root level
      after - the preceding sibling of the new location for the sub-tree, or 0 to place sub-tree as the first child
      Returns:
      true if the sub-tree has been moved, false if not (for example, if the row is not in the forest)
      Throws:
      StructureException - if the move is not possible - for example, under is not in the forest or if you attempt to move a sub-tree under itself

    • moveSubtree

      public boolean moveSubtree(long row, long under, long after, @Nullable ForestChangeEventHandler eventHandler) throws StructureException

      Moves sub-tree rooted at the specified row to a position specified by (under, after) coordinates.

      This method modifies the forest by removing the sub-tree with the specified row as the root and adding it at the position specified by under-after coordinates. See Forest for the explanation of under-after coordinates.

      Parameters:
      row - the root row of the sub-tree being moved
      under - the new parent of the sub-tree, or 0 if the sub-tree should be placed at the forest root level
      after - the preceding sibling of the new location for the sub-tree, or 0 to place sub-tree as the first child
      eventHandler - optional handler of the move events
      Returns:
      true if the sub-tree has been moved, false if not (for example, if the row is not in the forest)
      Throws:
      StructureException - if the move is not possible - for example, under is not in the forest or if you attempt to move a sub-tree under itself

    • moveSubtreeAtIndex

      public int moveSubtreeAtIndex(int index, long under, long after, @Nullable ForestChangeEventHandler eventHandler) throws StructureException

      Moves sub-tree rooted at the specified index to a position specified by (under, after) coordinates.

      This method modifies the forest by removing the sub-tree with the specified row as the root and adding it at the position specified by under-after coordinates. See Forest for the explanation of under-after coordinates.

      Parameters:
      index - the index of the root row of the sub-tree being moved
      under - the new parent of the sub-tree, or 0 if the sub-tree should be placed at the forest root level
      after - the preceding sibling of the new location for the sub-tree, or 0 to place sub-tree as the first child
      eventHandler - optional handler of the move events
      Returns:
      new index of the sub-tree if it has been moved, -1 if not (for example, if the given row index is negative or the subtree is already there)
      Throws:
      StructureException - if the move is not possible - for example, under is not in the forest or if you attempt to move a sub-tree under itself

    • indexOf

      public int indexOf(long row)
      Description copied from interface: Forest

      Searches for the position of a specific row in the forest.

      Execution of this method may take O(size()) time, however it may be optimized if the implementation maintains an index. It's better to use this method rather than using forest.getRows().indexOf(row) because of the possible optimizations.

      Specified by:
      indexOf in interface Forest
      Parameters:
      row - the row ID to search for
      Returns:
      such index of the row in the forest, or -1 if the row is not found

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: Forest
      Used to check if the forest does not contain any rows.
      Specified by:
      isEmpty in interface Forest
      Returns:
      true if the size of the forest is zero

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toFullString

      @NotNull public String toFullString()
      Description copied from interface: Forest
      Utility method for debugging - returns full string representation of the forest, that contains all the information, unlike toString() method, which may be truncated to some character number limit.
      Specified by:
      toFullString in interface Forest
      Returns:
      a full string containing all information about this forest

    • clone

      public ArrayForest clone()
      Overrides:
      clone in class Object

    • getLastChild

      public long getLastChild(long parent)
      Description copied from interface: Forest

      Gets the last direct sub-row of the specified parent row.

      Special case: when parent is 0, returns the last root row in the forest.

      If the parent row is not in the forest, or if it does not have child rows, the return value is 0.

      Specified by:
      getLastChild in interface Forest
      Parameters:
      parent - parent row
      Returns:
      the last row among the parent row's children, or 0 if the parent row does not have children

    • getLastChildByIndex

      public long getLastChildByIndex(int parentIndex)
      Description copied from interface: Forest

      Gets the last direct sub-row of the specified parent row.

      Special case: when parentIndex is less than zero, returns the last root row in the forest.

      If the parent row does not have child rows, the return value is 0.

      Specified by:
      getLastChildByIndex in interface Forest
      Parameters:
      parentIndex - the index of the parent row
      Returns:
      the last row among the parent row's children, or 0 if the parent row does not have children

    • foldUpwards

      public <T, C> C foldUpwards(ForestParentChildrenClosure<T,C> closure)
      Description copied from interface: Forest

      This is a more generic version of Forest.visitParentChildrenUpwards(com.almworks.jira.structure.api.forest.raw.ForestParentChildrenVisitor) that allows you to effectively process the forest bottom-up, probably saving on memory allocation and search speed.

      The method goes over the forest in the backwards direction and calls closure methods for each row:

      Specified by:
      foldUpwards in interface Forest
      Type Parameters:
      T - the type of the result of processing one row
      C - the type of the result of processing a number of sub-rows under the same parent
      Parameters:
      closure - the closure
      Returns:
      the result of processing top-level rows in the forest
      See Also:

    • scanDownwards

      public void scanDownwards(ForestScanner scanner)
      Description copied from interface: Forest
      Iterates through each row from top to the bottom. ForestScanner receives ForestScanControl, which can be used to cancel the scan, access parents, or skip subtrees.
      Specified by:
      scanDownwards in interface Forest
      Parameters:
      scanner - the iteratee

    • visitParentChildrenUpwards

      public void visitParentChildrenUpwards(ForestParentChildrenVisitor visitor)
      Description copied from interface: Forest

      This method is used to efficiently traverse all pairs (parent, children) from the end of the forest upwards.

      This method goes over the forest in the backwards direction and reports to the visitor pairs of (parent, direct children).

      Invariants:

      • The number of calls to the visitor is equal to the forest size: every row is reported as a parent once.
      • A child row is reported (as the parent of its own sub-rows) before parent is reported: the iteration goes upwards.
      • A leaf row is reported as a parent with no children (empty children list).

      If the forest is modified during iteration, the results are undefined.

      Specified by:
      visitParentChildrenUpwards in interface Forest
      Parameters:
      visitor - the visitor to receive pairs of (parent, children)

    • getPath

      @NotNull public LongArray getPath(long row)
      Description copied from interface: Forest

      Returns the path to the specified row - a sequence of rows that starts with a root row, ends with the specified row, and where element[i] is the parent row of element[i+1].

      If row is not in the forest, returns empty array.

      The array is modifiable and owned by the calling code.

      Specified by:
      getPath in interface Forest
      Parameters:
      row - row to get the path to
      Returns:
      path to the specified row, or empty array if the row is not in the forest

    • getPathForIndex

      @NotNull public LongArray getPathForIndex(int idx)
      Description copied from interface: Forest
      Similar to Forest.getPath(long), returns the path to the row specified by index.
      Specified by:
      getPathForIndex in interface Forest
      Parameters:
      idx - the index of the row to get the path to
      Returns:
      path to the specified row, or empty array if the index is negative

    • getParentPathForIndex

      @NotNull public LongArray getParentPathForIndex(int index)
      Description copied from interface: Forest

      Returns the path to the specified row without the row itself. In other words, this is the path to the parent of the specified row, if there is one.

      Specified by:
      getParentPathForIndex in interface Forest
      Parameters:
      index - row index
      Returns:
      path to the specified row's parent; empty array if the row is top-level or not in the forest
      See Also:

    • removeSubtree

      @NotNull public Forest removeSubtree(long row)
      Convenience method to call removeSubtree(long, ForestChangeEventHandler) without event handler.
      Parameters:
      row - the root of the sub-tree to be removed
      Returns:
      forest with the removed rows, or empty forest if row is not in this forest.

    • reorder

      public void reorder(long parent, LongList children)

    • append

      public void append(Forest forest)

    • iterator

      @NotNull public LongIntIterator iterator()
      Specified by:
      iterator in interface Iterable<LongIntIterator>
      Specified by:
      iterator in interface LongIntIterable

    • replaceSubtrees

      public void replaceSubtrees(long rowId, Forest forest)
      Removes everything from under given row and inserts forest as sub-forest of rowId.
      Parameters:
      rowId - parent rowId, or 0 if the whole forest should be replaced
      forest - the content to insert in place of the removed sub-forest under rowId

    • replaceSubtreesMutuallyExclusive

      public void replaceSubtreesMutuallyExclusive(long rowId, Forest forest)

    • replaceSubtreesMutuallyExclusiveAtIndex

      public void replaceSubtreesMutuallyExclusiveAtIndex(int index, Forest forest)
      Removes everything from under row with given index and inserts forest as sub-forest of the same row
      Parameters:
      index - parent row index, should be in [-1, forest.size()) range, -1 means replace the whole forest
      forest - the content to insert in place of the removed sub-forest under