Package org.hibernate.query.sqm.function

Interface SqmFunctionDescriptor

All Known Implementing Classes:

AbstractSqmFunctionDescriptor, AbstractSqmSelfRenderingFunctionDescriptor, AvgFunction, CaseLeastGreatestEmulation, CastFunction, CastingConcatFunction, CastStrEmulation, ChrLiteralEmulation, CoalesceIfnullEmulation, ConcatPipeFunction, CountFunction, CurrentFunction, DateTruncEmulation, DB2FormatEmulation, DB2PositionFunction, DB2SubstringFunction, DerbyLpadEmulation, DerbyRpadEmulation, EveryAnyEmulation, ExtractFunction, FormatFunction, HANASpatialAggregate, HANASpatialFunction, HypotheticalSetFunction, HypotheticalSetWindowEmulation, InsertSubstringOverlayEmulation, IntegralTimestampaddFunction, InverseDistributionFunction, InverseDistributionWindowEmulation, JdbcEscapeFunctionDescriptor, LengthFunction, ListaggFunction, ListaggGroupConcatEmulation, ListaggStringAggEmulation, LocatePositionEmulation, LpadRpadPadEmulation, MinMaxCaseEveryAnyEmulation, ModeStatsModeEmulation, MultipatternSqmFunctionDescriptor, NamedSqmFunctionDescriptor, NvlCoalesceEmulation, OracleSpatialFunction, OracleSpatialSQLMMFunction, OracleTruncFunction, OrderByFragmentFunction, PatternBasedSqmFunctionDescriptor, PostgreSQLMinMaxFunction, PostgreSQLTruncFunction, PostgreSQLTruncRoundFunction, QuantifiedLeastGreatestEmulation, SDOGetGeometryType, SDOMethodDescriptor, SDORelateFunction, SqlFunction, SqlServerConvertTruncFunction, SQLServerEveryAnyEmulation, SQLServerFormatEmulation, StandardSQLFunction, STRelateFunction, SybaseTruncFunction, TimestampaddFunction, TimestampdiffFunction, TransactSQLStrFunction, TrimFunction, TruncFunction

public interface SqmFunctionDescriptor

A factory for SQM nodes representing invocations of a certain named function.

When a function call is encountered in the text of an HQL query, a SqmFunctionDescriptor for the given name is obtained from the SqmFunctionRegistry, and the generateSqmExpression(java.util.List<? extends org.hibernate.query.sqm.tree.SqmTypedNode<?>>, org.hibernate.query.ReturnableType<T>, org.hibernate.query.spi.QueryEngine, org.hibernate.type.spi.TypeConfiguration) method is called with SQM nodes representing the invocation arguments. It is the responsibility of the SqmFunctionDescriptor to produce a subtree of SQM nodes representing the function invocation.

The resulting subtree might be quite complex, since the SqmFunctionDescriptor is permitted to perform syntactic de-sugaring. On the other hand, generateSqmExpression(java.util.List<? extends org.hibernate.query.sqm.tree.SqmTypedNode<?>>, org.hibernate.query.ReturnableType<T>, org.hibernate.query.spi.QueryEngine, org.hibernate.type.spi.TypeConfiguration) returns SelfRenderingSqmFunction, which is an object that is permitted to take over the logic of producing the SQL AST subtree, so de-sugaring may also be performed there.

Method Summary

Modifier and Type	Method	Description
default boolean	alwaysIncludesParentheses()	Will a call to the described function always include parentheses?
default <T> SelfRenderingSqmFunction<T>	generateAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, ReturnableType<T> impliedResultType, QueryEngine queryEngine, TypeConfiguration typeConfiguration)	Like generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration), but also accepts a filter predicate.
default <T> SelfRenderingSqmFunction<T>	generateOrderedSetAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, SqmOrderByClause withinGroupClause, ReturnableType<T> impliedResultType, QueryEngine queryEngine, TypeConfiguration typeConfiguration)	Like generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration), but also accepts a filter predicate and an order by clause.
<T> SelfRenderingSqmFunction<T>	generateSqmExpression(List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine, TypeConfiguration typeConfiguration)	Instantiate this template with the given arguments and expected return type.
default <T> SelfRenderingSqmFunction<T>	generateSqmExpression(ReturnableType<T> impliedResultType, QueryEngine queryEngine, TypeConfiguration typeConfiguration)	Convenience for no arguments.
default <T> SelfRenderingSqmFunction<T>	generateSqmExpression(SqmTypedNode<?> argument, ReturnableType<T> impliedResultType, QueryEngine queryEngine, TypeConfiguration typeConfiguration)	Convenience for a single argument.
default <T> SelfRenderingSqmFunction<T>	generateWindowSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, Boolean respectNulls, Boolean fromFirst, ReturnableType<T> impliedResultType, QueryEngine queryEngine, TypeConfiguration typeConfiguration)	Like generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration) but also accepts a filter predicate.
ArgumentsValidator	getArgumentsValidator()	The object responsible for validating arguments of the function.
default FunctionKind	getFunctionKind()	What sort of function is this?
default String	getSignature(String name)	Used only for pretty-printing the function signature in the log.

Method Detail

generateSqmExpression

<T> SelfRenderingSqmFunction<T> generateSqmExpression(List<? extends SqmTypedNode<?>> arguments,
                                                      ReturnableType<T> impliedResultType,
                                                      QueryEngine queryEngine,
                                                      TypeConfiguration typeConfiguration)

Instantiate this template with the given arguments and expected return type. This produces a tree of SQM nodes representing a tree of function invocations. This allows a single HQL function to be defined in terms of other predefined (database independent) HQL functions, simplifying the task of writing HQL functions which are portable between databases.

generateAggregateSqmExpression

default <T> SelfRenderingSqmFunction<T> generateAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments,
                                                                       SqmPredicate filter,
                                                                       ReturnableType<T> impliedResultType,
                                                                       QueryEngine queryEngine,
                                                                       TypeConfiguration typeConfiguration)

Like generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration), but also accepts a filter predicate.

This method is intended for aggregate functions.

generateOrderedSetAggregateSqmExpression

default <T> SelfRenderingSqmFunction<T> generateOrderedSetAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments,
                                                                                 SqmPredicate filter,
                                                                                 SqmOrderByClause withinGroupClause,
                                                                                 ReturnableType<T> impliedResultType,
                                                                                 QueryEngine queryEngine,
                                                                                 TypeConfiguration typeConfiguration)

Like generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration), but also accepts a filter predicate and an order by clause.

This method is intended for ordered set aggregate functions.

generateWindowSqmExpression

default <T> SelfRenderingSqmFunction<T> generateWindowSqmExpression(List<? extends SqmTypedNode<?>> arguments,
                                                                    SqmPredicate filter,
                                                                    Boolean respectNulls,
                                                                    Boolean fromFirst,
                                                                    ReturnableType<T> impliedResultType,
                                                                    QueryEngine queryEngine,
                                                                    TypeConfiguration typeConfiguration)

Like generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration) but also accepts a filter predicate.

This method is intended for window functions.

generateSqmExpression

default <T> SelfRenderingSqmFunction<T> generateSqmExpression(SqmTypedNode<?> argument,
                                                              ReturnableType<T> impliedResultType,
                                                              QueryEngine queryEngine,
                                                              TypeConfiguration typeConfiguration)

Convenience for a single argument.

generateSqmExpression

default <T> SelfRenderingSqmFunction<T> generateSqmExpression(ReturnableType<T> impliedResultType,
                                                              QueryEngine queryEngine,
                                                              TypeConfiguration typeConfiguration)

Convenience for no arguments.

alwaysIncludesParentheses

default boolean alwaysIncludesParentheses()

Will a call to the described function always include parentheses?

Instances of this interface are usually used for rendering of functions. However, there are cases where Hibernate needs to consume a fragment and decide if a token represents a function name. In cases where the token is followed by an opening parenthesis, we can safely assume the token is a function name. Bur if the next token is not an opening parenthesis, the token might still represent a function if the function has a "no paren" form in the case of no arguments.

For example, many databases do not require parentheses for functions like current_timestamp and friends. This method helps account for those cases.

Returns:

true by default

API Note:

The most common case, by far, is that a function call requires the parentheses. So this method returns true by default.

getSignature

default String getSignature(String name)

Used only for pretty-printing the function signature in the log.

Parameters:

name - the function name

Returns:

the signature of the function

getFunctionKind

default FunctionKind getFunctionKind()

What sort of function is this?

Returns:

FunctionKind.NORMAL by default

getArgumentsValidator

ArgumentsValidator getArgumentsValidator()

The object responsible for validating arguments of the function.

Returns:

an instance of ArgumentsValidator