com.atlassian.jira.jql.builder

Interface ValueBuilder

public interface ValueBuilder

A builder used during the construction of JQL conditions for a particular JQL field in a fluent programming style. It is used to specify the value or values of a JQL condition whose operator has already been specified using a ConditionBuilder. For example, a call to ConditionBuilder.eq() will return a ValueBuilder that can be used to specify which value should be matched by the equals operator.

Each JQL condition is essentially structured as name operator operand. When this object is created, it has an implied "name" and "operator". This object can be used to complete the current JQL condition by creating the operand. For example, JqlQueryBuilder.affectedVersion().eq() creates a ValueBuilder whose implied name is "affectedVersion" and whose operator is "=" that can used to complete the JQL condition by filling in the operand.

Generally, it is not possible to passs nulls, empty collections, empty arrays, collections that contain nulls, or arrays that contain nulls to the methods on this interface. Any exceptions to these argument conditions are documented on the method concerned. Passing a method a bad argument will result in a IllegalArgumentException.

JQL values are of two types String and Long. For fields that are resolvable by both Id's and Names (e.g. projects, versions, issue types, components, options etc), the order of resolution depends on the value type. If the JQL value type is long, JIRA will first attempt to find the domain object by Id, if that fails, it will attempt to find the domain object by name with the string value of the long. If the JQL value type is a String, JIRA will first try to find the domain object by name, if that fails AND the string can be parsed into a number, JIRA attempts to find the domain object by id with that number.

Since:

v4.0

See Also:

JqlClauseBuilder, ConditionBuilder, JqlQueryBuilder

Method Summary

Modifier and Type	Method and Description
JqlClauseBuilder	date(Date date) Specify the value that must me matched using the current operator.
JqlClauseBuilder	dates(Collection<Date> dates) Specify the values that must be matched using the current operator.
JqlClauseBuilder	dates(Date... dates) Specify the values that must be matched using the current operator.
JqlClauseBuilder	empty() Finish the current condition such that it looks for empty values.
JqlClauseBuilder	function(String funcName) Finish the current condition such that it matches the value(s) returned from the passed function.
JqlClauseBuilder	function(String funcName, Collection<String> args) Finish the current condition such that it matches the value(s) returned from the passed function.
JqlClauseBuilder	function(String funcName, String... args) Finish the current condition such that it matches the value(s) returned from the passed function.
JqlClauseBuilder	functionCascaingOption(String parent) Finish the current condition such that it matches the value(s) returned from the "cascadingOption" function.
JqlClauseBuilder	functionCascaingOption(String parent, String child) Finish the current condition such that it matches the value(s) returned from the "cascadingOption" function.
JqlClauseBuilder	functionCascaingOptionParentOnly(String parent) Finish the current condition such that it matches the value(s) returned from the "cascadingOption" function.
JqlClauseBuilder	functionCurrentLogin() Finish the current condition such that it matches the value returned from the "currentLogin" function.
JqlClauseBuilder	functionCurrentUser() Finish the current condition such that it matches the value returned from the "currentUser" function.
JqlClauseBuilder	functionIssueHistory() Finish the current condition such that it matches the values returned from the "issueHistory" function.
JqlClauseBuilder	functionLastLogin() Finish the current condition such that it matches the value returned from the "lastLogin" function.
JqlClauseBuilder	functionLinkedIssues(String issue, String... issueLinkTypes) Finish the current condition such that it matches the value(s) returned from the "linkedIssues" function.
JqlClauseBuilder	functionMembersOf(String groupName) Finish the current condition such that it matches the values returned from the "membersOfFunction" function.
JqlClauseBuilder	functionNow() Finish the current condition such that it matches the value returned from the "now" function.
JqlClauseBuilder	functionReleasedVersions(String... projects) Finish the current condition such that it matches the values returned from the "releasedVersions" function.
JqlClauseBuilder	functionRemoteLinksByGlobalId(String... globalIds) Finish the current condition such that it matches the value(s) returned from the "remoteLinksByGlobalId" function.
JqlClauseBuilder	functionStandardIssueTypes() Finish the current condition such that it matches the values returned from the "standardIssueTypes" function.
JqlClauseBuilder	functionSubTaskIssueTypes() Finish the current condition such that it matches the values returned from the "subTaskIssueTypes" function.
JqlClauseBuilder	functionUnreleasedVersions(String... projects) Finish the current condition such that it matches the values returned from the "unreleasedVersions" function.
JqlClauseBuilder	functionUpdatedBy(String user) Finish the current condition that it matches the values of issues ids updated by given user (with optional from and from-to time criteria).
JqlClauseBuilder	functionVotedIssues() Finish the current condition such that it matches the value(s) returned from the "votedIssues" function.
JqlClauseBuilder	functionWatchedIssues() Finish the current condition such that it matches the value(s) returned from the "watchedIssues" function.
JqlClauseBuilder	number(Long value) Finish the current condition such that it matches the passed value.
JqlClauseBuilder	numbers(Collection<Long> values) Finish the current condition such that it matches the passed values.
JqlClauseBuilder	numbers(Long... values) Finish the current condition such that it matches the passed values.
JqlClauseBuilder	operand(Operand operand) Finish the current condition such that it matches the passed operand.
JqlClauseBuilder	operands(Collection<? extends Operand> operands) Finish the current condition such that it matches the passed operands.
JqlClauseBuilder	operands(Operand... operands) Finish the current condition such that it matches the passed operands.
JqlClauseBuilder	string(String value) Finish the current condition such that it matches the passed value.
JqlClauseBuilder	strings(Collection<String> values) Finish the current condition such that it matches the passed values.
JqlClauseBuilder	strings(String... values) Finish the current condition such that it matches the passed values.

Method Detail

string

JqlClauseBuilder string(String value)

Finish the current condition such that it matches the passed value. It essentially creates the condition currentName currentOperator value.

Parameters:

value - the value of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

strings

JqlClauseBuilder strings(String... values)

Finish the current condition such that it matches the passed values. It essentially creates the condition currentName currentOperator (values).

Parameters:

values - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

strings

JqlClauseBuilder strings(Collection<String> values)

Finish the current condition such that it matches the passed values. It essentially creates the condition currentName currentOperator (values).

Parameters:

values - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

number

JqlClauseBuilder number(Long value)

Finish the current condition such that it matches the passed value. It essentially creates the condition current Namecurrent Operator value.

Parameters:

value - the value of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

numbers

JqlClauseBuilder numbers(Long... values)

Finish the current condition such that it matches the passed values. It essentially creates the condition currentName currentOperator (values).

Parameters:

values - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

numbers

JqlClauseBuilder numbers(Collection<Long> values)

Finish the current condition such that it matches the passed values. It essentially creates the condition currentName currentOperator (values).

Parameters:

values - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

operand

JqlClauseBuilder operand(Operand operand)

Finish the current condition such that it matches the passed operand. It essentially creates the condition currentName currentOperator operand.

Parameters:

operand - the value of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

operands

JqlClauseBuilder operands(Operand... operands)

Finish the current condition such that it matches the passed operands. It essentially creates the condition currentName currentOperator (operands).

Parameters:

operands - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

operands

JqlClauseBuilder operands(Collection<? extends Operand> operands)

Finish the current condition such that it matches the passed operands. It essentially creates the condition currentName currentOperator (operands).

Parameters:

operands - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

empty

JqlClauseBuilder empty()

Finish the current condition such that it looks for empty values. It essentially creates the condition currentName currentOperator EMPTY.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

function

JqlClauseBuilder function(String funcName)

Finish the current condition such that it matches the value(s) returned from the passed function. It essentially creates the condition currentName currentOperator funcName().

Parameters:

funcName - the name of the function whose value(s) must be matched.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

function

JqlClauseBuilder function(String funcName,
                          String... args)

Finish the current condition such that it matches the value(s) returned from the passed function. It essentially creates the condition currentName currentOperator funcName(arg1, arg2, arg3, ..., arg4).

Parameters:

funcName - the name of the function whose value(s) must be matched.

args - the arguments to be passed to the function. Cannot be null or contain null values.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

function

JqlClauseBuilder function(String funcName,
                          Collection<String> args)

Finish the current condition such that it matches the value(s) returned from the passed function. It essentially creates the condition currentName currentOperator funcName(arg1, arg2, arg3, ..., arg4).

Parameters:

funcName - the name of the function whose value(s) must be matched.

args - the arguments to be passed to the function. Cannot be null or contain null values.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionStandardIssueTypes

JqlClauseBuilder functionStandardIssueTypes()

Finish the current condition such that it matches the values returned from the "standardIssueTypes" function. This function returns all JIRA issue types that can be associated with top level issues. Only works when sub-tasks are enabled in JIRA. It essentially adds the condition currentName currentOperator standardIssueTypes().

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionSubTaskIssueTypes

JqlClauseBuilder functionSubTaskIssueTypes()

Finish the current condition such that it matches the values returned from the "subTaskIssueTypes" function. This function returns all JIRA issue types that can associated with sub-tasks. Only works when sub-tasks are enabled in JIRA. It essentially adds the condition currentName currentOperator subTaskIssueTypes().

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionMembersOf

JqlClauseBuilder functionMembersOf(String groupName)

Finish the current condition such that it matches the values returned from the "membersOfFunction" function. This function returns all JIRA users that are a members of the passed group. It essentially adds the condition currentName currentOperator membersOf("groupName") to the query.

Parameters:

groupName - the name of the group to search. Cannot be null.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionCurrentUser

JqlClauseBuilder functionCurrentUser()

Finish the current condition such that it matches the value returned from the "currentUser" function. This function returns the currently logged in JIRA user. It essentially adds the condition currentName currentOperator currentUser() to the query.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionIssueHistory

JqlClauseBuilder functionIssueHistory()

Finish the current condition such that it matches the values returned from the "issueHistory" function. This function returns the user history for the currently logged in user. It essentially adds the condition currentName currentOperator isssueHistory() to the query.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionReleasedVersions

JqlClauseBuilder functionReleasedVersions(String... projects)

Finish the current condition such that it matches the values returned from the "releasedVersions" function. This function returns all the released versions for the specified projects. Passing no projects will return all released versions in JIRA. It essentially adds the condition currentName currentOperator releasedVersions(projects) to the query.

Parameters:

projects - the projects to add to the condition. Each value can be a project's name (e.g. "JIRA), its key ("e.g. JRA") or its internal JIRA id (e.g. "10000"). Must not be null or contain any null values.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionUnreleasedVersions

JqlClauseBuilder functionUnreleasedVersions(String... projects)

Finish the current condition such that it matches the values returned from the "unreleasedVersions" function. This function returns all the unreleased versions for the specified projects. Passing no projects will return all unreleased versions in JIRA. It essentially adds the condition currentName currentOperator unreleasedVersions(projects) to the query.

Parameters:

projects - the projects to add to the condition. Each value can be project's name (e.g. "JIRA), its key ("e.g. JRA") or its internal JIRA id (e.g. "10000"). Must not be null or contain any null values.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionNow

JqlClauseBuilder functionNow()

Finish the current condition such that it matches the value returned from the "now" function. This function returns the time when it is run. It essentially adds the condition currentName currentOperator now() to the query.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionWatchedIssues

JqlClauseBuilder functionWatchedIssues()

Finish the current condition such that it matches the value(s) returned from the "watchedIssues" function. This function returns all the issues the current user is watching. It essentially adds the condition currentName currentOperator watchedIssues() to the query.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionVotedIssues

JqlClauseBuilder functionVotedIssues()

Finish the current condition such that it matches the value(s) returned from the "votedIssues" function. This function returns all the issues the current user has voted for. It essentially adds the condition currentName currentOperator votedIssues() to the query.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionLinkedIssues

JqlClauseBuilder functionLinkedIssues(String issue,
                                      String... issueLinkTypes)

Finish the current condition such that it matches the value(s) returned from the "linkedIssues" function. This function returns the issues that are linked from the passed issue. It essentially adds the condition currentName currentOperator issueType(issue, issueLikeTyes) to the query.

Parameters:

issue - the issue whose links should be followed. Can be an issue key or issue id as a string. Cannot be null.

issueLinkTypes - the list of issueLinkTypes to follow. An empty value indicates that all links should be followed. Cannot contain nulls.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionUpdatedBy

JqlClauseBuilder functionUpdatedBy(String user)

Finish the current condition that it matches the values of issues ids updated by given user (with optional from and from-to time criteria). Issue is considered updated by user if it any of it's fields were modified or it's comment is added, edited or deleted.

Parameters:

user - - user whose activity should concern the returned issues

Returns:

functionRemoteLinksByGlobalId

JqlClauseBuilder functionRemoteLinksByGlobalId(String... globalIds)

Finish the current condition such that it matches the value(s) returned from the "remoteLinksByGlobalId" function. This function returns the issues that are associated with remote issue links whose globalId is equals to any of the passed globalIds. It essentially adds the condition currentName currentOperator remoteLinksByGlobalId(globalIds) to the query.

Parameters:

globalIds - the globalIds to be used to search for remote issue links and then the issues that are associated with those links.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionCascaingOption

JqlClauseBuilder functionCascaingOption(String parent)

Finish the current condition such that it matches the value(s) returned from the "cascadingOption" function. It essentially adds the condition currentName currentOperator cascadingOption(parent).

Parameters:

parent - the first argument to the "cascadingOption" function. Cannot be null.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionCascaingOption

JqlClauseBuilder functionCascaingOption(String parent,
                                        String child)

Finish the current condition such that it matches the value(s) returned from the "cascadingOption" function. It essentially adds the condition currentName currentOperator cascadingOption(parent, child).

Parameters:

parent - the first argument to the "cascadingOption" function. Cannot be null.

child - the second argument to the "cascadingOption" function. Cannot be null.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionCascaingOptionParentOnly

JqlClauseBuilder functionCascaingOptionParentOnly(String parent)

Finish the current condition such that it matches the value(s) returned from the "cascadingOption" function. It essentially adds the condition currentName currentOperator cascadingOption(parent, "none").

Parameters:

parent - parent the first argument to the "cascadingOption" function. Cannot be null.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionLastLogin

JqlClauseBuilder functionLastLogin()

Finish the current condition such that it matches the value returned from the "lastLogin" function. This functions returns the time when the current user previously logged in.

Returns:

the builder of the overall JQL query

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

functionCurrentLogin

JqlClauseBuilder functionCurrentLogin()

Finish the current condition such that it matches the value returned from the "currentLogin" function. This functions returns the time when the current user logged in.

Returns:

the builder of the overall JQL query

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

date

JqlClauseBuilder date(Date date)

Specify the value that must me matched using the current operator. It essentially creates the condition currentName currentOperator date.

Parameters:

date - the value of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

dates

JqlClauseBuilder dates(Date... dates)

Specify the values that must be matched using the current operator. It essentially creates the condition currentName currentOperator (dates).

Parameters:

dates - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.

dates

JqlClauseBuilder dates(Collection<Date> dates)

Specify the values that must be matched using the current operator. It essentially creates the condition currentName currentOperator (dates).

Parameters:

dates - the values of the JQL condition.

Returns:

the bulder of the overall JQL query.

Throws:

IllegalStateException - if it is not possible to add a JQL condition given the current state of the builder.