From ccff90b211249373b9190250c7ed960ce244d4e9 Mon Sep 17 00:00:00 2001 From: Gavin Date: Thu, 5 Jan 2023 22:52:31 +0100 Subject: [PATCH] example config files in javadoc, and squash some warnings from jdoc tool --- .../src/main/java/org/hibernate/Session.java | 4 +- .../org/hibernate/cfg/AvailableSettings.java | 5 + .../java/org/hibernate/cfg/package-info.java | 109 ++++++++++++++++++ .../java/org/hibernate/dialect/Dialect.java | 2 - .../sqm/tree/domain/AbstractSqmFrom.java | 2 +- .../query/sqm/tree/expression/SqmFormat.java | 2 +- .../SqmJpaCriteriaParameterWrapper.java | 2 +- hibernate-core/src/main/javadoc/overview.html | 5 +- release/src/release/javadoc/overview.html | 5 +- 9 files changed, 125 insertions(+), 11 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java index 7bcaeb4356..ccba71529b 100644 --- a/hibernate-core/src/main/java/org/hibernate/Session.java +++ b/hibernate-core/src/main/java/org/hibernate/Session.java @@ -118,7 +118,7 @@ import jakarta.persistence.criteria.CriteriaUpdate; * An easy way to be sure that session and transaction management is being done correctly * is to {@linkplain SessionFactory#inTransaction(Consumer) let the factory do it}: * 
- * sessionFactory.inTransaction(session -> {
+ * sessionFactory.inTransaction(session -> {
  *     //do the work
  *     ...
  * });
@@ -127,7 +127,7 @@ import jakarta.persistence.criteria.CriteriaUpdate;
  * A session may be used to {@linkplain #doWork(Work) execute JDBC work} using its JDBC
  * connection and transaction:
  * 
- * session.doWork(connection -> {
+ * session.doWork(connection -> {
  *     try ( PreparedStatement ps = connection.prepareStatement( " ... " ) ) {
  *         ps.execute();
  *     }
diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
index ff8298c1d0..379da34a28 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
@@ -44,6 +44,11 @@ import jakarta.persistence.criteria.CriteriaUpdate;
  *     
  • via {@link Configuration#setProperty(String, String)}, or
  *     
  • via {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder#applySetting(String, Object)}.
  * 
+ * 
    
+ * Note that Hibernate does not distinguish between JPA-defined configuration
+ * properties and "native" configuration properties. Any property listed here
+ * may be used to configure Hibernate no matter what configuration mechanism
+ * or bootstrap API is used.
  *
  * @author Steve Ebersole
  */
diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/package-info.java b/hibernate-core/src/main/java/org/hibernate/cfg/package-info.java
index 44d72c9495..57d2815ecb 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/package-info.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/package-info.java
@@ -17,5 +17,114 @@
  * 
    
  * Note that all the real meat behind these APIs is defined in the package
  * {@link org.hibernate.boot}.
+ * 
    
+ * Configuration properties may be specified:
+ * 
      
+ * 
    • in Java code that {@linkplain org.hibernate.cfg.Configuration#setProperty
+ *     configures} Hibernate,
+ * 
    • in a JPA configuration file named {@code persistence.xml},
+ * 
    • in a native configuration file named {@code hibernate.cfg.xml},
+ * 
    • in a file named {@code hibernate.properties}, or
+ * 
    • using some container-specific configuration facility, for example,
+ *     Quarkus configuration properties.
+ * 
    
+ * 
    
+ * We now present a couple of example configuration files.
+ *
+ * 
    Example JPA configuration file
    
+ *
+ * The following JPA configuration may be specified in a file named {@code persistence.xml}:
+ *
+ * 
    {@code 
+ *
+ *     
+ *
+ *         org.hibernate.orm.example.Author
+ *         org.hibernate.orm.example.Book
+ *
+ *         
+ *
+ *             
+ *             
+ *
+ *             
+ *             
+ *             
+ *
+ *             
+ *             
+ *             
+ *             
+ *
+ *             
+ *             
+ *
+ *             
+ *             
+ *             
+ *             
+ *
+ *         
+ *     
+ *
+ * }
    
+ *
+ * The JPA configuration file is necessary when bootstrapping Hibernate via
+ * {@link jakarta.persistence.Persistence#createEntityManagerFactory(java.lang.String)}.
+ *
+ * 
    Example native configuration file
    
+ *
+ * The following configuration may be specified in a file named {@code hibernate.cfg.xml}:
+ *
+ * 
    {@code 
+ * 
+ *
+ * 
+ *     
+ *         
+ *         jdbc:postgresql://localhost/library
+ *
+ *         
+ *         hibernate
+ *         hibernate
+ *
+ *         
+ *         10
+ *         PT1s
+ *         PT10s
+ *
+ *         
+ *         create
+ *
+ *         
+ *         true
+ *         true
+ *         true
+ *
+ *         
+ *         10
+ *
+ *         
+ *         
+ *         
+ *
+ *     
+ * }
    
+ *
+ * The native configuration file is used when configuring Hibernate via
+ * {@link org.hibernate.cfg.Configuration#configure()} or
+ * {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder#configure()}.
  */
 package org.hibernate.cfg;
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java
index be7fb06e4f..25d462bcbc 100644
--- a/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java
+++ b/hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java
@@ -2145,8 +2145,6 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
 	 * @param lockOptions The lock options to apply
 	 * @param tableName The name of the table to which to apply the lock hint.
 	 * @return The table with any required lock hints.
-	 *
-	 * @author Helge Schulz
 	 */
 	public String appendLockHint(LockOptions lockOptions, String tableName){
 		return tableName;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/domain/AbstractSqmFrom.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/domain/AbstractSqmFrom.java
index 495fd2b776..06869348a4 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/domain/AbstractSqmFrom.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/domain/AbstractSqmFrom.java
@@ -104,7 +104,7 @@ public abstract class AbstractSqmFrom extends AbstractSqmPath implements
 	}
 
 	/**
-	 * Intended for use with {@link SqmTreatedRoot} -> {@link SqmRoot}
+	 * Intended for use with {@link SqmTreatedRoot} to {@link SqmRoot}
 	 */
 	protected AbstractSqmFrom(
 			NavigablePath navigablePath,
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmFormat.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmFormat.java
index e54ea355be..61ae7431dd 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmFormat.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmFormat.java
@@ -15,7 +15,7 @@ import org.hibernate.query.sqm.SqmExpressible;
 import org.hibernate.query.sqm.tree.SqmCopyContext;
 
 /**
- * Effectively a query-literal but we want to handle it specially in the SQM -> SQL AST conversion
+ * Effectively a query-literal but we want to handle it specially in the SQM to SQL AST conversion
  *
  * @author Gavin King
  */
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmJpaCriteriaParameterWrapper.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmJpaCriteriaParameterWrapper.java
index 249a320b04..b2569b14e3 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmJpaCriteriaParameterWrapper.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/expression/SqmJpaCriteriaParameterWrapper.java
@@ -96,7 +96,7 @@ public class SqmJpaCriteriaParameterWrapper
 	 * as part of {@link SemanticQueryWalker#visitJpaCriteriaParameter}.  This wrapper
 	 * is intended just for representing unique SqmParameter references for each
 	 * JpaCriteriaParameter occurrence in the SQM true as part of the {@link org.hibernate.query.QueryParameter}
-	 * -> {@link SqmParameter} -> {@link JdbcParameter} transformation.
+	 * to {@link SqmParameter} to {@link JdbcParameter} transformation.
 	 * Each occurrence requires a unique SqmParameter to make sure we ultimately get the complete
 	 * set of JdbcParameter references
 	 */
diff --git a/hibernate-core/src/main/javadoc/overview.html b/hibernate-core/src/main/javadoc/overview.html
index 1e38c9e63c..8415146b4c 100644
--- a/hibernate-core/src/main/javadoc/overview.html
+++ b/hibernate-core/src/main/javadoc/overview.html
@@ -126,8 +126,9 @@ mappings as an alternative.
     container-managed transactions.
 
    
 
    
-    A comprehensive list of configuration properties understood by Hibernate may be found in the
-    class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
+    Example configuration files for JPA and native usage may be found {@linkplain org.hibernate.cfg
+    here}. A comprehensive list of configuration properties understood by Hibernate may be found in
+    the class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
     to use a tiny handful of them.
 
    
 
diff --git a/release/src/release/javadoc/overview.html b/release/src/release/javadoc/overview.html
index e3f7a16e5e..eb6ed96692 100644
--- a/release/src/release/javadoc/overview.html
+++ b/release/src/release/javadoc/overview.html
@@ -126,8 +126,9 @@ mappings as an alternative.
     container-managed transactions.
 
    
 
    
-    A comprehensive list of configuration properties understood by Hibernate may be found in the
-    class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
+    Example configuration files for JPA and native usage may be found {@linkplain org.hibernate.cfg
+    here}. A comprehensive list of configuration properties understood by Hibernate may be found in
+    the class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
     to use a tiny handful of them.