Package org.hibernate.query.sqm.function

Interface SqmFunctionDescriptor

All Known Implementing Classes:

AbstractArrayContainsFunction, AbstractArrayFillFunction, AbstractArrayIncludesFunction, AbstractArrayIntersectsFunction, AbstractArrayPositionFunction, AbstractArrayPositionsFunction, AbstractArrayRemoveFunction, AbstractArrayTrimFunction, AbstractSqmFunctionDescriptor, AbstractSqmSelfRenderingFunctionDescriptor, ArrayAggFunction, ArrayConcatElementFunction, ArrayConcatFunction, ArrayConstructorFunction, ArrayContainsOperatorFunction, ArrayContainsUnnestFunction, ArrayGetUnnestFunction, ArrayIncludesOperatorFunction, ArrayIncludesUnnestFunction, ArrayIntersectsOperatorFunction, ArrayIntersectsUnnestFunction, ArrayRemoveIndexUnnestFunction, ArrayReplaceUnnestFunction, ArraySetUnnestFunction, ArraySliceUnnestFunction, ArrayToStringFunction, AvgFunction, CaseLeastGreatestEmulation, CastFunction, CastingConcatFunction, CastStrEmulation, ChrLiteralEmulation, CoalesceIfnullEmulation, CockroachArrayFillFunction, ConcatPipeFunction, CountFunction, CurrentFunction, DateTruncEmulation, DB2FormatEmulation, DB2PositionFunction, DB2SubstringFunction, DerbyLpadEmulation, DerbyRpadEmulation, DynamicDispatchFunction, EveryAnyEmulation, ExtractFunction, FormatFunction, H2ArrayContainsFunction, H2ArrayFillFunction, H2ArrayIncludesFunction, H2ArrayIntersectsFunction, H2ArrayPositionFunction, H2ArrayPositionsFunction, H2ArrayRemoveFunction, H2ArrayRemoveIndexFunction, H2ArrayReplaceFunction, H2ArraySetFunction, H2ArrayToStringFunction, HANASpatialAggregate, HANASpatialFunction, HSQLArrayConstructorFunction, HSQLArrayFillFunction, HSQLArrayPositionFunction, HSQLArrayPositionsFunction, HSQLArrayRemoveFunction, HSQLArraySetFunction, HSQLArrayToStringFunction, HypotheticalSetFunction, HypotheticalSetWindowEmulation, InsertSubstringOverlayEmulation, IntegralTimestampaddFunction, InverseDistributionFunction, InverseDistributionWindowEmulation, JdbcEscapeFunctionDescriptor, LengthFunction, ListaggFunction, ListaggGroupConcatEmulation, ListaggStringAggEmulation, LocatePositionEmulation, LpadRpadPadEmulation, MinMaxCaseEveryAnyEmulation, ModeStatsModeEmulation, MultipatternSqmFunctionDescriptor, NamedSqmFunctionDescriptor, NvlCoalesceEmulation, OracleArrayAggEmulation, OracleArrayConcatElementFunction, OracleArrayConcatFunction, OracleArrayConstructorFunction, OracleArrayContainsFunction, OracleArrayFillFunction, OracleArrayGetFunction, OracleArrayIncludesFunction, OracleArrayIntersectsFunction, OracleArrayLengthFunction, OracleArrayPositionFunction, OracleArrayPositionsFunction, OracleArrayRemoveFunction, OracleArrayRemoveIndexFunction, OracleArrayReplaceFunction, OracleArraySetFunction, OracleArraySliceFunction, OracleArrayToStringFunction, OracleArrayTrimFunction, OracleExtractFunction, OracleSpatialFunction, OracleSpatialSQLMMFunction, OracleTruncFunction, OrderByFragmentFunction, PatternBasedSqmFunctionDescriptor, PostgreSQLArrayConcatElementFunction, PostgreSQLArrayConcatFunction, PostgreSQLArrayConstructorFunction, PostgreSQLArrayFillFunction, PostgreSQLArrayPositionFunction, PostgreSQLArrayPositionsFunction, PostgreSQLArrayTrimEmulation, PostgreSQLMinMaxFunction, PostgreSQLTruncFunction, PostgreSQLTruncRoundFunction, QuantifiedLeastGreatestEmulation, SDOGetGeometryType, SDOMethodDescriptor, SDORelateFunction, SqlColumn, 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) 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) 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.

User-written function descriptors may be contributed via a FunctionContributor or by calling Configuration.addSqlFunction(java.lang.String, org.hibernate.query.sqm.function.SqmFunctionDescriptor). The SqmFunctionRegistry exposes methods which simplify the definition of a function, including SqmFunctionRegistry.namedDescriptorBuilder(String) and SqmFunctionRegistry.patternAggregateDescriptorBuilder(String, String).

For example, this code registers a function named prefixes():

 Configuration config = ... ;
 config.addSqlFunction("prefixes",
         new SqmFunctionDescriptor() {
             @Override
             public <T> SelfRenderingSqmFunction<T> generateSqmExpression(
                     List<? extends SqmTypedNode<?>> arguments,
                     ReturnableType<T> impliedResultType,
                     QueryEngine queryEngine) {
                 final SqmFunctionRegistry registry = queryEngine.getSqmFunctionRegistry();
                 final TypeConfiguration types = queryEngine.getTypeConfiguration();
                 return registry.patternDescriptorBuilder("prefix", "(left(?1, character_length(?2)) = ?2)" )
                         .setExactArgumentCount(2)
                         .setParameterTypes(FunctionParameterType.STRING, FunctionParameterType.STRING)
                         .setInvariantType(types.standardBasicTypeForJavaType(Boolean.class))
                         .descriptor()
                         .generateSqmExpression(arguments, impliedResultType, queryEngine);
             }

             @Override
             public ArgumentsValidator getArgumentsValidator() {
                 return new ArgumentTypesValidator(
                         StandardArgumentsValidators.exactly(2),
                         FunctionParameterType.STRING, FunctionParameterType.STRING
                 );
             }
         }
 );
 

The function may be called like this: prefixes('Hibernate',book.title).

See Also:

SqmFunctionRegistry, Configuration.addSqlFunction(java.lang.String, org.hibernate.query.sqm.function.SqmFunctionDescriptor), MetadataBuilder.applySqlFunction(java.lang.String, org.hibernate.query.sqm.function.SqmFunctionDescriptor), FunctionContributor

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)	Like generateSqmExpression(List, ReturnableType, QueryEngine), but also accepts a filter predicate.
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.
<T> SelfRenderingSqmFunction<T>	generateSqmExpression(List<? extends SqmTypedNode<?>> arguments, ReturnableType<T> impliedResultType, QueryEngine queryEngine)	Instantiate this template with the given arguments and expected return type.
default <T> SelfRenderingSqmFunction<T>	generateSqmExpression(ReturnableType<T> impliedResultType, QueryEngine queryEngine)	Convenience for no arguments.
default <T> SelfRenderingSqmFunction<T>	generateSqmExpression(SqmTypedNode<?> argument, ReturnableType<T> impliedResultType, QueryEngine queryEngine)	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)	Like generateSqmExpression(List, ReturnableType, QueryEngine) 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)

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)

Like generateSqmExpression(List, ReturnableType, QueryEngine), 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)

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.

generateWindowSqmExpression

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.

generateSqmExpression

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

Convenience for a single argument.

generateSqmExpression

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

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