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

Class StructureQuery

Object
StructureQuery
@PublicApi public abstract class StructureQuery extends Object

A structure query is a condition on rows and their relationships in a Forest, such as rows that are children of issues satisfying JQL 'type = Epic' or rows at the top level of the forest. An object of class StructureQuery lets you search for matching rows in a given Forest. It also lets you validate the structure query it represents, returning error messages that you can display to the user.

This class is the API counterpart of the structure() JQL function bundled with the Structure plugin, along with the ability to retrieve Structure objects from StructureManager and structure's Forest from Structure.

StructureQuery is obtained by either parsing the query expressed in the StructuredJQL language, or by building it with StructureQueryBuilder. If you have obtained this StructureQuery by parsing a String, you can get this string back via getQueryString(). Otherwise, you can use toString(), which either returns the parsed query string or generates a query string if this query was built.

StructureQuery's equals() and hashCode() provide structural equality: if you have a query built by StructureQueryBuilder and a similar-looking query built by StructureQueryParser, they are equal, if they happen to have equal JQL constraints. That is, if you use JqlQueryParser instead of JqlQueryBuilder to create JQL Query that you put into StructureQueryBuilder, the resulting Structure query will be equal to the parsed one; this is due to the way Atlassian's Query.equals() and Query.hashCode() work.

Note: this class is not thread-safe.

Since:
8.1.0 (Structure 2.4)
Author:
Igor Baltiyskiy
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    StructureQuery()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract boolean
    checkIndex(int index, Forest forest)
    Checks if the row at the given index in the Forest matches the query.
    abstract boolean
    checkRow(Long rowId, Forest forest)
    Checks if the specified row matches the query against the specified Forest.
    abstract LongArray
    execute(Forest forest)
    Executes this query against the specified Forest, returning IDs of all matching rows in the forest order.
    abstract IntArray
    executeIndices(Forest forest)
    Executes this query against the specified Forest, returning indices of all matching rows in the forest order (i.e., the sequence of indices strictly increases.)
    abstract IntIterator
    executeIndicesUnbuffered(Forest forest)
    Executes this query against the specified Forest, returning an iterator over indices of all matching rows in the forest order (i.e., iterator values strictly increase.)
    abstract LongIterator
    executeUnbuffered(Forest forest)
    Executes this query against the specified Forest, returning an iterator over all matching row IDs in the forest order.
    abstract String
    getQueryString()
     
    abstract String
    getSanitizedQueryString()
    Returns a string representation of this query, with all the potential "information leaks" removed, with regards to the current user.
    abstract MessageSet
    validate()
    Validates this StructureQuery in the current authentication context.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • StructureQuery

      public StructureQuery()

  • Method Details

    • validate

      @NotNull public abstract MessageSet validate()

      Validates this StructureQuery in the current authentication context. The following things are checked:

      1. Whether all nested JQL constraints are valid, as per SearchService.validateQuery(User, Query).
      2. Whether referenced items exist and are accessible to the current user.
      3. Whether all nested constraints have valid arguments, as per StructureQueryConstraint.validate(List).
      4. Whether all saved filters (aka search requests) referenced in the nested JQL constraints don't reference themselves through the structure() JQL function.

      The resulting human-readable errors and warnings are reported in the returned MessageSet.

      The result of the validation is remembered, so that validation is not repeated at the execution time.

      Returns:
      human-readable validation error messages and warnings in the current user's locale; if there are no error messages, this query has passed the validation
      See Also:

    • getSanitizedQueryString

      @NotNull public abstract String getSanitizedQueryString()
      Returns a string representation of this query, with all the potential "information leaks" removed, with regards to the current user.
      Returns:
      sanitized string representation of this query
      Since:
      8.5.0 (Structure 2.8)
      See Also:
      • SearchService.sanitiseSearchQuery(com.atlassian.jira.user.ApplicationUser, com.atlassian.query.Query)

    • execute

      @NotNull public abstract LongArray execute(@NotNull Forest forest)

      Executes this query against the specified Forest, returning IDs of all matching rows in the forest order.

      This method observes JIRA and Structure permissions in the following ways:

      1. Only rows visible to the current user are returned.
      2. All JIRA searches for nested JQL constraints are executed under the current user.
      3. If the current user cannot use Structure, an empty list is returned.

      Prior to execution, validation status is checked. If validate() hasn't been called on this object before, validation is carried out. If validation fails, returns an empty list.

      If you are doing administrative tasks under a trusted account, and you need to ensure that you know all certain rows in a forest, override security in the current authentication context to skip validation and permission checks. In this case, this method will not require you to call nor call itself validate(), and all JIRA searches for nested JQL constraints will be executed without permission checks.

      Parameters:
      forest - the forest in which to search the rows
      Returns:
      the list of IDs of rows matching this query in forest in the forest order, subject to permission restrictions unless security is overridden

    • executeUnbuffered

      public abstract LongIterator executeUnbuffered(@NotNull Forest forest)

      Executes this query against the specified Forest, returning an iterator over all matching row IDs in the forest order.

      Behaves the same as execute(Forest) with respect to validation and permission checks.

      Parameters:
      forest - the forest in which to search the rows
      Returns:
      an iterator over matching row IDs in the forest order, subject to permission restrictions unless security is overridden

    • executeIndices

      @NotNull public abstract IntArray executeIndices(@NotNull Forest forest)

      Executes this query against the specified Forest, returning indices of all matching rows in the forest order (i.e., the sequence of indices strictly increases.)

      Behaves the same as execute(Forest) with respect to validation and permission checks.

      Parameters:
      forest - the forest in which to search the rows
      Returns:
      increasing positions of rows in forest matching this query

    • executeIndicesUnbuffered

      public abstract IntIterator executeIndicesUnbuffered(@NotNull Forest forest)

      Executes this query against the specified Forest, returning an iterator over indices of all matching rows in the forest order (i.e., iterator values strictly increase.)

      Behaves the same as execute(Forest) with respect to validation and permission checks.

      Parameters:
      forest - the forest in which to search the rows
      Returns:
      an iterator over increasing positions of rows in forest matching this query

    • checkRow

      public abstract boolean checkRow(Long rowId, @NotNull Forest forest)

      Checks if the specified row matches the query against the specified Forest.

      If rowId is null or the forest does not contain the row, false is returned.

      Because of possible implementation optimizations, it's better to use this method rather than calling execute(Forest) and checking if the row ID is contained in the result.

      Behaves the same as execute(Forest) with respect to validation and permission checks.

      Parameters:
      rowId - ID of the row to check
      forest - the forest against which the row should be checked
      Returns:
      true if the row matches the query, otherwise false

    • checkIndex

      public abstract boolean checkIndex(int index, Forest forest)

      Checks if the row at the given index in the Forest matches the query.

      If index is out of the forest bounds, false is returned.

      Because of possible implementation optimizations, it's better to use this method rather than calling executeIndices(com.almworks.jira.structure.api.forest.raw.Forest) and checking if the index is contained in the result.

      Behaves the same as execute(Forest) with respect to validation and permission checks.

      Parameters:
      index - index in the forest
      forest - the forest for which to check the row at the specified index
      Returns:
      true if the row at the specified index matches the query, otherwise false

    • getQueryString

      @Nullable public abstract String getQueryString()
      Returns:
      If this query was created by parsing a String, returns that String. Otherwise, returns null.