Polishing

spring-tx/src/main/java/org/springframework/transaction/TransactionDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,13 +24,13 @@ import org.springframework.lang.Nullable;
  *
  * <p>Note that isolation level and timeout settings will not get applied unless
  * an actual new transaction gets started. As only {@link #PROPAGATION_REQUIRED},
- * {@link #PROPAGATION_REQUIRES_NEW} and {@link #PROPAGATION_NESTED} can cause
+ * {@link #PROPAGATION_REQUIRES_NEW}, and {@link #PROPAGATION_NESTED} can cause
  * that, it usually doesn't make sense to specify those settings in other cases.
  * Furthermore, be aware that not all transaction managers will support those
  * advanced features and thus might throw corresponding exceptions when given
  * non-default values.
  *
- * <p>The {@link #isReadOnly() read-only flag} applies to any transaction context,
+ * <p>The {@linkplain #isReadOnly() read-only flag} applies to any transaction context,
  * whether backed by an actual resource transaction or operating non-transactionally
  * at the resource level. In the latter case, the flag will only apply to managed
  * resources within the application, such as a Hibernate {@code Session}.
@@ -46,7 +46,7 @@ public interface TransactionDefinition {
 	/**
 	 * Support a current transaction; create a new one if none exists.
 	 * Analogous to the EJB transaction attribute of the same name.
-	 * <p>This is typically the default setting of a transaction definition,
+	 * <p>This is typically the default setting of a transaction definition
 	 * and typically defines a transaction synchronization scope.
 	 */
 	int PROPAGATION_REQUIRED = 0;
@@ -60,8 +60,8 @@ public interface TransactionDefinition {
 	 * As a consequence, the same resources (a JDBC {@code Connection}, a
 	 * Hibernate {@code Session}, etc) will be shared for the entire specified
 	 * scope. Note that the exact behavior depends on the actual synchronization
-	 * configuration of the transaction manager!
+	 * configuration of the transaction manager.
-	 * <p>In general, use {@code PROPAGATION_SUPPORTS} with care! In particular, do
+	 * <p>In general, use {@code PROPAGATION_SUPPORTS} with care. In particular, do
 	 * not rely on {@code PROPAGATION_REQUIRED} or {@code PROPAGATION_REQUIRES_NEW}
 	 * <i>within</i> a {@code PROPAGATION_SUPPORTS} scope (which may lead to
 	 * synchronization conflicts at runtime). If such nesting is unavoidable, make sure
@@ -87,7 +87,7 @@ public interface TransactionDefinition {
 	 * on all transaction managers. This in particular applies to
 	 * {@link org.springframework.transaction.jta.JtaTransactionManager},
 	 * which requires the {@code jakarta.transaction.TransactionManager} to be
-	 * made available it to it (which is server-specific in standard Jakarta EE).
+	 * made available to it (which is server-specific in standard Jakarta EE).
 	 * <p>A {@code PROPAGATION_REQUIRES_NEW} scope always defines its own
 	 * transaction synchronizations. Existing synchronizations will be suspended
 	 * and resumed appropriately.
@@ -102,7 +102,7 @@ public interface TransactionDefinition {
 	 * on all transaction managers. This in particular applies to
 	 * {@link org.springframework.transaction.jta.JtaTransactionManager},
 	 * which requires the {@code jakarta.transaction.TransactionManager} to be
-	 * made available it to it (which is server-specific in standard Jakarta EE).
+	 * made available to it (which is server-specific in standard Jakarta EE).
 	 * <p>Note that transaction synchronization is <i>not</i> available within a
 	 * {@code PROPAGATION_NOT_SUPPORTED} scope. Existing synchronizations
 	 * will be suspended and resumed appropriately.
@@ -120,7 +120,7 @@ public interface TransactionDefinition {
 
 	/**
 	 * Execute within a nested transaction if a current transaction exists,
-	 * behave like {@link #PROPAGATION_REQUIRED} otherwise. There is no
+	 * behaving like {@link #PROPAGATION_REQUIRED} otherwise. There is no
 	 * analogous feature in EJB.
 	 * <p><b>NOTE:</b> Actual creation of a nested transaction will only work on
 	 * specific transaction managers. Out of the box, this only applies to the JDBC
@@ -134,13 +134,13 @@ public interface TransactionDefinition {
 
 	/**
 	 * Use the default isolation level of the underlying datastore.
-	 * All other levels correspond to the JDBC isolation levels.
+	 * <p>All other levels correspond to the JDBC isolation levels.
 	 * @see java.sql.Connection
 	 */
 	int ISOLATION_DEFAULT = -1;
 
 	/**
-	 * Indicates that dirty reads, non-repeatable reads and phantom reads
+	 * Indicates that dirty reads, non-repeatable reads, and phantom reads
 	 * can occur.
 	 * <p>This level allows a row changed by one transaction to be read by another
 	 * transaction before any changes in that row have been committed (a "dirty read").
@@ -153,8 +153,8 @@ public interface TransactionDefinition {
 	/**
 	 * Indicates that dirty reads are prevented; non-repeatable reads and
 	 * phantom reads can occur.
-	 * <p>This level only prohibits a transaction from reading a row
+	 * <p>This level only prohibits a transaction from reading a row with uncommitted
-	 * with uncommitted changes in it.
+	 * changes in it.
 	 * @see java.sql.Connection#TRANSACTION_READ_COMMITTED
 	 */
 	int ISOLATION_READ_COMMITTED = 2;  // same as java.sql.Connection.TRANSACTION_READ_COMMITTED;
@@ -171,7 +171,7 @@ public interface TransactionDefinition {
 	int ISOLATION_REPEATABLE_READ = 4;  // same as java.sql.Connection.TRANSACTION_REPEATABLE_READ;
 
 	/**
-	 * Indicates that dirty reads, non-repeatable reads and phantom reads
+	 * Indicates that dirty reads, non-repeatable reads, and phantom reads
 	 * are prevented.
 	 * <p>This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ}
 	 * and further prohibits the situation where one transaction reads all rows that

spring-tx/src/main/java/org/springframework/transaction/annotation/Isolation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,8 +19,8 @@ package org.springframework.transaction.annotation;
 import org.springframework.transaction.TransactionDefinition;
 
 /**
- * Enumeration that represents transaction isolation levels for use
+ * Enumeration that represents transaction isolation levels for use with the
- * with the {@link Transactional} annotation, corresponding to the
+ * {@link Transactional @Transactional} annotation, corresponding to the
  * {@link TransactionDefinition} interface.
  *
  * @author Colin Sampaleanu
@@ -30,15 +30,16 @@ import org.springframework.transaction.TransactionDefinition;
 public enum Isolation {
 
 	/**
-	 * Use the default isolation level of the underlying datastore.
+	 * Use the default isolation level of the underlying data store.
-	 * All other levels correspond to the JDBC isolation levels.
+	 * <p>All other levels correspond to the JDBC isolation levels.
 	 * @see java.sql.Connection
 	 */
 	DEFAULT(TransactionDefinition.ISOLATION_DEFAULT),
 
 	/**
-	 * A constant indicating that dirty reads, non-repeatable reads and phantom reads
+	 * A constant indicating that dirty reads, non-repeatable reads, and phantom reads
-	 * can occur. This level allows a row changed by one transaction to be read by
+	 * can occur.
+	 * <p>This level allows a row changed by one transaction to be read by
 	 * another transaction before any changes in that row have been committed
 	 * (a "dirty read"). If any of the changes are rolled back, the second
 	 * transaction will have retrieved an invalid row.
@@ -48,31 +49,33 @@ public enum Isolation {
 
 	/**
 	 * A constant indicating that dirty reads are prevented; non-repeatable reads
-	 * and phantom reads can occur. This level only prohibits a transaction
+	 * and phantom reads can occur.
-	 * from reading a row with uncommitted changes in it.
+	 * <p>This level only prohibits a transaction from reading a row with uncommitted
+	 * changes in it.
 	 * @see java.sql.Connection#TRANSACTION_READ_COMMITTED
 	 */
 	READ_COMMITTED(TransactionDefinition.ISOLATION_READ_COMMITTED),
 
 	/**
 	 * A constant indicating that dirty reads and non-repeatable reads are
-	 * prevented; phantom reads can occur. This level prohibits a transaction
+	 * prevented; phantom reads can occur.
-	 * from reading a row with uncommitted changes in it, and it also prohibits
+	 * <p>This level prohibits a transaction from reading a row with uncommitted changes
-	 * the situation where one transaction reads a row, a second transaction
+	 * in it, and it also prohibits the situation where one transaction reads a row,
-	 * alters the row, and the first transaction rereads the row, getting
+	 * a second transaction alters the row, and the first transaction re-reads the row,
-	 * different values the second time (a "non-repeatable read").
+	 * getting different values the second time (a "non-repeatable read").
 	 * @see java.sql.Connection#TRANSACTION_REPEATABLE_READ
 	 */
 	REPEATABLE_READ(TransactionDefinition.ISOLATION_REPEATABLE_READ),
 
 	/**
-	 * A constant indicating that dirty reads, non-repeatable reads and phantom
+	 * A constant indicating that dirty reads, non-repeatable reads, and phantom
-	 * reads are prevented. This level includes the prohibitions in
+	 * reads are prevented.
-	 * {@code ISOLATION_REPEATABLE_READ} and further prohibits the situation
+	 * <p>This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ}
-	 * where one transaction reads all rows that satisfy a {@code WHERE}
+	 * and further prohibits the situation where one transaction reads all rows that
-	 * condition, a second transaction inserts a row that satisfies that
+	 * satisfy a {@code WHERE} condition, a second transaction inserts a row
-	 * {@code WHERE} condition, and the first transaction rereads for the
+	 * that satisfies that {@code WHERE} condition, and the first transaction
-	 * same condition, retrieving the additional "phantom" row in the second read.
+	 * re-reads for the same condition, retrieving the additional "phantom" row
+	 * in the second read.
 	 * @see java.sql.Connection#TRANSACTION_SERIALIZABLE
 	 */
 	SERIALIZABLE(TransactionDefinition.ISOLATION_SERIALIZABLE);