From edb3c335b2d068520cab07ded52ef5f02e50ab4f Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Mon, 16 Dec 2024 09:15:22 +0100
Subject: [PATCH] javadoc about properties in Configuration

---
 .../java/org/hibernate/cfg/Configuration.java   | 17 +++++++++++++++--
 .../java/org/hibernate/cfg/Environment.java     |  8 ++++----
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java b/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java
index ff5932da18..f38c4efd84 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java
@@ -74,15 +74,28 @@ import jakarta.persistence.SharedCacheMode;
  * <li>{@linkplain #setProperty(String, String) configuration properties}
  *     from various sources, and
  * <li>entity O/R mappings, defined in either {@linkplain #addAnnotatedClass
- *    annotated classes}, or {@linkplain #addFile XML mapping documents}.
+ *     annotated classes}, or {@linkplain #addFile XML mapping documents}.
  * </ul>
  * <p>
  * Note that XML mappings may be expressed using the JPA {@code orm.xml}
  * format, or in Hibernate's legacy {@code .hbm.xml} format.
  * <p>
  * Configuration properties are enumerated by {@link AvailableSettings}.
+ * <p>
+ * When instantiated, an instance of {@code Configuration} has its properties
+ * initially populated from the {@linkplain Environment#getProperties()
+ * environment}, including:
+ * <ul>
+ * <li>JVM {@linkplain System#getProperties() system properties}, and
+ * <li>properties specified in {@code hibernate.properties}.
+ * </ul>
+ * <p>
+ * These initial properties may be completely discarded by calling
+ * {@link #setProperties(Properties)}, or they may be overridden
+ * individually by calling {@link #setProperty(String, String)}.
+ * <p>
  * <pre>
- *  SessionFactory factory = new Configuration()
+ * SessionFactory factory = new Configuration()
  *     // scan classes for mapping annotations
  *     .addAnnotatedClass(Item.class)
  *     .addAnnotatedClass(Bid.class)
diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/Environment.java b/hibernate-core/src/main/java/org/hibernate/cfg/Environment.java
index 3d09ce15b9..caefd691c0 100644
--- a/hibernate-core/src/main/java/org/hibernate/cfg/Environment.java
+++ b/hibernate-core/src/main/java/org/hibernate/cfg/Environment.java
@@ -163,7 +163,7 @@ public final class Environment implements AvailableSettings {
 		}
 
 		try {
-			Properties systemProperties = System.getProperties();
+			final Properties systemProperties = System.getProperties();
 			// Must be thread-safe in case an application changes System properties during Hibernate initialization.
 			// See HHH-8383.
 			synchronized (systemProperties) {
@@ -183,11 +183,11 @@ public final class Environment implements AvailableSettings {
 	}
 
 	/**
-	 * The {@link System#getProperties() system properties}, extended with all
-	 * additional properties specified in {@code hibernate.properties}.
+	 * The {@linkplain System#getProperties() system properties}, extended
+	 * with all additional properties specified in {@code hibernate.properties}.
 	 */
 	public static Properties getProperties() {
-		Properties copy = new Properties();
+		final Properties copy = new Properties();
 		copy.putAll(GLOBAL_PROPERTIES);
 		return copy;
 	}