Merge class-level and method-level @SQL declarations

Prior to these commits method-level @SQL declarations always overrode
class-level @SQL declarations, which required developers to redeclare
class-level @SQL declarations on test methods (e.g., via
copy-and-paste) in order to combine them with method-level @SQL
declarations.

These commits provide developers the ability to optionally merge
class-level and method-level @SQL declarations via a new @SqlMergeMode
annotation that can be applied at the class level or method level, with
method-level declarations of @SqlMergeMode overriding class-level
declarations. For example, @SqlMergeMode(MERGE) switches from the
default OVERRIDE behavior to merging behavior, with class-level SQL
scripts and statements executed before method-level SQL scripts and
statements.

Closes gh-1835

Author: sbrannen

spring-test/src/main/java/org/springframework/test/context/jdbc/Sql.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -31,7 +31,8 @@
  * SQL {@link #scripts} and {@link #statements} to be executed against a given
  * database during integration tests.
  *
- * <p>Method-level declarations override class-level declarations.
+ * <p>Method-level declarations override class-level declarations by default,
+ * but this behavior can be configured via {@link SqlMergeMode @SqlMergeMode}.
  *
  * <p>Script execution is performed by the {@link SqlScriptsTestExecutionListener},
  * which is enabled by default.
@@ -55,6 +56,7 @@
  * @author Sam Brannen
  * @since 4.1
  * @see SqlConfig
+ * @see SqlMergeMode
  * @see SqlGroup
  * @see SqlScriptsTestExecutionListener
  * @see org.springframework.transaction.annotation.Transactional

spring-test/src/main/java/org/springframework/test/context/jdbc/SqlMergeMode.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2002-2019 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
+ *
+ *      https://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.jdbc;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * {@code @SqlMergeMode} is used to annotate a test class or test method to
+ * configure whether method-level {@code @Sql} declarations are merged with
+ * class-level {@code @Sql} declarations.
+ *
+ * <p>A method-level {@code @SqlMergeMode} declaration overrides a class-level
+ * declaration.
+ *
+ * <p>If {@code @SqlMergeMode} is not declared on a test class or test method,
+ * {@link MergeMode#OVERRIDE} will be used by default.
+ *
+ * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
+ * <em>composed annotations</em> with attribute overrides.
+ *
+ * @author Sam Brannen
+ * @author Dmitry Semukhin
+ * @since 5.2
+ * @see Sql
+ * @see MergeMode#MERGE
+ * @see MergeMode#OVERRIDE
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+public @interface SqlMergeMode {
+
+	/**
+	 * Indicates whether method-level {@code @Sql} annotations should be merged
+	 * with class-level {@code @Sql} annotations or override them.
+	 */
+	MergeMode value();
+
+
+	/**
+	 * Enumeration of <em>modes</em> that dictate whether method-level {@code @Sql}
+	 * declarations are merged with class-level {@code @Sql} declarations.
+	 */
+	enum MergeMode {
+
+		/**
+		 * Indicates that method-level {@code @Sql} declarations should be merged
+		 * with class-level {@code @Sql} declarations, with class-level SQL
+		 * scripts and statements executed before method-level scripts and
+		 * statements.
+		 */
+		MERGE,
+
+		/**
+		 * Indicates that method-level {@code @Sql} declarations should override
+		 * class-level {@code @Sql} declarations.
+		 */
+		OVERRIDE
+
+	}
+
+}

spring-test/src/main/java/org/springframework/test/context/jdbc/SqlScriptsTestExecutionListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -16,6 +16,7 @@
 
 package org.springframework.test.context.jdbc;
 
+import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
 import java.util.List;
 import java.util.Set;
@@ -30,11 +31,13 @@
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.core.io.Resource;
 import org.springframework.jdbc.datasource.init.ResourceDatabasePopulator;
+import org.springframework.lang.NonNull;
 import org.springframework.lang.Nullable;
 import org.springframework.test.context.TestContext;
 import org.springframework.test.context.jdbc.Sql.ExecutionPhase;
 import org.springframework.test.context.jdbc.SqlConfig.ErrorMode;
 import org.springframework.test.context.jdbc.SqlConfig.TransactionMode;
+import org.springframework.test.context.jdbc.SqlMergeMode.MergeMode;
 import org.springframework.test.context.support.AbstractTestExecutionListener;
 import org.springframework.test.context.transaction.TestContextTransactionUtils;
 import org.springframework.test.context.util.TestContextResourceUtils;
@@ -81,6 +84,7 @@
  * locate these beans.
  *
  * @author Sam Brannen
+ * @author Dmitry Semukhin
  * @since 4.1
  * @see Sql
  * @see SqlConfig
@@ -108,7 +112,7 @@ public final int getOrder() {
 	 * {@link TestContext} <em>before</em> the current test method.
 	 */
 	@Override
-	public void beforeTestMethod(TestContext testContext) throws Exception {
+	public void beforeTestMethod(TestContext testContext) {
 		executeSqlScripts(testContext, ExecutionPhase.BEFORE_TEST_METHOD);
 	}
 
@@ -117,30 +121,66 @@ public void beforeTestMethod(TestContext testContext) throws Exception {
 	 * {@link TestContext} <em>after</em> the current test method.
 	 */
 	@Override
-	public void afterTestMethod(TestContext testContext) throws Exception {
+	public void afterTestMethod(TestContext testContext) {
 		executeSqlScripts(testContext, ExecutionPhase.AFTER_TEST_METHOD);
 	}
 
 	/**
 	 * Execute SQL scripts configured via {@link Sql @Sql} for the supplied
 	 * {@link TestContext} and {@link ExecutionPhase}.
 	 */
-	private void executeSqlScripts(TestContext testContext, ExecutionPhase executionPhase) throws Exception {
-		boolean classLevel = false;
-
-		Set<Sql> sqlAnnotations = AnnotatedElementUtils.getMergedRepeatableAnnotations(
-				testContext.getTestMethod(), Sql.class, SqlGroup.class);
-		if (sqlAnnotations.isEmpty()) {
-			sqlAnnotations = AnnotatedElementUtils.getMergedRepeatableAnnotations(
-					testContext.getTestClass(), Sql.class, SqlGroup.class);
-			if (!sqlAnnotations.isEmpty()) {
-				classLevel = true;
+	private void executeSqlScripts(TestContext testContext, ExecutionPhase executionPhase) {
+		Method testMethod = testContext.getTestMethod();
+		Class<?> testClass = testContext.getTestClass();
+
+		if (mergeSqlAnnotations(testContext)) {
+			executeSqlScripts(getSqlAnnotationsFor(testClass), testContext, executionPhase, true);
+			executeSqlScripts(getSqlAnnotationsFor(testMethod), testContext, executionPhase, false);
+		}
+		else {
+			Set<Sql> methodLevelSqlAnnotations = getSqlAnnotationsFor(testMethod);
+			if (!methodLevelSqlAnnotations.isEmpty()) {
+				executeSqlScripts(methodLevelSqlAnnotations, testContext, executionPhase, false);
+			}
+			else {
+				executeSqlScripts(getSqlAnnotationsFor(testClass), testContext, executionPhase, true);
 			}
 		}
+	}
 
-		for (Sql sql : sqlAnnotations) {
-			executeSqlScripts(sql, executionPhase, testContext, classLevel);
+	/**
+	 * Determine if method-level {@code @Sql} annotations should be merged with
+	 * class-level {@code @Sql} annotations.
+	 */
+	private boolean mergeSqlAnnotations(TestContext testContext) {
+		SqlMergeMode sqlMergeMode = getSqlMergeModeFor(testContext.getTestMethod());
+		if (sqlMergeMode == null) {
+			sqlMergeMode = getSqlMergeModeFor(testContext.getTestClass());
 		}
+		return (sqlMergeMode != null && sqlMergeMode.value() == MergeMode.MERGE);
+	}
+
+	/**
+	 * Get the {@code @SqlMergeMode} annotation declared on the supplied {@code element}.
+	 */
+	private SqlMergeMode getSqlMergeModeFor(AnnotatedElement element) {
+		return AnnotatedElementUtils.findMergedAnnotation(element, SqlMergeMode.class);
+	}
+
+	/**
+	 * Get the {@code @Sql} annotations declared on the supplied {@code element}.
+	 */
+	private Set<Sql> getSqlAnnotationsFor(AnnotatedElement element) {
+		return AnnotatedElementUtils.getMergedRepeatableAnnotations(element, Sql.class, SqlGroup.class);
+	}
+
+	/**
+	 * Execute SQL scripts for the supplied {@link Sql @Sql} annotations.
+	 */
+	private void executeSqlScripts(
+			Set<Sql> sqlAnnotations, TestContext testContext, ExecutionPhase executionPhase, boolean classLevel) {
+
+		sqlAnnotations.forEach(sql -> executeSqlScripts(sql, executionPhase, testContext, classLevel));
 	}
 
 	/**
@@ -153,8 +193,8 @@ private void executeSqlScripts(TestContext testContext, ExecutionPhase execution
 	 * @param testContext the current {@code TestContext}
 	 * @param classLevel {@code true} if {@link Sql @Sql} was declared at the class level
 	 */
-	private void executeSqlScripts(Sql sql, ExecutionPhase executionPhase, TestContext testContext, boolean classLevel)
-			throws Exception {
+	private void executeSqlScripts(
+			Sql sql, ExecutionPhase executionPhase, TestContext testContext, boolean classLevel) {
 
 		if (executionPhase != sql.executionPhase()) {
 			return;
@@ -166,15 +206,6 @@ private void executeSqlScripts(Sql sql, ExecutionPhase executionPhase, TestConte
 					mergedSqlConfig, executionPhase, testContext));
 		}
 
-		final ResourceDatabasePopulator populator = new ResourceDatabasePopulator();
-		populator.setSqlScriptEncoding(mergedSqlConfig.getEncoding());
-		populator.setSeparator(mergedSqlConfig.getSeparator());
-		populator.setCommentPrefix(mergedSqlConfig.getCommentPrefix());
-		populator.setBlockCommentStartDelimiter(mergedSqlConfig.getBlockCommentStartDelimiter());
-		populator.setBlockCommentEndDelimiter(mergedSqlConfig.getBlockCommentEndDelimiter());
-		populator.setContinueOnError(mergedSqlConfig.getErrorMode() == ErrorMode.CONTINUE_ON_ERROR);
-		populator.setIgnoreFailedDrops(mergedSqlConfig.getErrorMode() == ErrorMode.IGNORE_FAILED_DROPS);
-
 		String[] scripts = getScripts(sql, testContext, classLevel);
 		scripts = TestContextResourceUtils.convertToClasspathResourcePaths(testContext.getTestClass(), scripts);
 		List<Resource> scriptResources = TestContextResourceUtils.convertToResourceList(
@@ -185,6 +216,8 @@ private void executeSqlScripts(Sql sql, ExecutionPhase executionPhase, TestConte
 				scriptResources.add(new ByteArrayResource(stmt.getBytes(), "from inlined SQL statement: " + stmt));
 			}
 		}
+
+		ResourceDatabasePopulator populator = createDatabasePopulator(mergedSqlConfig);
 		populator.setScripts(scriptResources.toArray(new Resource[0]));
 		if (logger.isDebugEnabled()) {
 			logger.debug("Executing SQL scripts: " + ObjectUtils.nullSafeToString(scriptResources));
@@ -225,13 +258,23 @@ private void executeSqlScripts(Sql sql, ExecutionPhase executionPhase, TestConte
 					TransactionDefinition.PROPAGATION_REQUIRED);
 			TransactionAttribute txAttr = TestContextTransactionUtils.createDelegatingTransactionAttribute(
 					testContext, new DefaultTransactionAttribute(propagation));
-			new TransactionTemplate(txMgr, txAttr).execute(status -> {
-				populator.execute(finalDataSource);
-				return null;
-			});
+			new TransactionTemplate(txMgr, txAttr).execute(() -> populator.execute(finalDataSource));
 		}
 	}
 
+	@NonNull
+	private ResourceDatabasePopulator createDatabasePopulator(MergedSqlConfig mergedSqlConfig) {
+		ResourceDatabasePopulator populator = new ResourceDatabasePopulator();
+		populator.setSqlScriptEncoding(mergedSqlConfig.getEncoding());
+		populator.setSeparator(mergedSqlConfig.getSeparator());
+		populator.setCommentPrefix(mergedSqlConfig.getCommentPrefix());
+		populator.setBlockCommentStartDelimiter(mergedSqlConfig.getBlockCommentStartDelimiter());
+		populator.setBlockCommentEndDelimiter(mergedSqlConfig.getBlockCommentEndDelimiter());
+		populator.setContinueOnError(mergedSqlConfig.getErrorMode() == ErrorMode.CONTINUE_ON_ERROR);
+		populator.setIgnoreFailedDrops(mergedSqlConfig.getErrorMode() == ErrorMode.IGNORE_FAILED_DROPS);
+		return populator;
+	}
+
 	@Nullable
 	private DataSource getDataSourceFromTransactionManager(PlatformTransactionManager transactionManager) {
 		try {

spring-test/src/test/java/org/springframework/test/context/jdbc/merging/AbstractSqlMergeModeTests.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2019 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
+ *
+ *      https://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.jdbc.merging;
+
+import java.util.List;
+
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.jdbc.EmptyDatabaseConfig;
+import org.springframework.test.context.jdbc.SqlMergeMode;
+import org.springframework.test.context.junit4.AbstractTransactionalJUnit4SpringContextTests;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.test.annotation.DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD;
+
+/**
+ * Abstract base class for tests involving {@link SqlMergeMode @SqlMergeMode}.
+ *
+ * @author Sam Brannen
+ * @since 5.2
+ */
+@ContextConfiguration(classes = EmptyDatabaseConfig.class)
+@DirtiesContext(classMode = AFTER_EACH_TEST_METHOD)
+abstract class AbstractSqlMergeModeTests extends AbstractTransactionalJUnit4SpringContextTests {
+
+	protected void assertUsers(String... expectedUsers) {
+		List<String> actualUsers = super.jdbcTemplate.queryForList("select name from user", String.class);
+		assertThat(actualUsers).containsExactlyInAnyOrder(expectedUsers);
+	}
+
+}