com.almworks.jira.structure.api.query

Interface StructureQueryConstraint

@PublicSpi
public interface StructureQueryConstraint

This is an extension point in the S-JQL, through which you can add custom basic constraints on forest rows to StructureQuery.

The constraint is always executed in the context of some forest (e.g., when StructureQuery.execute(Forest) is called). It is given a sequence of indices into the forest, which it filters according to the desired criteria.

Syntactically, this corresponds to one of the following constructs:

1. condition name followed by a comma-separated list of arguments in parentheses: name ( arg1 , arg2 , ... , argN ) , where N >= 0;
2. condition name followed by a single argument (the argument cannot contain spaces): name arg1.

An instance of a query constraint is registered in the atlassian-plugin.xml file of your plugin using structure-query-constraint module type.

Query constraint name must not coincide with one of the existing S-JQL keywords. However, it is possible to register two constraints with the same names. The conflict is resolved using the order attribute of the structure-query-constraint element in atlassian-plugin.xml: lower order wins - constraint with lower order always overrides constraint with higher order. In case of tie, the order is unspecified.

See Also:

S-JQL reference, StructureQuery.execute(Forest)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	StructureQueryConstraint.Acceptor Represents the consumer of StructureQueryConstraint.Sequence values - i.e., the consumer of matching indices.
static class	StructureQueryConstraint.BulkFilter A base implementation for a constraint that looks at a bunch of rows at a time.
static class	StructureQueryConstraint.EmptySequence A default implementation of an empty sequence.
static interface	StructureQueryConstraint.Sequence Allows to implement a sequence of numbers in a generator-like fashion.
static class	StructureQueryConstraint.SimpleFilter A base implementation for a simple constraint that looks at one row at a time.

Method Summary

Modifier and Type	Method and Description
StructureQueryConstraint.Sequence	filter(com.almworks.integers.IntIterator indices, List<String> arguments, QueryContext context) Filters the specified indices in the forest being searched according to some criteria.
com.atlassian.jira.util.MessageSet	validate(List<String> arguments) Validates the list of arguments.

Method Detail

validate

com.atlassian.jira.util.MessageSet validate(@NotNull
                                            List<String> arguments)

Validates the list of arguments. This method is called when StructureQuery.validate() is called.

Number of arguments, as well as semantic validity of arguments can be checked. If any of the tests fail, the results should be included in the resulting message set through MessageSet.addErrorMessage(String). Warnings can be added as well, but note that both JIRA and Structure ignore them.

See StructureQueryConstraints.validateArgumentCount(java.util.List<java.lang.String>, int, int, com.atlassian.jira.util.MessageSet) for a standard method of verifying the number of arguments.

Parameters:

arguments - list of arguments passed to this constraint in some StructureQuery: not null, its elements are not null

Returns:

validation results (as error messages)

See Also:

StructureQueryConstraints.validateArgumentCount(List, int, int, MessageSet)

filter

StructureQueryConstraint.Sequence filter(@NotNull
                                         com.almworks.integers.IntIterator indices,
                                         @NotNull
                                         List<String> arguments,
                                         @NotNull
                                         QueryContext context)

Filters the specified indices in the forest being searched according to some criteria.

Use QueryContext to access the forest being searched.

The incoming indices are sorted in the increasing order. The implementation must return indices also in increasing order, without repetition. Moreover, it must return only those indices that were returned from indices iterator. An example where the latter is violated is a "pass-all" constraint that always returns all indices in the range [0..context.size()) without consulting indices. To implement this correctly, such constraint should read indices from indices and return all of them.

Note that this method may be called without a prior call to validate(java.util.List<java.lang.String>). The implementation's behaviour is undefined in this case. However, such call may only originate from inside Structure plugin, since all methods in StructureQuery that execute the query validate it first, and don't run it if reports any errors.

Parameters:

indices - increasing indices into the forest being searched; the implementation should test them and return those of them that pass the constraint

arguments - list of arguments passed to this constraint in some StructureQuery: not null, its elements are not null

context - contains forest being searched and some row resolution methods

Returns:

a sequence of matching indices in the increasing order