Package com.almworks.jira.structure.api.query

Interface QueryContext

@PublicApi public interface QueryContext

This interface represents the environment of the StructureQuery being executed. This interface is consumed by StructureQueryConstraint implementations.

It consists mostly of accessors to the forest being searched. Some of them are backed by a per-execution cache and have better amortized time compared to their counterparts from Forest.

There are also methods that help in mapping row ID to issue ID and vice versa.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    depth(int idx)
    A shorthand for getForest().getDepth(idx).
    LongArray
    filterIssues(Query query, LongList sortedIssues)
    Given the specified issue IDs (sorted in increasing order), returns those of them that match the specified JQL.
    Forest
    getForest()
    Returns the forest being searched.
    boolean
    isIssue(int idx)
    Returns true if the row at the specified index into the forest being searched represents an issue.
    long
    issueId(int idx)
    If the row at the specified index into the forest being searched represents an issue, returns that issues' ID; otherwise, returns 0.
    int
    parent(int idx)
    Behaves as getForest().getParentIndex(idx), but for many calls the amortized time is much less because of caching; for O(N) calls the amortized time is O(N) with N = size().
    LongIterable
    resolveIssueIdToRows(long issueId)
    Returns row IDs for rows in the forest being searched that represent issue with the specified ID.
    LongIterable
    resolveIssueKeyToRows(String issueKey)
    Returns row IDs for rows in the forest being searched that represent issues with the specified issue key.
    void
    resolveRowIdsToIssues(LongIterator rows, boolean sorted, LongLongProcedure rowIssueCollector)
    Looks up the specified rows, and for each issue among them calls rowIssueCollector with row ID and issue ID, respectively.
    StructureRow
    row(int idx)
    Returns a row object at the specified index in the forest being searched.
    long
    rowId(int idx)
    Returns row ID at the specified index in the forest being searched.
    LongIterator
    rows(IntIterator indices)
    Given indices into the forest being searched, returns the corresponding rows.
    int
    size()
    A shorthand for getForest().size().
    int
    subtreeEnd(int idx)
    Behaves as getForest().getSubtreeEnd(idx), but for many calls the amortized time is much less because of caching; for O(N) calls the amortized time is O(N) with N = size().

  • Method Details

    • rowId

      long rowId(int idx)
      Returns row ID at the specified index in the forest being searched. Basically, a shorthand for getForest().getRow(idx).
      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      row ID
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).
      See Also:

    • row

      StructureRow row(int idx)
      Returns a row object at the specified index in the forest being searched. Basically, a shorthand for RowManager rm = ...; rm.getRow(getForest().getRow(idx)).
      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      row object
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).
      See Also:

    • rows

      LongIterator rows(IntIterator indices)
      Given indices into the forest being searched, returns the corresponding rows. This behaves like getForest().getRows().get(indices), but the result is computed on-demand (lazily).
      Parameters:
      indices - an iterator over indices into the forest being searched; each index must be not less than 0 and less than size()
      Returns:
      row IDs
      Throws:
      IndexOutOfBoundsException - if any of indices is not within range [0 .. size()).
      See Also:

    • isIssue

      boolean isIssue(int idx)
      Returns true if the row at the specified index into the forest being searched represents an issue. The result is cached, so subsequent calls of this method during the computation of this query should be faster.
      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      true iff the row is an issue
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).

    • issueId

      long issueId(int idx)
      If the row at the specified index into the forest being searched represents an issue, returns that issues' ID; otherwise, returns 0. The result is cached, so subsequent calls of this method during the computation of this query should be faster.
      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      issue ID if the row is an issue, 0 otherwise
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).

    • depth

      int depth(int idx)
      A shorthand for getForest().getDepth(idx).
      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      row depth
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).
      See Also:

    • size

      int size()
      A shorthand for getForest().size().
      Returns:
      size of the forest being searched
      See Also:

    • parent

      int parent(int idx)

      Behaves as getForest().getParentIndex(idx), but for many calls the amortized time is much less because of caching; for O(N) calls the amortized time is O(N) with N = size().

      Not only the result for the requested index is cached, but also the results of all indices between the requested index and the returned index.

      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      index of the parent row for the specified row
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).
      See Also:

    • subtreeEnd

      int subtreeEnd(int idx)

      Behaves as getForest().getSubtreeEnd(idx), but for many calls the amortized time is much less because of caching; for O(N) calls the amortized time is O(N) with N = size().

      Not only the result for the requested index is cached, but also the results of all indices between the requested index and the returned index.

      Parameters:
      idx - index into the forest being searched, must be not less than 0 and less than size()
      Returns:
      next index after the end of this row's subtree
      Throws:
      IndexOutOfBoundsException - if idx is not within range [0 .. size()).
      See Also:

    • getForest

      Forest getForest()
      Returns the forest being searched.
      Returns:
      the forest being searched

    • resolveRowIdsToIssues

      void resolveRowIdsToIssues(LongIterator rows, boolean sorted, LongLongProcedure rowIssueCollector)

      Looks up the specified rows, and for each issue among them calls rowIssueCollector with row ID and issue ID, respectively.

      This method reuses the same cache used by isIssue(int) and issueId(int). Also, it uses a faster bulk row lookup method in RowManager.

      There are no guarantees on the order of calls to rowIssueCollector regardless of sorted parameter.

      Parameters:
      rows - row IDs to resolve
      sorted - specify true if you can guarantee that the iterator produces strictly increasing values. Mind that here we talk about values ordered by row ID, not index into the forest being searched.
      rowIssueCollector - callback to receive (row ID, issue ID) for all rows among rows that represent issues. The order of calls may not correspond to the order in rows.

    • filterIssues

      LongArray filterIssues(Query query, LongList sortedIssues)

      Given the specified issue IDs (sorted in increasing order), returns those of them that match the specified JQL.

      The order of elements in the returned is not specified.

      Parameters:
      query - the JQL query object
      sortedIssues - issue ID list, sorted in increasing order
      Returns:
      ID list of issues matching the JQL, in unspecified order

    • resolveIssueIdToRows

      LongIterable resolveIssueIdToRows(long issueId)
      Returns row IDs for rows in the forest being searched that represent issue with the specified ID.
      Parameters:
      issueId - ID of the issue (e.g., 10210)
      Returns:
      row IDs for rows in the forest being searched that represent the issue

    • resolveIssueKeyToRows

      LongIterable resolveIssueKeyToRows(String issueKey)
      Returns row IDs for rows in the forest being searched that represent issues with the specified issue key.
      Parameters:
      issueKey - key of the issue (e.g., FOO-123)
      Returns:
      row IDs for rows in the forest being searched that represent the issue