Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

improve some javadoc around settings

This commit is contained in:
Gavin 2022-12-08 11:41:49 +01:00
parent 2c8d6d719b
commit 7376a1cdfb
5 changed files with 78 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
hibernate-core/src/main/java/org/hibernate/ConnectionAcquisitionMode.java
View File

@ -9,20 +9,25 @@ package org.hibernate;
import org.hibernate.internal.util.StringHelper;
/**
* Indicates the manner in which JDBC Connections should be acquired. Inverse to
* {@link ConnectionReleaseMode}.
* Indicates the manner in which JDBC {@linkplain java.sql.Connection connections}
* are acquired. Complementary to {@link ConnectionReleaseMode}.
*
* @author Steve Ebersole
*
* @see org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode
*/
public enum ConnectionAcquisitionMode {
/**
* The Connection will be acquired as soon as the Hibernate Session is opened. This
* also circumvents ConnectionReleaseMode, as the Connection will then be held until the
* Session is closed.
* The {@code Connection} will be acquired as soon as a session is opened.
* <p>
* This circumvents the {@link ConnectionReleaseMode}, as the {@code Connection}
* will then be held until the session is closed.
*/
IMMEDIATELY,
/**
* The legacy behavior. A Connection is only acquired when (if) it is actually needed.
* A {@code Connection} is acquired only when (and if) it's actually needed.
* <p>
* This is the default (and legacy) behavior.
*/
AS_NEEDED;

43
hibernate-core/src/main/java/org/hibernate/ConnectionReleaseMode.java
View File

@ -11,44 +11,55 @@ import java.util.Locale;
import org.hibernate.internal.util.StringHelper;
/**
* Defines the various policies by which Hibernate might release its underlying
* JDBC connection. Inverse of {@link ConnectionAcquisitionMode}.
* Enumerates various policies for releasing JDBC {@linkplain java.sql.Connection
* connections}. Complementary to {@link ConnectionAcquisitionMode}.
*
* @author Steve Ebersole
*
* @see org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode
*/
public enum ConnectionReleaseMode{
/**
* Indicates that JDBC connection should be aggressively released after each
* SQL statement is executed. In this mode, the application <em>must</em>
* explicitly close all iterators and scrollable results. This mode may
* only be used with a JTA datasource.
* Indicates that the JDBC connection should be aggressively released after
* each SQL statement is executed. In this mode, the application must
* <em>explicitly</em> close all iterators and scrollable results.
* <p>
* This mode may only be used with a JTA datasource.
*/
AFTER_STATEMENT,
/**
* Indicates that JDBC connections should be released before each transaction
* commits/rollbacks (works with both JTA-registered synch and HibernateTransaction API).
* This mode may be used with an application server JTA datasource.
* Indicates that the JDBC connection should be released before each transaction
* commits or rolls back.
* <p>
* This works with both resource-local transactions and with JTA-registered
* synchronizations. It may be used with an application server JTA datasource.
*/
BEFORE_TRANSACTION_COMPLETION,
/**
* Indicates that JDBC connections should be released after each transaction
* ends (works with both JTA-registered synch and HibernateTransaction API).
* This mode may not be used with an application server JTA datasource.
* Indicates that the JDBC connection should be released after each transaction
* ends.
* <p>
* This is the default mode starting in 3.1; was previously {@link #ON_CLOSE}.
* This works with both resource-local transactions and with JTA-registered
* synchronizations. But it may not be used with an application server JTA
* datasource.
* <p>
* This is the default mode.
*/
AFTER_TRANSACTION,
/**
* Indicates that connections should only be released when the Session is explicitly closed
* or disconnected; this is the legacy (Hibernate2 and pre-3.1) behavior.
* Indicates that connections should only be released when the session is
* explicitly closed or disconnected.
* <p>
* Prior to Hibernate 3.1, this was the default mode.
*/
ON_CLOSE;
/**
* Alias for {@link ConnectionReleaseMode#valueOf(String)} using upper-case version of the incoming name.
* Alias for {@link ConnectionReleaseMode#valueOf(String)} using uppercase
* version of the incoming name.
*
* @param name The name to parse
*

2
hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java
View File

@ -217,7 +217,7 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate);
/**
* Should generated identifiers be "unset" on entities during a rollback?
* Should the generated identifier be "unset" when an entity is deleted?
*
* @param enabled {@code true} indicates identifiers should be unset; {@code false} indicates not.
*

42
hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
View File

@ -322,7 +322,8 @@ public interface AvailableSettings {
* to use for obtaining JDBC connections, either:
* <ul>
* <li>an instance of {@code ConnectionProvider},
* <li>a {@link Class} representing a class that implements {@code ConnectionProvider}, or
* <li>a {@link Class} representing a class that implements
* {@code ConnectionProvider}, or
* <li>the name of a class that implements {@code ConnectionProvider}.
* </ul>
* <p>
@ -354,10 +355,10 @@ public interface AvailableSettings {
* specified username might be used to:
* <ul>
* <li>create a JDBC connection using
* {@link java.sql.DriverManager#getConnection(String,java.util.Properties)}
* or {@link java.sql.Driver#connect(String,java.util.Properties)}, or
* {@link java.sql.DriverManager#getConnection(String,java.util.Properties)}
* or {@link java.sql.Driver#connect(String,java.util.Properties)}, or
* <li>obtain a JDBC connection from a datasource, using
* {@link javax.sql.DataSource#getConnection(String, String)}.
* {@link javax.sql.DataSource#getConnection(String, String)}.
* </ul>
*
* @see #PASS
@ -1063,7 +1064,14 @@ public interface AvailableSettings {
/**
* Specifies how Hibernate should manage JDBC connections in terms of acquisition
* and release.
* and release, either:
* <ul>
* <li>an instance of the enumeration
* {@link org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode},
* or
* <li>the name of one of its instances.
* </ul>
* The default is {@code DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION}.
*
* @see org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode
* @see org.hibernate.boot.SessionFactoryBuilder#applyConnectionHandlingMode(PhysicalConnectionHandlingMode)
@ -1086,6 +1094,11 @@ public interface AvailableSettings {
String CURRENT_SESSION_CONTEXT_CLASS = "hibernate.current_session_context_class";
/**
* When enabled, specifies that the generated identifier of an entity is unset
* when the entity is {@linkplain org.hibernate.Session#remove(Object) deleted}.
* <p>
* By default, generated identifiers are never unset.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyIdentifierRollbackSupport(boolean)
*/
String USE_IDENTIFIER_ROLLBACK = "hibernate.use_identifier_rollback";
@ -1147,22 +1160,27 @@ public interface AvailableSettings {
String QUERY_STARTUP_CHECKING = "hibernate.query.startup_check";
/**
* Enable ordering of update statements by primary key value.
* Enable ordering of update statements by primary key value, for the purpose of more
* efficient JDBC batching
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyOrderingOfUpdates(boolean)
*/
String ORDER_UPDATES = "hibernate.order_updates";
/**
* Enable ordering of insert statements for the purpose of more efficient JDBC batching.
* Enable ordering of insert statements by primary key value, for the purpose of more
* efficient JDBC batching.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyOrderingOfInserts(boolean)
*/
String ORDER_INSERTS = "hibernate.order_inserts";
/**
* JPA callbacks are enabled by default. Set this to {@code false} to disable them.
* Mostly useful to save a bit of memory when they are not used.
* Allows JPA callbacks (via {@link jakarta.persistence.PreUpdate} and friends) to be
* completely disabled. Mostly useful to save some memory when they are not used.
* <p>
* JPA callbacks are enabled by default. Set this property to {@code false} to disable
* them.
* <p>
* Experimental and will likely be removed as soon as the memory overhead is resolved.
*
@ -1174,10 +1192,12 @@ public interface AvailableSettings {
String JPA_CALLBACKS_ENABLED = "hibernate.jpa_callbacks.enabled";
/**
* Default precedence of null values in {@code ORDER BY} clause.
* Specifies the default {@linkplain NullPrecedence precedence of null values} in the HQL
* {@code ORDER BY} clause, either {@code none}, {@code first}, or {@code last}.
* <p>
* Supported options: {@code none} (default), {@code first}, {@code last}.
* The default is {@code none}.
*
* @see NullPrecedence
* @see org.hibernate.boot.SessionFactoryBuilder#applyDefaultNullPrecedence(NullPrecedence)
*/
String DEFAULT_NULL_ORDERING = "hibernate.order_by.default_null_ordering";

16
hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.java
View File

@ -28,28 +28,28 @@ import static org.hibernate.ConnectionReleaseMode.ON_CLOSE;
*/
public enum PhysicalConnectionHandlingMode {
/**
* The Connection will be acquired as soon as the Session is opened and
* held until the Session is closed. This is the only valid combination
* The {@code Connection} will be acquired as soon as the session is opened
* and held until the session is closed. This is the only valid combination
* including immediate acquisition of the Connection
*/
IMMEDIATE_ACQUISITION_AND_HOLD( IMMEDIATELY, ON_CLOSE ),
/**
* The Connection will be acquired as soon as it is needed and then held
* until the Session is closed. This is the original Hibernate behavior.
* The {@code Connection} will be acquired as soon as it is needed and then
* held until the session is closed. This is the original Hibernate behavior.
*/
DELAYED_ACQUISITION_AND_HOLD( AS_NEEDED, ON_CLOSE ),
/**
* The Connection will be acquired as soon as it is needed; it will be
* The {@code Connection} will be acquired as soon as it is needed; it will be
* released after each statement is executed.
*/
DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT( AS_NEEDED, AFTER_STATEMENT ),
/**
* The Connection will be acquired as soon as it is needed; it will be
* released before commit/rollback.
* The {@code Connection} will be acquired as soon as it is needed; it will be
* released before commit or rollback.
*/
DELAYED_ACQUISITION_AND_RELEASE_BEFORE_TRANSACTION_COMPLETION( AS_NEEDED, BEFORE_TRANSACTION_COMPLETION ),
/**
* The Connection will be acquired as soon as it is needed; it will be
* The {@code Connection} will be acquired as soon as it is needed; it will be
* released after each transaction is completed.
*/
DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION( AS_NEEDED, AFTER_TRANSACTION )