javadoc for creation contexts

Author: gavinking

hibernate-core/src/main/java/org/hibernate/metamodel/mapping/ordering/ast/OrderingExpression.java

@@ -54,7 +54,7 @@ static Expression applyCollation(
 			final SqmToSqlAstConverter converter =
 					creationState instanceof SqmToSqlAstConverter sqmToSqlAstConverter
 							? sqmToSqlAstConverter
-							: new FakeSqmToSqlAstConverter(creationState);
+							: new FakeSqmToSqlAstConverter( creationState );
 			sortExpression =
 					queryEngine.getSqmFunctionRegistry()
 							.findFunctionDescriptor( "collate" )

hibernate-core/src/main/java/org/hibernate/query/sqm/spi/SqmCreationContext.java

@@ -13,31 +13,59 @@
 
 /**
  * The context in which all SQM creations occur.
+ * <p>
+ * Since we need to be able to parse and type check queries completely
+ * outside the usual lifecycle of a Hibernate {@code SessionFactory},
+ * it's extremely important that code which builds SQM trees does not
+ * access the factory or other services or object not exposed by this
+ * context object.
  *
  * @author Steve Ebersole
  */
 @Incubating
 public interface SqmCreationContext extends BindingContext {
+
+	/**
+	 * The {@link QueryEngine}.
+	 */
 	QueryEngine getQueryEngine();
 
+	/**
+	 * The {@link NodeBuilder}.
+	 */
 	default NodeBuilder getNodeBuilder() {
 		return getQueryEngine().getCriteriaBuilder();
 	}
 
 	/**
+	 * Obtain a Java class object with the given fully-qualified
+	 * name. This method may only be used for unmanaged types,
+	 * for example, for {@code select new}, or for references to
+	 * {@code static final} constants or to {@code enum} values.
+	 *
 	 * @apiNote Avoid calling this method, since {@link Class}
 	 *          objects are not available to the query validator
-	 *          in Hibernate Processor at compilation time.
+	 *          in Hibernate Processor at compilation time. If
+	 *          you must call it, be prepared to robustly handle
+	 *          the case in which the class is not present, in
+	 *          which case this method might return something
+	 *          arbitrary like {@code Object[].class}.
 	 */
 	default Class<?> classForName(String className) {
 		return getQueryEngine().getClassLoaderService().classForName( className );
 	}
 
+	/**
+	 * The {@link MappingMetamodel}.
+	 */
 	@Override
 	default MappingMetamodel getMappingMetamodel() {
 		return getQueryEngine().getMappingMetamodel();
 	}
 
+	/**
+	 * The {@link JpaMetamodel}.
+	 */
 	@Override
 	default JpaMetamodel getJpaMetamodel() {
 		return getQueryEngine().getJpaMetamodel();

hibernate-core/src/main/java/org/hibernate/sql/ast/spi/SqlAstCreationContext.java

@@ -13,8 +13,14 @@
 import org.hibernate.type.descriptor.WrapperOptions;
 
 /**
- * The "context" in which creation of SQL AST occurs.  Provides
+ * The "context" in which creation of SQL AST occurs. Provides
  * access to stuff generally needed when creating SQL AST nodes
+ * <p>
+ * Because we would like to be able to render SQL during the
+ * startup cycle, before the {@code SessionFactory} is completely
+ * initialized, code involved in SQL AST creation and rendering
+ * should avoid making use of the {@code SessionFactory}.
+ * Instead, use the objects exposed by this creation context.
  *
  * @author Steve Ebersole
  */