+ * When a function call is encountered in the text of an HQL query, + * a {@code SqmFunctionDescriptor} for the given name is obtained + * from the {@link SqmFunctionRegistry}, and the + * {@link #generateSqmExpression} method is called with SQM nodes + * representing the invocation arguments. It is the responsibility + * of the {@code SqmFunctionDescriptor} to produce a subtree of SQM + * nodes representing the function invocation. + *
+ * The resulting subtree might be quite complex, since the + * {@code SqmFunctionDescriptor} is permitted to perform syntactic + * de-sugaring. On the other hand, {@link #generateSqmExpression} + * returns {@link 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. * * @author David Channon * @author Steve Ebersole @@ -49,8 +59,10 @@ public interface SqmFunctionDescriptor { TypeConfiguration typeConfiguration); /** - * Like {@link #generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration)} - * but also accepts a filter predicate. This method is intended for aggregate functions. + * Like {@link #generateSqmExpression(List, ReturnableType, QueryEngine, TypeConfiguration)}, + * but also accepts a {@code filter} predicate. + *
+ * This method is intended for aggregate functions.
*/
default
+ * This method is intended for ordered set aggregate functions.
*/
default
+ * This method is intended for window functions.
*/
default
- * SqmFunctionTemplate is generally used for rendering of a function.
- * 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 open-paren we can safely assume the
- * token is a function name. However, if the next token is not an
- * open-paren, the token can still represent a function provided that
- * the function has a "no paren" form in the case of no arguments. E.g.
- * Many databases do not require parentheses on functions like
- * `current_timestamp`, etc. This method helps account for those
- * cases.
+ * 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.
*
- * Note that the most common case, by far, is that a function will always
- * include the parentheses - therefore this return is defined as true by
- * default.
+ * For example, many databases do not require parentheses for functions
+ * like {@code current_timestamp} and friends. This method helps account
+ * for those cases.
+ *
+ * @apiNote The most common case, by far, is that a function call requires
+ * the parentheses. So this method returns true by default.
*
- * see Template#isFunction
+ * @return {@code true} by default
*/
default boolean alwaysIncludesParentheses() {
return true;
}
+ /**
+ * Used only for pretty-printing the function signature in the log.
+ *
+ * @param name the function name
+ * @return the signature of the function
+ */
default String getSignature(String name) {
return name;
}
+ /**
+ * What sort of function is this?
+ *
+ * @return {@link FunctionKind#NORMAL} by default
+ */
default FunctionKind getFunctionKind() {
return FunctionKind.NORMAL;
}
+ /**
+ * The object responsible for validating arguments of the function.
+ *
+ * @return an instance of {@link ArgumentsValidator}
+ */
ArgumentsValidator getArgumentsValidator();
}