Hibernate ORM - hibernate-core 6.4.4.Final · org.hibernate.query.sqm.function.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 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 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 and Description
public default boolean	Returns: `true` by default alwaysIncludesParentheses() Will a call to the described function always include parentheses?
public default <T> SelfRenderingSqmFunction<T>	generateAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Like `generateSqmExpression(List, ReturnableType, QueryEngine)`, but also accepts a `filter` predicate.
public default <T> SelfRenderingSqmFunction<T>	generateOrderedSetAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, SqmOrderByClause withinGroupClause, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Like `generateSqmExpression(List, ReturnableType, QueryEngine)`, but also accepts a `filter` predicate and an `order by` clause.
public <T> SelfRenderingSqmFunction<T>	generateSqmExpression(List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Instantiate this template with the given arguments and expected return type.
public default <T> SelfRenderingSqmFunction<T>	generateSqmExpression(SqmTypedNode<?> argument, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for a single argument.
public default <T> SelfRenderingSqmFunction<T>	generateSqmExpression(ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for no arguments.
public default <T> SelfRenderingSqmFunction<T>	generateWindowSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, Boolean respectNulls, Boolean fromFirst, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Like `generateSqmExpression(List, ReturnableType, QueryEngine)` but also accepts a `filter` predicate.
public ArgumentsValidator	Returns: an instance of `ArgumentsValidator` getArgumentsValidator() The object responsible for validating arguments of the function.
public default FunctionKind	Returns: `FunctionKind#NORMAL` by default getFunctionKind() What sort of function is this?
public default String	Returns: the signature of the function getSignature(String the function name name) Used only for pretty-printing the function signature in the log.

Method Detail

alwaysIncludesParentheses back to summary

alwaysIncludesParentheses	back to summary
public 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. API Note The most common case, by far, is that a function call requires the parentheses. So this method returns true by default. Returns:boolean `true` by default

public 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.

API Note

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

Returns:boolean: true by default

generateAggregateSqmExpression back to summary

generateAggregateSqmExpression	back to summary
public default <T> SelfRenderingSqmFunction<T> generateAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Like `generateSqmExpression(List, ReturnableType, QueryEngine)`, but also accepts a `filter` predicate. This method is intended for aggregate functions.

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

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

This method is intended for aggregate functions.

generateOrderedSetAggregateSqmExpression back to summary

generateOrderedSetAggregateSqmExpression	back to summary
public default <T> SelfRenderingSqmFunction<T> generateOrderedSetAggregateSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, SqmOrderByClause withinGroupClause, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Like `generateSqmExpression(List, ReturnableType, QueryEngine)`, but also accepts a `filter` predicate and an `order by` clause. This method is intended for ordered set aggregate functions.

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

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

This method is intended for ordered set aggregate functions.

generateSqmExpression	back to summary
public <T> SelfRenderingSqmFunction<T> generateSqmExpression(List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine) 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.

generateSqmExpression

back to summary

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

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.

generateSqmExpression	back to summary
public default <T> SelfRenderingSqmFunction<T> generateSqmExpression(SqmTypedNode<?> argument, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for a single argument.

generateSqmExpression	back to summary
public default <T> SelfRenderingSqmFunction<T> generateSqmExpression(ReturnableType<T> impliedResultType, QueryEngine queryEngine) Convenience for no arguments.

generateWindowSqmExpression back to summary

generateWindowSqmExpression	back to summary
public default <T> SelfRenderingSqmFunction<T> generateWindowSqmExpression(List<? extends SqmTypedNode<?>> arguments, SqmPredicate filter, Boolean respectNulls, Boolean fromFirst, ReturnableType<T> impliedResultType, QueryEngine queryEngine) Like `generateSqmExpression(List, ReturnableType, QueryEngine)` but also accepts a `filter` predicate. This method is intended for window functions.

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

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

This method is intended for window functions.

getArgumentsValidator back to summary

getArgumentsValidator	back to summary
public ArgumentsValidator getArgumentsValidator() The object responsible for validating arguments of the function. Returns:ArgumentsValidator an instance of `ArgumentsValidator`

public ArgumentsValidator getArgumentsValidator()

The object responsible for validating arguments of the function.

Returns:ArgumentsValidator: an instance of ArgumentsValidator

getFunctionKind back to summary

getFunctionKind	back to summary
public default FunctionKind getFunctionKind() What sort of function is this? Returns:FunctionKind `FunctionKind#NORMAL` by default

public default FunctionKind getFunctionKind()

What sort of function is this?

Returns:FunctionKind: FunctionKind#NORMAL by default

getSignature	back to summary
public default String getSignature(String name) Used only for pretty-printing the function signature in the log. Parameters name:String the function name Returns:String the signature of the function

getSignature

back to summary

public default String getSignature(String name)

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

Parameters

name:String: the function name

Returns:String

the signature of the function

public Interface SqmFunctionDescriptor

Method Summary

Method Detail