From 5db76293824b48642ee5fa3d47db0ac48f524b0b Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sun, 20 Oct 2024 13:56:46 +0200 Subject: [PATCH] improve jdoc of SQM enums Signed-off-by: Gavin King --- .../org/hibernate/query/sqm/CastType.java | 24 +++++++-------- .../query/sqm/ComparisonOperator.java | 8 +++-- .../query/sqm/DynamicInstantiationNature.java | 2 ++ .../org/hibernate/query/sqm/SetOperator.java | 30 +++++++++++-------- .../hibernate/query/sqm/SqmQuerySource.java | 13 +++++++- .../org/hibernate/query/sqm/TrimSpec.java | 25 ++++++++-------- .../query/sqm/UnaryArithmeticOperator.java | 22 ++++++++------ 7 files changed, 74 insertions(+), 50 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/CastType.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/CastType.java index e0fdfa179b..da57813bec 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/CastType.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/CastType.java @@ -8,8 +8,8 @@ package org.hibernate.query.sqm; * Defines the set of basic types which should be * accepted by the {@code cast()} function on every * platform. - *

- * Note that while almost every database supports + * + * @implNote While almost every database supports * the ANSI {@code cast()} function, the actual type * conversions supported vary widely. Therefore, it * is sometimes necessary to emulate certain type @@ -19,6 +19,11 @@ package org.hibernate.query.sqm; * type, and so type conversions to and from * {@link Boolean} must be emulated. * + * @apiNote This is an SPI type allowing collaboration + * between {@code org.hibernate.dialect} and + * {@code org.hibernate.sqm}. It should never occur in + * APIs visible to the application program. + * * @see org.hibernate.dialect.Dialect#castPattern(CastType, CastType) * * @author Gavin King @@ -33,16 +38,9 @@ public enum CastType { OTHER; public boolean isNumeric() { - switch (this) { - case INTEGER: - case LONG: - case INTEGER_BOOLEAN: - case FLOAT: - case DOUBLE: - case FIXED: - return true; - default: - return false; - } + return switch ( this ) { + case INTEGER, LONG, INTEGER_BOOLEAN, FLOAT, DOUBLE, FIXED -> true; + default -> false; + }; } } diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/ComparisonOperator.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/ComparisonOperator.java index be03e984a6..c6c2a9b30c 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/ComparisonOperator.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/ComparisonOperator.java @@ -5,8 +5,12 @@ package org.hibernate.query.sqm; /** - * Defines the comparison operators. We could also get away with - * only 3 and use negation... + * Enumerates the binary comparison operators. + * + * @apiNote This is an SPI type allowing collaboration + * between {@code org.hibernate.dialect} and + * {@code org.hibernate.sqm}. It should never occur in + * APIs visible to the application program. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/DynamicInstantiationNature.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/DynamicInstantiationNature.java index 380840c118..d89bd4485c 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/DynamicInstantiationNature.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/DynamicInstantiationNature.java @@ -10,6 +10,8 @@ import java.util.Map; /** * Represents the type of instantiation to be performed. * + * @see org.hibernate.query.sqm.tree.select.SqmDynamicInstantiationTarget#getNature + * * @author Steve Ebersole */ public enum DynamicInstantiationNature { diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/SetOperator.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/SetOperator.java index ac04cf8e7e..84f419be50 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/SetOperator.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/SetOperator.java @@ -7,41 +7,45 @@ package org.hibernate.query.sqm; /** * The SQL set operators. * + * @apiNote This is an SPI type. It should never occur + * in APIs visible to the application program. + * * @author Christian Beikov */ public enum SetOperator { /** * Union of sets that removes duplicate rows. */ - UNION("union"), + UNION, /** * Union of bags that retains all elements. */ - UNION_ALL("union all"), + UNION_ALL, /** * Intersection of sets that removes duplicate rows. */ - INTERSECT("intersect"), + INTERSECT, /** * Intersection of bags that retains duplicate matches. */ - INTERSECT_ALL("intersect all"), + INTERSECT_ALL, /** * Exclusion of set elements of the set on the right-hand side. */ - EXCEPT("except"), + EXCEPT, /** * Exclusion of bag elements of the bag on the right-hand side that retains duplicates. */ - EXCEPT_ALL("except all"); - - private final String sqlString; - - private SetOperator(String sqlString) { - this.sqlString = sqlString; - } + EXCEPT_ALL; public String sqlString() { - return sqlString; + return switch (this) { + case UNION -> "union"; + case UNION_ALL -> "union all"; + case INTERSECT -> "intersect"; + case INTERSECT_ALL -> "intersect all"; + case EXCEPT -> "except"; + case EXCEPT_ALL -> "except all"; + }; } } diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/SqmQuerySource.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/SqmQuerySource.java index ca281cfa98..15f5d0cd70 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/SqmQuerySource.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/SqmQuerySource.java @@ -5,14 +5,25 @@ package org.hibernate.query.sqm; /** - * Informational - used to identify the source of an SQM statement. + * Identifies the source of an SQM statement. * * @see org.hibernate.query.sqm.tree.SqmStatement#getQuerySource * * @author Steve Ebersole */ public enum SqmQuerySource { + /** + * The SQM tree represents a query written in HQL or JPQL. + */ HQL, + /** + * The SQM tree was built via the + * {@linkplain org.hibernate.query.criteria.HibernateCriteriaBuilder + * criteria query API}. + */ CRITERIA, + /** + * The SQM tree came from somewhere else. + */ OTHER } diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/TrimSpec.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/TrimSpec.java index aa7d84c947..694b1e6c67 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/TrimSpec.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/TrimSpec.java @@ -5,11 +5,17 @@ package org.hibernate.query.sqm; import jakarta.persistence.criteria.CriteriaBuilder; -import org.hibernate.AssertionFailure; import java.util.Locale; /** + * Variations of the {@code trim()} function. + * + * @apiNote This is an SPI type allowing collaboration + * between {@code org.hibernate.dialect} and + * {@code org.hibernate.sqm}. It should never occur in + * APIs visible to the application program. + * * @author Steve Ebersole */ public enum TrimSpec { @@ -21,17 +27,12 @@ public enum TrimSpec { if ( jpaTs == null ) { return null; } - - switch ( jpaTs ) { - case BOTH: - return BOTH; - case LEADING: - return LEADING; - case TRAILING: - return TRAILING; - default: - throw new AssertionFailure( "Unrecognized JPA TrimSpec" ); - + else { + return switch ( jpaTs ) { + case BOTH -> BOTH; + case LEADING -> LEADING; + case TRAILING -> TRAILING; + }; } } diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/UnaryArithmeticOperator.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/UnaryArithmeticOperator.java index 62d4f6967f..439a9bdb34 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/UnaryArithmeticOperator.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/UnaryArithmeticOperator.java @@ -5,19 +5,23 @@ package org.hibernate.query.sqm; /** + * Enumerates the unary prefix operators. + * + * @apiNote This is an SPI type allowing collaboration + * between {@code org.hibernate.dialect} and + * {@code org.hibernate.sqm}. It should never occur in + * APIs visible to the application program. + * * @author Steve Ebersole */ public enum UnaryArithmeticOperator { - UNARY_PLUS( '+' ), - UNARY_MINUS( '-' ); - - private final char operatorChar; - - UnaryArithmeticOperator(char operatorChar) { - this.operatorChar = operatorChar; - } + UNARY_PLUS, + UNARY_MINUS; public char getOperatorChar() { - return operatorChar; + return switch ( this ) { + case UNARY_PLUS -> '+'; + case UNARY_MINUS -> '-'; + }; } }