From 58e9c2a0fcd7b577fb57a8526c5bc742dbab764a Mon Sep 17 00:00:00 2001
From: Gavin <gavin@hibernate.org>
Date: Wed, 16 Nov 2022 17:47:50 +0100
Subject: [PATCH] use default noop methods on SessionEventListener

- also, mark it @Incubating, as was already documented
- improve the jdoc for SessionEventListener and StatementInspector
---
 .../org/hibernate/SessionEventListener.java   | 57 +++++++++++--------
 .../resource/jdbc/spi/StatementInspector.java | 23 ++++++--
 2 files changed, 51 insertions(+), 29 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/SessionEventListener.java b/hibernate-core/src/main/java/org/hibernate/SessionEventListener.java
index effca9c6ca..27598d94e6 100644
--- a/hibernate-core/src/main/java/org/hibernate/SessionEventListener.java
+++ b/hibernate-core/src/main/java/org/hibernate/SessionEventListener.java
@@ -9,44 +9,55 @@
 import java.io.Serializable;
 
 /**
- * NOTE : Consider this an incubating API, likely to change as wider usage indicates changes that need to be made
+ * Implemented by custom listeners that respond to low-level events
+ * involving interactions between the {@link Session} and the database
+ * or second-level cache.
+ * <p>
+ * A {@code SessionEventListener} class applying to all newly-created
+ * sessions may be registered using the configuration property
+ * {@value org.hibernate.cfg.AvailableSettings#AUTO_SESSION_EVENTS_LISTENER}.
+ * A new instance of the class will be created for each new session.
+ * <p>
+ * <em>This an incubating API, subject to change.</em>
  *
  * @see org.hibernate.cfg.AvailableSettings#AUTO_SESSION_EVENTS_LISTENER
+ * @see SessionBuilder#eventListeners(SessionEventListener...)
  *
  * @author Steve Ebersole
  */
+@Incubating
 public interface SessionEventListener extends Serializable {
-	void transactionCompletion(boolean successful);
+	default void transactionCompletion(boolean successful) {}
 
-	void jdbcConnectionAcquisitionStart();
-	void jdbcConnectionAcquisitionEnd();
+	default void jdbcConnectionAcquisitionStart() {}
+	default void jdbcConnectionAcquisitionEnd() {}
 
-	void jdbcConnectionReleaseStart();
-	void jdbcConnectionReleaseEnd();
+	default void jdbcConnectionReleaseStart() {}
+	default void jdbcConnectionReleaseEnd() {}
 
-	void jdbcPrepareStatementStart();
-	void jdbcPrepareStatementEnd();
+	default void jdbcPrepareStatementStart() {}
+	default void jdbcPrepareStatementEnd() {}
 
-	void jdbcExecuteStatementStart();
-	void jdbcExecuteStatementEnd();
+	default void jdbcExecuteStatementStart() {}
+	default void jdbcExecuteStatementEnd() {}
 
-	void jdbcExecuteBatchStart();
-	void jdbcExecuteBatchEnd();
+	default void jdbcExecuteBatchStart() {}
+	default void jdbcExecuteBatchEnd() {}
 
-	void cachePutStart();
-	void cachePutEnd();
+	default void cachePutStart() {}
+	default void cachePutEnd() {}
 
-	void cacheGetStart();
-	void cacheGetEnd(boolean hit);
+	default void cacheGetStart() {}
+	default void cacheGetEnd(boolean hit) {}
 
-	void flushStart();
-	void flushEnd(int numberOfEntities, int numberOfCollections);
+	default void flushStart() {}
+	default void flushEnd(int numberOfEntities, int numberOfCollections) {}
 
-	void partialFlushStart();
-	void partialFlushEnd(int numberOfEntities, int numberOfCollections);
+	default void partialFlushStart() {}
+	default void partialFlushEnd(int numberOfEntities, int numberOfCollections) {}
 
-	void dirtyCalculationStart();
-	void dirtyCalculationEnd(boolean dirty);
+	default void dirtyCalculationStart() {}
+	default void dirtyCalculationEnd(boolean dirty) {}
 
-	void end();
+	default void end() {}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/StatementInspector.java b/hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/StatementInspector.java
index d9d4013410..81103e5baf 100644
--- a/hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/StatementInspector.java
+++ b/hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/StatementInspector.java
@@ -9,24 +9,35 @@
 import java.io.Serializable;
 
 /**
- * Contract to allow inspection (and swapping) of SQL to be prepared.
- * <p>
+ * Implementors may inspect and even process each SQL command issued
+ * by a session, before a {@linkplain java.sql.PreparedStatement JDBC
+ * statement} is prepared. A {@code StatementInspector} may be either:
+ * <ul>
+ * <li>shared by all sessions created by a given session factory, in
+ *     which case it must be thread-safe, or
+ * <li>a dedicated instance {@linkplain
+ *     org.hibernate.SessionBuilder#statementInspector registered}
+ *     for a certain session.
+ * </ul>
  * An implementation may be specified via the configuration property
  * {@value org.hibernate.cfg.AvailableSettings#STATEMENT_INSPECTOR}.
+ * An implementation registered this way is shared between sessions.
  *
+ * @see org.hibernate.cfg.AvailableSettings#STATEMENT_INSPECTOR
  * @see org.hibernate.boot.SessionFactoryBuilder#applyStatementInspector(StatementInspector)
+ * @see org.hibernate.SessionBuilder#statementInspector(StatementInspector)
  *
  * @author Steve Ebersole
  */
 public interface StatementInspector extends Serializable {
 	/**
-	 * Inspect the given SQL, possibly returning a different SQL to be used instead.
-	 * Note that returning {@code null} is interpreted as returning the same SQL as
-	 * was passed.
+	 * Inspect the given SQL command, possibly returning a different
+	 * SQL command to be used instead. A {@code null} return value is
+	 * interpreted as if the method had returned its argument.
 	 *
 	 * @param sql The SQL to inspect
 	 *
-	 * @return The SQL to use; may be {@code null}
+	 * @return The processed SQL to use; may be {@code null}
 	 */
 	String inspect(String sql);
 }