com.atlassian.jira.plugin.jql.function

Interface JqlFunction

All Known Implementing Classes:

AbstractDateFunction, AbstractIssueTypeFunction, AbstractJqlFunction, AbstractUserBasedFunction, AbstractUserCapabilityFunction, AbstractVersionsFunction, AllReleasedVersionsFunction, AllStandardIssueTypesFunction, AllSubIssueTypesFunction, AllUnreleasedVersionsFunction, CascadeOptionFunction, ComponentsLeadByUserFunction, CurrentLoginFunction, CurrentUserFunction, EarliestUnreleasedVersionFunction, EchoFunction, EchoJqlFunction, EndOfDayFunction, EndOfMonthFunction, EndOfWeekFunction, EndOfYearFunction, IssueHistoryFunction, LastLoginFunction, LatestReleasedVersionFunction, LinkedIssuesFunction, MembersOfFunction, NowFunction, ProjectsLeadByUserFunction, ProjectsWhereUserHasPermissionFunction, ProjectsWhereUserHasRoleFunction, RemoteLinksByGlobalIdFunction, StartOfDayFunction, StartOfMonthFunction, StartOfWeekFunction, StartOfYearFunction, UpdatedByFunction, VotedIssuesFunction, WatchedIssuesFunction

@PublicSpi
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.

QueryLiterals returned by the getValues(com.atlassian.jira.jql.query.QueryCreationContext, com.atlassian.query.operand.FunctionOperand, com.atlassian.query.clause.TerminalClause) method must have the operand source of the passed in FunctionOperand.

The function must be thread safe. Only one instance of the function is created to service all JQL queries. As a result the function may have multiple threads calling it at the same time.

The function will be executed each time a query using it is run. A query is only going to run as fast as its slowest part, thus the function must be very fast to ensure that queries run as quickly as possible. The function also needs to perform well under concurrent load.

Since:

v4.0

See Also:

AbstractJqlFunction, JqlFunctionModuleDescriptor

Method Summary

Modifier and Type	Method and Description
JiraDataType	getDataType() Provides the JiraDataType that this function handles and creates values for.
String	getFunctionName() The name of the function.
int	getMinimumNumberOfExpectedArguments() This method must return the number of arguments that the function expects to perform its operation correctly.
List<QueryLiteral>	getValues(QueryCreationContext queryCreationContext, 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() This method should return true if the function is meant to be used with the IN or NOT IN operators, that is, if the function should be viewed as returning a list.
MessageSet	validate(ApplicationUser searcher, FunctionOperand operand, TerminalClause terminalClause) Will validate the function operand's arguments and report back any errors.

Method Detail

init

void init(@Nonnull
          JqlFunctionModuleDescriptor moduleDescriptor)

Initialises this pluggable function with it's module descriptor.

Parameters:

moduleDescriptor - the module descriptor; will not be null.

validate

@Nonnull
MessageSet validate(ApplicationUser searcher,
                             @Nonnull
                             FunctionOperand operand,
                             @Nonnull
                             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

@Nonnull
List<QueryLiteral> getValues(@Nonnull
                                      QueryCreationContext queryCreationContext,
                                      @Nonnull
                                      FunctionOperand operand,
                                      @Nonnull
                                      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:

queryCreationContext - the context of query creation

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. Cannot be null.

isList

boolean isList()

This method should return true if the function is meant to be used with the IN or NOT IN operators, that is, if the function should be viewed as returning a list. The method should return false when it is to be used with the other relational operators (e.g. =, !=, <, >, ...) that only work with single values.

As a general rule, if a function is going to return more than one value then it should return true here, otherwise it should return false. This does not necessarily need to be the case. For example, it is possible for function that returns false here to return more than one value when it is run.

Returns:

true if the function can should be considered a list (i.e. work with IN and NOT IN), or false otherwise. In this case it is considered to return a single value (i.e. work with =, !=, <, >, ...).

getMinimumNumberOfExpectedArguments

int getMinimumNumberOfExpectedArguments()

This method must return the number of arguments that the function expects to perform its operation correctly. If the function can accept a variable number of arguments this value should be the lower limit. It is perfectly legal for a function to take no arguments and return 0 for this method.

Returns:

the number of arguments that the function expects to perform its operation correctly. Must be >=0.

getFunctionName

@Nonnull
String getFunctionName()

The name of the function. Multiple calls to this method must return the same result. This means that the function name cannot be internationalised with respect to the searcher.

Returns:

the name of the function. Cannot be null.

getDataType

@Nonnull
JiraDataType getDataType()

Provides the JiraDataType that this function handles and creates values for. This allows us to infer some information about how it will interact with other elements in the system.

For example, if this returns JiraDataTypes.DATE then we know that we can provide values for any clauses that also specify a data type of DATE.

Returns:

the JiraDataType that this function produces values for. Cannot be null.

See Also:

JiraDataTypes