From ab139dffd0d8c07e84df7ccb092773eba1ca4285 Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Wed, 24 Mar 2010 23:22:52 +0000 Subject: [PATCH] added javadoc references to semantic definition of transaction attributes (SPR-7029) --- .../transaction/TransactionDefinition.java | 56 +++++++++---------- .../transaction/annotation/Transactional.java | 25 +++++++-- 2 files changed, 44 insertions(+), 37 deletions(-) diff --git a/org.springframework.transaction/src/main/java/org/springframework/transaction/TransactionDefinition.java b/org.springframework.transaction/src/main/java/org/springframework/transaction/TransactionDefinition.java index e5109d73278..0382efa2f24 100644 --- a/org.springframework.transaction/src/main/java/org/springframework/transaction/TransactionDefinition.java +++ b/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. - *

NOTE: Actual creation of a nested transaction will only work on specific - * transaction managers. Out of the box, this only applies to the JDBC + *

NOTE: Actual creation of a nested transaction will only work on + * 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. - *

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. + *

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. * @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. - *

This level prohibits a transaction from reading a row with - * uncommitted changes in it, and it also prohibits the situation - * where one transaction reads a row, a second transaction alters - * the row, and the first transaction rereads the row, getting - * different values the second time (a "non-repeatable read"). + *

This level prohibits a transaction from reading a row with uncommitted changes + * in it, and it also prohibits the situation where one transaction reads a row, + * a second transaction alters the row, and the first transaction re-reads the row, + * getting 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. - *

This level includes the prohibitions in - * {@link #ISOLATION_REPEATABLE_READ} and further prohibits the - * situation where one transaction reads all rows that satisfy a - * WHERE condition, a second transaction inserts a - * row that satisfies that WHERE condition, and the - * first transaction rereads for the same condition, retrieving - * the additional "phantom" row in the second read. + *

This level includes the prohibitions in {@link #ISOLATION_REPEATABLE_READ} + * and further prohibits the situation where one transaction reads all rows that + * satisfy a WHERE condition, a second transaction inserts a row + * that satisfies that WHERE condition, and the first transaction + * re-reads for the same condition, retrieving 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}. *

Only makes sense in combination with {@link #PROPAGATION_REQUIRED} * or {@link #PROPAGATION_REQUIRES_NEW}. - *

Note that a transaction manager that does not support custom - * isolation levels will throw an exception when given any other level - * than {@link #ISOLATION_DEFAULT}. + *

Note that a transaction manager that does not support custom isolation levels + * will throw an exception when given any other level than {@link #ISOLATION_DEFAULT}. * @return the isolation level */ int getIsolationLevel(); @@ -221,9 +218,8 @@ public interface TransactionDefinition { *

Must return a number of seconds, or {@link #TIMEOUT_DEFAULT}. *

Only makes sense in combination with {@link #PROPAGATION_REQUIRED} * or {@link #PROPAGATION_REQUIRES_NEW}. - *

Note that a transaction manager that does not support timeouts - * will throw an exception when given any other timeout than - * {@link #TIMEOUT_DEFAULT}. + *

Note that a transaction manager that does not support timeouts will throw + * an exception when given any other timeout than {@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 Session. - *

This just serves as a hint for the actual transaction subsystem; +<< *

This just serves as a hint for the actual transaction subsystem; * it will not necessarily 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 * not throw an exception when asked for a read-only transaction. * @return true 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 null. *

This will be used as the transaction name to be shown in a * transaction monitor, if applicable (for example, WebLogic's). - *

In case of Spring's declarative transactions, the exposed name - * must (and will) be the - * fully-qualified class name + "." + method name - * (by default). + *

In case of Spring's declarative transactions, the exposed name will be + * the fully-qualified class name + "." + method name (by default). * @return the name of this transaction * @see org.springframework.transaction.interceptor.TransactionAspectSupport * @see org.springframework.transaction.support.TransactionSynchronizationManager#getCurrentTransactionName() diff --git a/org.springframework.transaction/src/main/java/org/springframework/transaction/annotation/Transactional.java b/org.springframework.transaction/src/main/java/org/springframework/transaction/annotation/Transactional.java index 56211ab503d..c3fc85dcbce 100644 --- a/org.springframework.transaction/src/main/java/org/springframework/transaction/annotation/Transactional.java +++ b/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). - * + * + *

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. - *

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. - *

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. - *

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; /** * true if the transaction is read-only. - *

Defaults to false. + * Defaults to false. + *

This just serves as a hint for the actual transaction subsystem; + * it will not necessarily cause failure of write access attempts. + * A transaction manager which cannot interpret the read-only hint will + * not throw an exception when asked for a read-only transaction. + * @see org.springframework.transaction.interceptor.TransactionAttribute#isReadOnly() */ boolean readOnly() default false;