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:

StructureQueryParser, StructureQueryBuilder

Constructor Summary

Constructors

Constructor and Description
StructureQuery()

Method Summary

Modifier and Type	Method and 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 Detail

StructureQuery

public StructureQuery()

Method Detail

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:

SearchService.validateQuery(ApplicationUser, Query), StructureQueryConstraint.validate(List)

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.