added javadoc references to semantic definition of transaction attributes (SPR-7029)

org.springframework.transaction/src/main/java/org/springframework/transaction/TransactionDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2006 the original author or authors.
+ * Copyright 2002-2010 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.
@@ -122,8 +122,8 @@ public interface TransactionDefinition {
 	 * Execute within a nested transaction if a current transaction exists,
 	 * behave like {@link #PROPAGATION_REQUIRED} else. There is no analogous
 	 * feature in EJB.
-	 * <p><b>NOTE:</b> Actual creation of a nested transaction will only work on specific
+	 * <p><b>NOTE:</b> Actual creation of a nested transaction will only work on
-	 * transaction managers. Out of the box, this only applies to the JDBC
+	 * specific transaction managers. Out of the box, this only applies to the JDBC
 	 * {@link org.springframework.jdbc.datasource.DataSourceTransactionManager}
 	 * when working on a JDBC 3.0 driver. Some JTA providers might support
 	 * nested transactions as well.
@@ -142,10 +142,10 @@ public interface TransactionDefinition {
 	/**
 	 * 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
+	 * <p>This level allows a row changed by one transaction to be read by another
-	 * another transaction before any changes in that row have been committed
+	 * transaction before any changes in that row have been committed (a "dirty read").
-	 * (a "dirty read"). If any of the changes are rolled back, the second
+	 * If any of the changes are rolled back, the second transaction will have
-	 * transaction will have retrieved an invalid row.
+	 * retrieved an invalid row.
 	 * @see java.sql.Connection#TRANSACTION_READ_UNCOMMITTED
 	 */
 	int ISOLATION_READ_UNCOMMITTED = Connection.TRANSACTION_READ_UNCOMMITTED;
@@ -162,11 +162,10 @@ public interface TransactionDefinition {
 	/**
 	 * Indicates that dirty reads and non-repeatable reads are prevented;
 	 * phantom reads can occur.
-	 * <p>This level prohibits a transaction from reading a row with
+	 * <p>This level prohibits a transaction from reading a row with uncommitted changes
-	 * uncommitted changes in it, and it also prohibits the situation
+	 * in it, and it also prohibits the situation where one transaction reads a row,
-	 * where one transaction reads a row, a second transaction alters
+	 * a second transaction alters the row, and the first transaction re-reads the row,
-	 * the row, and the first transaction rereads the row, getting
+	 * getting different values the second time (a "non-repeatable read").
-	 * different values the second time (a "non-repeatable read").
 	 * @see java.sql.Connection#TRANSACTION_REPEATABLE_READ
 	 */
 	int ISOLATION_REPEATABLE_READ = Connection.TRANSACTION_REPEATABLE_READ;
@@ -174,13 +173,12 @@ public interface TransactionDefinition {
 	/**
 	 * Indicates that dirty reads, non-repeatable reads and phantom reads
 	 * are prevented.
-	 * <p>This level includes the prohibitions in
+	 * <p>This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ}
-	 * {@link #ISOLATION_REPEATABLE_READ} and further prohibits the
+	 * and further prohibits the situation where one transaction reads all rows that
-	 * situation where one transaction reads all rows that satisfy a
+	 * satisfy a <code>WHERE</code> condition, a second transaction inserts a row
-	 * <code>WHERE</code> condition, a second transaction inserts a
+	 * that satisfies that <code>WHERE</code> condition, and the first transaction
-	 * row that satisfies that <code>WHERE</code> condition, and the
+	 * re-reads for the same condition, retrieving the additional "phantom" row
-	 * first transaction rereads for the same condition, retrieving
+	 * in the second read.
-	 * the additional "phantom" row in the second read.
 	 * @see java.sql.Connection#TRANSACTION_SERIALIZABLE
 	 */
 	int ISOLATION_SERIALIZABLE = Connection.TRANSACTION_SERIALIZABLE;
@@ -209,9 +207,8 @@ public interface TransactionDefinition {
 	 * defined on {@link TransactionDefinition this interface}.
 	 * <p>Only makes sense in combination with {@link #PROPAGATION_REQUIRED}
 	 * or {@link #PROPAGATION_REQUIRES_NEW}.
-	 * <p>Note that a transaction manager that does not support custom
+	 * <p>Note that a transaction manager that does not support custom isolation levels
-	 * isolation levels will throw an exception when given any other level
+	 * will throw an exception when given any other level than {@link #ISOLATION_DEFAULT}.
-	 * than {@link #ISOLATION_DEFAULT}.
 	 * @return the isolation level
 	 */
 	int getIsolationLevel();
@@ -221,9 +218,8 @@ public interface TransactionDefinition {
 	 * <p>Must return a number of seconds, or {@link #TIMEOUT_DEFAULT}.
 	 * <p>Only makes sense in combination with {@link #PROPAGATION_REQUIRED}
 	 * or {@link #PROPAGATION_REQUIRES_NEW}.
-	 * <p>Note that a transaction manager that does not support timeouts
+	 * <p>Note that a transaction manager that does not support timeouts will throw
-	 * will throw an exception when given any other timeout than
+	 * an exception when given any other timeout than {@link #TIMEOUT_DEFAULT}.
-	 * {@link #TIMEOUT_DEFAULT}.
 	 * @return the transaction timeout
 	 */
 	int getTimeout();
@@ -237,9 +233,9 @@ public interface TransactionDefinition {
 	 * ({@link #PROPAGATION_SUPPORTS}). In the latter case, the flag will
 	 * only apply to managed resources within the application, such as a
 	 * Hibernate <code>Session</code>.
-	 * <p>This just serves as a hint for the actual transaction subsystem;
+<<	 * <p>This just serves as a hint for the actual transaction subsystem;
 	 * it will <i>not necessarily</i> cause failure of write access attempts.
-	 * A transaction manager that cannot interpret the read-only hint will
+	 * A transaction manager which cannot interpret the read-only hint will
 	 * <i>not</i> throw an exception when asked for a read-only transaction.
 	 * @return <code>true</code> if the transaction is to be optimized as read-only 
 	 * @see org.springframework.transaction.support.TransactionSynchronization#beforeCommit(boolean)
@@ -251,10 +247,8 @@ public interface TransactionDefinition {
 	 * Return the name of this transaction. Can be <code>null</code>.
 	 * <p>This will be used as the transaction name to be shown in a
 	 * transaction monitor, if applicable (for example, WebLogic's).
-	 * <p>In case of Spring's declarative transactions, the exposed name
+	 * <p>In case of Spring's declarative transactions, the exposed name will be
-	 * must (and will) be the
+	 * the <code>fully-qualified class name + "." + method name</code> (by default).
-	 * <code>fully-qualified class name + "." + method name</code>
-	 * (by default).
 	 * @return the name of this transaction
 	 * @see org.springframework.transaction.interceptor.TransactionAspectSupport
 	 * @see org.springframework.transaction.support.TransactionSynchronizationManager#getCurrentTransactionName()

org.springframework.transaction/src/main/java/org/springframework/transaction/annotation/Transactional.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2010 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.
@@ -36,10 +36,15 @@ import org.springframework.transaction.TransactionDefinition;
  * it will be treated like
  * {@link org.springframework.transaction.interceptor.DefaultTransactionAttribute}
  * (rolling back on runtime exceptions).
- * 
+ *
+ * <p>For specific information about the semantics of this annotation's attributes,
+ * consider the {@link org.springframework.transaction.TransactionDefinition} and
+ * {@link org.springframework.transaction.interceptor.TransactionAttribute} javadocs.
+ *
  * @author Colin Sampaleanu
  * @author Juergen Hoeller
  * @since 1.2
+ * @see org.springframework.transaction.interceptor.TransactionAttribute
  * @see org.springframework.transaction.interceptor.DefaultTransactionAttribute
  * @see org.springframework.transaction.interceptor.RuleBasedTransactionAttribute
  */
@@ -60,25 +65,33 @@ public @interface Transactional {
 
 	/**
 	 * The transaction propagation type.
-	 * <p>Defaults to {@link Propagation#REQUIRED}.
+	 * Defaults to {@link Propagation#REQUIRED}.
+	 * @see org.springframework.transaction.interceptor.TransactionAttribute#getPropagationBehavior()
 	 */
 	Propagation propagation() default Propagation.REQUIRED;
 
 	/**
 	 * The transaction isolation level.
-	 * <p>Defaults to {@link Isolation#DEFAULT}.
+	 * Defaults to {@link Isolation#DEFAULT}.
+	 * @see org.springframework.transaction.interceptor.TransactionAttribute#getIsolationLevel()
 	 */
 	Isolation isolation() default Isolation.DEFAULT;
 
 	/**
 	 * The timeout for this transaction.
-	 * <p>Defaults to the default timeout of the underlying transaction system.
+	 * Defaults to the default timeout of the underlying transaction system.
+	 * @see org.springframework.transaction.interceptor.TransactionAttribute#getTimeout()
 	 */
 	int timeout() default TransactionDefinition.TIMEOUT_DEFAULT;
 
 	/**
 	 * <code>true</code> if the transaction is read-only.
-	 * <p>Defaults to <code>false</code>.
+	 * Defaults to <code>false</code>.
+	 * <p>This just serves as a hint for the actual transaction subsystem;
+	 * it will <i>not necessarily</i> cause failure of write access attempts.
+	 * A transaction manager which cannot interpret the read-only hint will
+	 * <i>not</i> throw an exception when asked for a read-only transaction.
+	 * @see org.springframework.transaction.interceptor.TransactionAttribute#isReadOnly()
 	 */
 	boolean readOnly() default false;