com.atlassian.jira.plugin.jql.function
Interface JqlFunction

All Known Implementing Classes:

AbstractIssueTypeFunction, AbstractJqlFunction, AbstractVersionsFunction, AllReleasedVersionsFunction, AllStandardIssueTypesFunction, AllSubIssueTypesFunction, AllUnreleasedVersionsFunction, CascadeOptionFunction, CurrentUserFunction, IssueHistoryFunction, LinkedIssuesFunction, MembersOfFunction, NowFunction, VotedIssuesFunction, WatchedIssuesFunction

public interface JqlFunction

Functions in JQL can be used to provide values for search criteria. For example, the membersOf("myGroup") JQL function returns a list of the usernames who are members of the group "myGroup". This function can then be used in any JQL clause that operates on a list of usernames. For example, the JQL clause assignee in membersOf("myGroup") returns all issues assigned to a member of the JIRA group "myGroup". This is very powerful, as it removes the need to enumerate over all the members of the group manually.

Implementations of JQL functions need to know how to validate a FunctionOperand (which contains their arguments), and also need to know how to produce QueryLiteral values from that operand. They must also specify whether or not the function produces a list of values or a single value.

The validate and getValues method take the TerminalClause that contained the FunctionOperand on its left-hand side. This can be used to create advanced functionality, such as adjusting the functions result or validation based on the clauses right-hand side value or operator.

For plugin developers wishing to write their own JQL functions - you may find it useful to extend from our provided AbstractJqlFunction. In addition to implementing this interface, you must also provide an XML descriptor for your function. For an example, see JqlFunctionModuleDescriptor.

Since:

v4.0

See Also:

AbstractJqlFunction, JqlFunctionModuleDescriptor

Method Summary

String	getFunctionName()
List<QueryLiteral>	getValues(User searcher, FunctionOperand operand, TerminalClause terminalClause) Gets the unexpanded values provided by the user on input.
void	init(JqlFunctionModuleDescriptor moduleDescriptor) Initialises this pluggable function with it's module descriptor.
boolean	isList() Note: this method should only return false if it will NEVER return more than a single value; if it sometimes returns a single value, but sometimes returns multiple values, the return value of this function should always be true.
MessageSet	validate(User searcher, FunctionOperand operand, TerminalClause terminalClause) Will validate the function operand's arguments and report back any errors.

Method Detail

init

void init(JqlFunctionModuleDescriptor moduleDescriptor)

Initialises this pluggable function with it's module descriptor.

Parameters:

moduleDescriptor - the module descriptor; must not be null.

validate

MessageSet validate(User searcher,
                    FunctionOperand operand,
                    TerminalClause terminalClause)

Will validate the function operand's arguments and report back any errors.

Parameters:

searcher - the user performing the search

operand - the operand to validate

terminalClause - the terminal clause that contains the operand

Returns:

a MessageSet which will contain any validation errors or warnings or will be empty if there is nothing to report; never null.

getValues

List<QueryLiteral> getValues(User searcher,
                             FunctionOperand operand,
                             TerminalClause terminalClause)

Gets the unexpanded values provided by the user on input. This is the output values that will later be transformed into index values.

For example, a function who returns all the released versions of a specified project should return QueryLiterals representing the ids of those versions. For correctness, always opt to return the most specific identifier for the object; if you can return either the id (which is stored in the index) or a string name (that would require resolving to get the index value), choose the id.

Parameters:

searcher - the user performing the search

operand - the operand to get values from

terminalClause - the terminal clause that contains the operand

Returns:

a List of objects that represent this Operands raw values.

isList

boolean isList()

Note: this method should only return false if it will NEVER return more than a single value; if it sometimes returns a single value, but sometimes returns multiple values, the return value of this function should always be true.

Returns:

true if the function can return a list of values; false if it only ever returns a single value.

getFunctionName

String getFunctionName()

Returns:

the name of the function