com.almworks.jira.structure.api.query

Class StructureQueryBuilder<B extends StructureQueryBuilder<B>>

java.lang.Object

com.almworks.jira.structure.api.query.StructureQueryBuilder<B>

Direct Known Subclasses:

StructureQueryBuilder.Head, StructureQueryBuilder.Sub

@PublicApi
public class StructureQueryBuilder<B extends StructureQueryBuilder<B>>
extends Object

StructureQueryBuilder allows you to build a structure query with a fluent interface. You begin the building process with begin() and end it with StructureQueryBuilder.Head.end(); if the Java compiler accepts the resulting expression, it is also a syntactically valid StructuredJQL expression.

A structure query consists of constraints that select rows in a forest, connected with OR and AND; each constraint can be negated. A constraint can be either a basic or a relational constraint.

Working example (assumes that begin() is statically imported):

     Query typeEpic = JqlQueryBuilder.newBuilder().where().issueType("Epic").buildQuery();
     Query typeTask = JqlQueryBuilder.newBuilder().where().issueType("Task").buildQuery();
     Query versionQuery = JqlQueryBuilder.newBuilder().where().fixVersion("5.2.11", "6.0").buildQuery();
     Query unresolved = JqlQueryBuilder.newBuilder().where().unresolved().buildQuery();
 
     StructureQuery q1 = begin().jql(unresolved).end();
     StructureQuery q2 = begin().root().end();
     StructureQuery q3 = begin().parent.is.empty().end();
     StructureQuery q4 = begin().child.in.issueKeys("TS-129", "TS-239").end();
     StructureQuery q5 = begin().child.of.issueKeys("TS-129", "TS-239").end();
     StructureQuery q6 = begin().ancestor.or().issue.in.jql(versionQuery).end();
     StructureQuery q7 = begin().issue.or().descendant.of.jql(versionQuery).end();
     StructureQuery q8 = begin().self.or().sibling.of.sub().parent.of.issueKey("TS-129").endsub().end();
     StructureQuery q9 = begin().child.of.sub().child.of.root().endsub().end();
     StructureQuery q10 = begin().prevSibling.is.sub().empty().or.jql(unresolved).endsub().end();
     StructureQuery q11 = begin().sub().root().or.jql(typeEpic).endsub().and.descendant.in.jql(unresolved).end();
     StructureQuery q12 = begin().parent.in.jql(typeEpic).and.issue.notIn.jql(typeTask).end();
     StructureQuery q13 = begin().self.or().descendant.of.constraint("folder", "Future tasks").end(); 
 

Explanation:

1. Query q1 matches all unresolved issues in a forest.
2. Queries q2 and q3 both match all top-level rows.
3. Query q4 matches parents of issue TS-129 and parents of issue TS-239.
4. Query q5 matches sub-rows of issue TS-129 and sub-rows of issue TS-239.
5. Queries q6, q7 both match issues with fix version 5.2.11 or 6.0 and their subtrees.
6. Query q8 matches siblings of TS-129's parents.
7. Query q9 matches rows on the 3rd level of the hierarchy.
8. Query q10 matches all rows such that either all the issues under the same parent that come before them are unresolved, or there are no issues under the same parent that come before them.
9. Query q11 matches all such top-level rows and all such Epics that have unresolved sub-issues at any level.
10. Query q12 matches all rows (both issues and non-issues) under Epics that are not Tasks.
11. Query q13 matches the subtree of folder named "Future tasks".

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	StructureQueryBuilder.BasicConstraintStep<B extends StructureQueryBuilder<B>> This class allows to specify a basic constraint, either on its own, or as the last step of building a relational constraint.
static class	StructureQueryBuilder.Head Object of this class contains the state of the builder; you can finish building the query by calling StructureQueryBuilder.Head.end(), or add more constraints, connecting them with and or or.
static class	StructureQueryBuilder.OpStep<B extends StructureQueryBuilder<B>> This class lets you add operator to the relational constraint being built, or to combine the already added relation with another one via StructureQueryBuilder.OpStep.or().
static class	StructureQueryBuilder.RelationConstraintStartStep<B extends StructureQueryBuilder<B>> This class allows you to continue building relational constraint by adding another relation.
protected static class	StructureQueryBuilder.RelationStepHelper<B extends StructureQueryBuilder<B>>
static class	StructureQueryBuilder.StartStep<B extends StructureQueryBuilder<B>> This class allows you to either build a basic constraint or start building a relational constraint.
protected static class	StructureQueryBuilder.StartStepHelper<B extends StructureQueryBuilder<B>>
static class	StructureQueryBuilder.Sub<B extends StructureQueryBuilder<B>> Object of this class contains the state of the builder inside the currently open parentheses; you can finish building the query in the parentheses and return to the main builder by calling StructureQueryBuilder.Sub.endsub(), or add more constraints inside the parentheses, connecting them with and or or.

Field Summary

Fields

Modifier and Type	Field and Description
StructureQueryBuilder.StartStep<B>	and Starts a new constraint, connected to the previous one with AND.
StructureQueryBuilder.StartStep<B>	or Starts a new constraint, connected to the previous one with OR.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StructureQueryBuilder(StructureQueryBuilder.StartStep<B> and, StructureQueryBuilder.StartStep<B> or)

Method Summary

Modifier and Type	Method and Description
static StructureQueryBuilder.StartStep<StructureQueryBuilder.Head>	begin() This is the starting point for building a Structure query.

Methods inherited from class java.lang.Object

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

Field Detail

and

public final StructureQueryBuilder.StartStep<B extends StructureQueryBuilder<B>> and

Starts a new constraint, connected to the previous one with AND.

Note that AND has higher precedence than OR, so that X OR Y AND Z will mean X OR (Y AND Z). In order to get (X OR Y) AND Z, you'll need to use a sub-query ("parentheses.") To open parentheses, use sub(); to close, use endsub(). You will thus get sub().X.or.Y.endsub().and.Z. For an example, see query q11 in the class documentation.

or

public final StructureQueryBuilder.StartStep<B extends StructureQueryBuilder<B>> or

Starts a new constraint, connected to the previous one with OR.

Note that OR has lower precedence than AND, so that X AND Y OR Z will mean (X AND Y) OR Z. In order to get X AND (Y OR Z), you'll need to use a sub-query ("parentheses.") To open parentheses, use sub(); to close, use endsub(). You will then get X.and.sub().Y.or.Z.endsub(). For an example, see query q11 in the class documentation.

Constructor Detail

StructureQueryBuilder

protected StructureQueryBuilder(StructureQueryBuilder.StartStep<B> and,
                                StructureQueryBuilder.StartStep<B> or)

Method Detail

begin

@NotNull
public static StructureQueryBuilder.StartStep<StructureQueryBuilder.Head> begin()

This is the starting point for building a Structure query.

Returns:

an intermediate object that lets you specify basic and relation constraints