From d6bdfcaa6e29ef40ead5dbbfd3e2bf6d6373f026 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 25 Jul 2015 21:09:32 +0200 Subject: [PATCH] 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 --- .../test/annotation/Commit.java | 57 +++++++++++++++++++ .../test/annotation/Rollback.java | 21 +++++-- ...TransactionalJUnit4SpringContextTests.java | 1 + ...TransactionalTestNGSpringContextTests.java | 3 +- .../transaction/TransactionConfiguration.java | 1 + .../TransactionalTestExecutionListener.java | 1 + .../CommitForRequiredEjbTxDaoTestNGTests.java | 2 +- ...mmitForRequiresNewEjbTxDaoTestNGTests.java | 2 +- .../ProgrammaticTxMgmtTestNGTests.java | 7 ++- .../test/context/transaction/Commit.java | 37 ------------ ...ansactionalTestExecutionListenerTests.java | 1 + .../ejb/CommitForRequiredEjbTxDaoTests.java | 2 +- .../CommitForRequiresNewEjbTxDaoTests.java | 2 +- .../programmatic/ProgrammaticTxMgmtTests.java | 4 +- src/asciidoc/testing.adoc | 25 +++++++- src/asciidoc/whats-new.adoc | 2 + 16 files changed, 115 insertions(+), 53 deletions(-) create mode 100644 spring-test/src/main/java/org/springframework/test/annotation/Commit.java delete mode 100644 spring-test/src/test/java/org/springframework/test/context/transaction/Commit.java diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Commit.java b/spring-test/src/main/java/org/springframework/test/annotation/Commit.java new file mode 100644 index 0000000000..79205810e5 --- /dev/null +++ b/spring-test/src/main/java/org/springframework/test/annotation/Commit.java @@ -0,0 +1,57 @@ +/* + * 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.test.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.Target; + +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 + * test-managed transaction should be committed after + * the test method has completed. + * + *

Consult the class-level Javadoc for + * {@link org.springframework.test.context.transaction.TransactionalTestExecutionListener} + * for an explanation of test-managed transactions. + * + *

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

Warning: {@code @Commit} can be used as direct + * replacement for {@code @Rollback(false)}; however, it should + * not 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) +@Target({ TYPE, METHOD }) +@Rollback(false) +public @interface Commit { +} diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java b/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java index 3b692317dd..65333a23e3 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java +++ b/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 test-managed transaction - * should be rolled back after the test method has completed. + * {@code @Rollback} is a test annotation that is used to indicate whether + * a test-managed transaction should be rolled back after + * the test method has completed. * *

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

As of Spring Framework 4.0, this annotation may be used as a - * meta-annotation to create custom composed annotations. + *

As of Spring Framework 4.2, {@code @Commit} can be used as direct + * replacement for {@code @Rollback(false)}. + * + *

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

This annotation may be used as a meta-annotation to create + * custom composed annotations. 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. *

If {@code true}, the transaction will be rolled back; otherwise, * the transaction will be committed. + *

Defaults to {@code true}. */ boolean value() default true; diff --git a/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java b/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java index 01cbd861b8..9745e597c1 100644 --- a/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java +++ b/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 diff --git a/spring-test/src/main/java/org/springframework/test/context/testng/AbstractTransactionalTestNGSpringContextTests.java b/spring-test/src/main/java/org/springframework/test/context/testng/AbstractTransactionalTestNGSpringContextTests.java index 45c9e7186c..1fd08e329c 100644 --- a/spring-test/src/main/java/org/springframework/test/context/testng/AbstractTransactionalTestNGSpringContextTests.java +++ b/spring-test/src/main/java/org/springframework/test/context/testng/AbstractTransactionalTestNGSpringContextTests.java @@ -1,5 +1,5 @@ /* - * 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 diff --git a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java index 44ef346bf2..98857e5a05 100644 --- a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java +++ b/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 diff --git a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java b/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java index 659a9694f6..953d184b85 100644 --- a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionalTestExecutionListener.java +++ b/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 diff --git a/spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiredEjbTxDaoTestNGTests.java b/spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiredEjbTxDaoTestNGTests.java index ae5148bff1..9a38bef11f 100644 --- a/spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiredEjbTxDaoTestNGTests.java +++ b/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; diff --git a/spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiresNewEjbTxDaoTestNGTests.java b/spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiresNewEjbTxDaoTestNGTests.java index 0117299971..d784bff5c6 100644 --- a/spring-test/src/test/java/org/springframework/test/context/testng/transaction/ejb/CommitForRequiresNewEjbTxDaoTestNGTests.java +++ b/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; diff --git a/spring-test/src/test/java/org/springframework/test/context/testng/transaction/programmatic/ProgrammaticTxMgmtTestNGTests.java b/spring-test/src/test/java/org/springframework/test/context/testng/transaction/programmatic/ProgrammaticTxMgmtTestNGTests.java index 64902fbf9f..495ce2bb93 100644 --- a/spring-test/src/test/java/org/springframework/test/context/testng/transaction/programmatic/ProgrammaticTxMgmtTestNGTests.java +++ b/spring-test/src/test/java/org/springframework/test/context/testng/transaction/programmatic/ProgrammaticTxMgmtTestNGTests.java @@ -1,5 +1,5 @@ /* - * 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()); diff --git a/spring-test/src/test/java/org/springframework/test/context/transaction/Commit.java b/spring-test/src/test/java/org/springframework/test/context/transaction/Commit.java deleted file mode 100644 index 4ba3b134a8..0000000000 --- a/spring-test/src/test/java/org/springframework/test/context/transaction/Commit.java +++ /dev/null @@ -1,37 +0,0 @@ -/* - * 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. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package org.springframework.test.context.transaction; - -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.*; - -/** - * @author Sam Brannen - * @since 4.2 - */ -@Documented -@Retention(RUNTIME) -@Target({ TYPE, METHOD }) -@Rollback(false) -public @interface Commit { -} diff --git a/spring-test/src/test/java/org/springframework/test/context/transaction/TransactionalTestExecutionListenerTests.java b/spring-test/src/test/java/org/springframework/test/context/transaction/TransactionalTestExecutionListenerTests.java index e08f6be545..b01fc608e8 100644 --- a/spring-test/src/test/java/org/springframework/test/context/transaction/TransactionalTestExecutionListenerTests.java +++ b/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; diff --git a/spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiredEjbTxDaoTests.java b/spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiredEjbTxDaoTests.java index 2692d94713..7c73b7a2b2 100644 --- a/spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiredEjbTxDaoTests.java +++ b/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; diff --git a/spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiresNewEjbTxDaoTests.java b/spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiresNewEjbTxDaoTests.java index dbfa033fad..97817df4f8 100644 --- a/spring-test/src/test/java/org/springframework/test/context/transaction/ejb/CommitForRequiresNewEjbTxDaoTests.java +++ b/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; diff --git a/spring-test/src/test/java/org/springframework/test/context/transaction/programmatic/ProgrammaticTxMgmtTests.java b/spring-test/src/test/java/org/springframework/test/context/transaction/programmatic/ProgrammaticTxMgmtTests.java index 35f71b2229..872b9120eb 100644 --- a/spring-test/src/test/java/org/springframework/test/context/transaction/programmatic/ProgrammaticTxMgmtTests.java +++ b/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()); diff --git a/src/asciidoc/testing.adoc b/src/asciidoc/testing.adoc index d1e5de8150..12dadb237d 100644 --- a/src/asciidoc/testing.adoc +++ b/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. + diff --git a/src/asciidoc/whats-new.adoc b/src/asciidoc/whats-new.adoc index 9e4c6a39b1..16ec877b44 100644 --- a/src/asciidoc/whats-new.adoc +++ b/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. -- GitLab