Introduce @Commit alias for @Rollback(false)

Due to common usage of @Rollback(false), this commit introduces a new
@Commit annotation that more clearly conveys the intent of the code
while retaining the run-time semantics.

@Commit is in fact meta-annotated with @Rollback(false).

Issue: SPR-13279

spring-test/src/test/java/org/springframework/test/context/transaction/Commit.java → spring-test/src/main/java/org/springframework/test/annotation/Commit.java

@@ -14,20 +14,40 @@
  * limitations under the License.
  */
 
-package org.springframework.test.context.transaction;
+package org.springframework.test.annotation;
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import org.springframework.test.annotation.Rollback;
-
 import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
 /**
+ * {@code @Commit} is a test annotation that is used to indicate that a
+ * <em>test-managed transaction</em> should be <em>committed</em> after
+ * the test method has completed.
+ *
+ * <p>Consult the class-level Javadoc for
+ * {@link org.springframework.test.context.transaction.TransactionalTestExecutionListener}
+ * for an explanation of <em>test-managed transactions</em>.
+ *
+ * <p>When declared as a class-level annotation, {@code @Commit} defines
+ * the default commit semantics for all test methods within the test class
+ * hierarchy. When declared as a method-level annotation, {@code @Commit}
+ * defines commit semantics for the specific test method, potentially
+ * overriding class-level default commit or rollback semantics.
+ *
+ * <p><strong>Warning</strong>: {@code @Commit} can be used as direct
+ * replacement for {@code @Rollback(false)}; however, it should
+ * <strong>not</strong> be declared alongside {@code @Rollback}. Declaring
+ * {@code @Commit} and {@code @Rollback} on the same test method or on the
+ * same test class is unsupported and may lead to unpredictable results.
+ *
  * @author Sam Brannen
  * @since 4.2
+ * @see Rollback
+ * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener
  */
 @Documented
 @Retention(RUNTIME)

spring-test/src/main/java/org/springframework/test/annotation/Rollback.java

@@ -24,8 +24,9 @@ import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
 /**
- * Test annotation used to indicate whether a <em>test-managed transaction</em>
- * should be <em>rolled back</em> after the test method has completed.
+ * {@code @Rollback} is a test annotation that is used to indicate whether
+ * a <em>test-managed transaction</em> should be <em>rolled back</em> after
+ * the test method has completed.
  *
  * <p>Consult the class-level Javadoc for
  * {@link org.springframework.test.context.transaction.TransactionalTestExecutionListener}
@@ -35,13 +36,22 @@ import static java.lang.annotation.RetentionPolicy.*;
  * the default rollback semantics for all test methods within the test class
  * hierarchy. When declared as a method-level annotation, {@code @Rollback}
  * defines rollback semantics for the specific test method, potentially
- * overriding class-level default rollback semantics.
+ * overriding class-level default commit or rollback semantics.
  *
- * <p>As of Spring Framework 4.0, this annotation may be used as a
- * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ * <p>As of Spring Framework 4.2, {@code @Commit} can be used as direct
+ * replacement for {@code @Rollback(false)}.
+ *
+ * <p><strong>Warning</strong>: Declaring {@code @Commit} and {@code @Rollback}
+ * on the same test method or on the same test class is unsupported and may
+ * lead to unpredictable results.
+ *
+ * <p>This annotation may be used as a <em>meta-annotation</em> to create
+ * custom <em>composed annotations</em>. Consult the source code for
+ * {@link Commit @Commit} for a concrete example.
  *
  * @author Sam Brannen
  * @since 2.5
+ * @see Commit
  * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener
  */
 @Documented
@@ -54,6 +64,7 @@ public @interface Rollback {
 	 * after the test method has completed.
 	 * <p>If {@code true}, the transaction will be rolled back; otherwise,
 	 * the transaction will be committed.
+	 * <p>Defaults to {@code true}.
 	 */
 	boolean value() default true;
 

spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java

@@ -85,6 +85,7 @@ import org.springframework.transaction.annotation.Transactional;
  * @see org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
  * @see org.springframework.test.context.transaction.TransactionConfiguration
  * @see org.springframework.transaction.annotation.Transactional
+ * @see org.springframework.test.annotation.Commit
  * @see org.springframework.test.annotation.Rollback
  * @see org.springframework.test.context.transaction.BeforeTransaction
  * @see org.springframework.test.context.transaction.AfterTransaction

spring-test/src/main/java/org/springframework/test/context/testng/AbstractTransactionalTestNGSpringContextTests.java

 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -69,6 +69,7 @@ import org.springframework.transaction.annotation.Transactional;
  * @see org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
  * @see org.springframework.test.context.transaction.TransactionConfiguration
  * @see org.springframework.transaction.annotation.Transactional
+ * @see org.springframework.test.annotation.Commit
  * @see org.springframework.test.annotation.Rollback
  * @see org.springframework.test.context.transaction.BeforeTransaction
  * @see org.springframework.test.context.transaction.AfterTransaction

spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java

@@ -34,6 +34,7 @@ import java.lang.annotation.Target;
  * @since 2.5
  * @see TransactionalTestExecutionListener
  * @see org.springframework.transaction.annotation.Transactional
+ * @see org.springframework.test.annotation.Commit
  * @see org.springframework.test.annotation.Rollback
  * @see org.springframework.test.context.jdbc.Sql
  * @see org.springframework.test.context.jdbc.SqlConfig

spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java

@@ -120,6 +120,7 @@ import static org.springframework.core.annotation.AnnotationUtils.*;
  * @since 2.5
  * @see org.springframework.transaction.annotation.TransactionManagementConfigurer
  * @see org.springframework.transaction.annotation.Transactional
+ * @see org.springframework.test.annotation.Commit
  * @see org.springframework.test.annotation.Rollback
  * @see BeforeTransaction
  * @see AfterTransaction

spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiredEjbTxDaoTestNGTests.java

@@ -16,8 +16,8 @@
 
 package org.springframework.test.context.testng.transaction.ejb;
 
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.context.ContextConfiguration;
-import org.springframework.test.context.transaction.Commit;
 import org.springframework.test.context.transaction.TransactionalTestExecutionListener;
 import org.springframework.test.context.transaction.ejb.dao.RequiredEjbTxTestEntityDao;
 

spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiresNewEjbTxDaoTestNGTests.java

@@ -16,8 +16,8 @@
 
 package org.springframework.test.context.testng.transaction.ejb;
 
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.context.ContextConfiguration;
-import org.springframework.test.context.transaction.Commit;
 import org.springframework.test.context.transaction.TransactionalTestExecutionListener;
 import org.springframework.test.context.transaction.ejb.dao.RequiresNewEjbTxTestEntityDao;
 

spring-test/src/test/java/org/springframework/test/context/testng/transaction/programmatic/ProgrammaticTxMgmtTestNGTests.java

 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -26,7 +26,7 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.jdbc.datasource.DataSourceTransactionManager;
 import org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseBuilder;
-import org.springframework.test.annotation.Rollback;
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.context.ContextConfiguration;
 import org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests;
 import org.springframework.test.context.transaction.AfterTransaction;
@@ -36,6 +36,7 @@ import org.springframework.test.context.transaction.programmatic.ProgrammaticTxM
 import org.springframework.transaction.PlatformTransactionManager;
 import org.springframework.transaction.annotation.Propagation;
 import org.springframework.transaction.annotation.Transactional;
+
 import org.testng.IHookCallBack;
 import org.testng.ITestResult;
 import org.testng.annotations.Test;
@@ -219,7 +220,7 @@ public class ProgrammaticTxMgmtTestNGTests extends AbstractTransactionalTestNGSp
 	}
 
 	@Test
-	@Rollback(false)
+	@Commit
 	public void rollbackTxAndStartNewTxWithDefaultCommitSemantics() {
 		assertInTransaction(true);
 		assertTrue(TestTransaction.isActive());

spring-test/src/test/java/org/springframework/test/context/transaction/TransactionalTestExecutionListenerTests.java

@@ -27,6 +27,7 @@ import org.junit.rules.ExpectedException;
 import org.mockito.BDDMockito;
 
 import org.springframework.core.annotation.AliasFor;
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.annotation.Rollback;
 import org.springframework.test.context.TestContext;
 import org.springframework.transaction.PlatformTransactionManager;

spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiredEjbTxDaoTests.java

@@ -16,8 +16,8 @@
 
 package org.springframework.test.context.transaction.ejb;
 
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.context.ContextConfiguration;
-import org.springframework.test.context.transaction.Commit;
 import org.springframework.test.context.transaction.TransactionalTestExecutionListener;
 import org.springframework.test.context.transaction.ejb.dao.RequiredEjbTxTestEntityDao;
 

spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiresNewEjbTxDaoTests.java

@@ -16,8 +16,8 @@
 
 package org.springframework.test.context.transaction.ejb;
 
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.context.ContextConfiguration;
-import org.springframework.test.context.transaction.Commit;
 import org.springframework.test.context.transaction.TransactionalTestExecutionListener;
 import org.springframework.test.context.transaction.ejb.dao.RequiresNewEjbTxTestEntityDao;
 

spring-test/src/test/java/org/springframework/test/context/transaction/programmatic/ProgrammaticTxMgmtTests.java

@@ -37,7 +37,7 @@ import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.jdbc.datasource.DataSourceTransactionManager;
 import org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseBuilder;
 import org.springframework.jdbc.datasource.init.ResourceDatabasePopulator;
-import org.springframework.test.annotation.Rollback;
+import org.springframework.test.annotation.Commit;
 import org.springframework.test.context.ContextConfiguration;
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 import org.springframework.test.context.transaction.AfterTransaction;
@@ -238,7 +238,7 @@ public class ProgrammaticTxMgmtTests {
 	}
 
 	@Test
-	@Rollback(false)
+	@Commit
 	public void rollbackTxAndStartNewTxWithDefaultCommitSemantics() {
 		assertInTransaction(true);
 		assertTrue(TestTransaction.isActive());

src/asciidoc/testing.adoc

@@ -799,13 +799,36 @@ for an example and further details.
 
 +
 
+* `@Commit`
+
++
+
+Indicates that the transaction for a transactional test method should be __committed__
+after the test method has completed. `@Commit` can be used as a direct replacement for
+`@Rollback(false)` in order to more explicitly convey the intent of the code. Analogous to
+`@Rollback`, `@Commit` may also be declared as a class-level or method-level annotation.
+
++
+
+[source,java,indent=0]
+[subs="verbatim,quotes"]
+----
+	**@Commit**
+	@Test
+	public void testProcessWithoutRollback() {
+		// ...
+	}
+----
+
 * `@Rollback`
 
 +
 
 Indicates whether the transaction for a transactional test method should be __rolled
 back__ after the test method has completed. If `true`, the transaction is rolled back;
-otherwise, the transaction is committed.
+otherwise, the transaction is committed. Rollback semantics for integration tests in the
+Spring TestContext Framework default to `true` even if `@Rollback` is not explicitly
+declared.
 
 +
 

src/asciidoc/whats-new.adoc

@@ -577,6 +577,8 @@ public @interface MyTestConfig {
   _before_ a test -- for example, if some rogue (i.e., yet to be
   determined) test within a large test suite has corrupted the original
   configuration for the `ApplicationContext`.
+* `@Commit` is a new annotation that may be used as a direct replacement for
+  `@Rollback(false)`.
 * `@Rollback` may now be used to configure class-level _default rollback_ semantics.
 ** Consequently, `@TransactionConfiguration` is now deprecated and will be removed in a
    subsequent release.