Add multi-prefix comment support for @SqlConfig

spring-projectsgh-23289 introduced support for multiple single-line comment prefixes
for ScriptUtils, ResourceDatabasePopulator, and EmbeddedDatabaseBuilder.

This commit adds the same support for @SqlConfig in the TestContext
Framework. Specifically, @SqlConfig has a new `commentPrefixes`
attribute for setting multiple single-line comment prefixes.

Closes spring-projectsgh-23331

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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,11 +16,15 @@
 
 package org.springframework.test.context.jdbc;
 
+import java.lang.reflect.Array;
+import java.util.Arrays;
+
 import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.core.annotation.AnnotationAttributes;
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.core.style.ToStringCreator;
 import org.springframework.jdbc.datasource.init.ScriptUtils;
+import org.springframework.lang.Nullable;
 import org.springframework.test.context.jdbc.SqlConfig.ErrorMode;
 import org.springframework.test.context.jdbc.SqlConfig.TransactionMode;
 import org.springframework.util.Assert;
@@ -37,6 +41,11 @@
  */
 class MergedSqlConfig {
 
+	private static final String COMMENT_PREFIX = "commentPrefix";
+
+	private static final String COMMENT_PREFIXES = "commentPrefixes";
+
+
 	private final String dataSource;
 
 	private final String transactionManager;
@@ -47,7 +56,7 @@ class MergedSqlConfig {
 
 	private final String separator;
 
-	private final String commentPrefix;
+	private final String[] commentPrefixes;
 
 	private final String blockCommentStartDelimiter;
 
@@ -68,38 +77,53 @@ class MergedSqlConfig {
 		Assert.notNull(localSqlConfig, "Local @SqlConfig must not be null");
 		Assert.notNull(testClass, "testClass must not be null");
 
+		AnnotationAttributes mergedAttributes;
+		AnnotationAttributes localAttributes = AnnotationUtils.getAnnotationAttributes(localSqlConfig, false, false);
+		// Enforce comment prefix aliases within the local @SqlConfig.
+		enforceCommentPrefixAliases(localAttributes);
+
 		// Get global attributes, if any.
-		AnnotationAttributes attributes = AnnotatedElementUtils.findMergedAnnotationAttributes(
+		AnnotationAttributes globalAttributes = AnnotatedElementUtils.findMergedAnnotationAttributes(
 				testClass, SqlConfig.class.getName(), false, false);
 
-		// Override global attributes with local attributes.
-		if (attributes != null) {
-			for (String key : attributes.keySet()) {
-				Object value = AnnotationUtils.getValue(localSqlConfig, key);
-				if (value != null) {
-					// Is the value explicit (i.e., not a 'default')?
-					if (!value.equals("") && value != TransactionMode.DEFAULT && value != ErrorMode.DEFAULT) {
-						attributes.put(key, value);
+		if (globalAttributes != null) {
+			// Enforce comment prefix aliases within the global @SqlConfig.
+			enforceCommentPrefixAliases(globalAttributes);
+
+			for (String key : globalAttributes.keySet()) {
+				Object value = localAttributes.get(key);
+				if (isExplicitValue(value)) {
+					// Override global attribute with local attribute.
+					globalAttributes.put(key, value);
+
+					// Ensure comment prefix aliases are honored during the merge.
+					if (key.equals(COMMENT_PREFIX) && isEmptyArray(localAttributes.get(COMMENT_PREFIXES))) {
+						globalAttributes.put(COMMENT_PREFIXES, value);
+					}
+					else if (key.equals(COMMENT_PREFIXES) && isEmptyString(localAttributes.get(COMMENT_PREFIX))) {
+						globalAttributes.put(COMMENT_PREFIX, value);
 					}
 				}
 			}
+			mergedAttributes = globalAttributes;
 		}
 		else {
 			// Otherwise, use local attributes only.
-			attributes = AnnotationUtils.getAnnotationAttributes(localSqlConfig, false, false);
+			mergedAttributes = localAttributes;
 		}
 
-		this.dataSource = attributes.getString("dataSource");
-		this.transactionManager = attributes.getString("transactionManager");
-		this.transactionMode = getEnum(attributes, "transactionMode", TransactionMode.DEFAULT, TransactionMode.INFERRED);
-		this.encoding = attributes.getString("encoding");
-		this.separator = getString(attributes, "separator", ScriptUtils.DEFAULT_STATEMENT_SEPARATOR);
-		this.commentPrefix = getString(attributes, "commentPrefix", ScriptUtils.DEFAULT_COMMENT_PREFIX);
-		this.blockCommentStartDelimiter = getString(attributes, "blockCommentStartDelimiter",
+		this.dataSource = mergedAttributes.getString("dataSource");
+		this.transactionManager = mergedAttributes.getString("transactionManager");
+		this.transactionMode = getEnum(mergedAttributes, "transactionMode", TransactionMode.DEFAULT,
+				TransactionMode.INFERRED);
+		this.encoding = mergedAttributes.getString("encoding");
+		this.separator = getString(mergedAttributes, "separator", ScriptUtils.DEFAULT_STATEMENT_SEPARATOR);
+		this.commentPrefixes = getCommentPrefixes(mergedAttributes);
+		this.blockCommentStartDelimiter = getString(mergedAttributes, "blockCommentStartDelimiter",
 				ScriptUtils.DEFAULT_BLOCK_COMMENT_START_DELIMITER);
-		this.blockCommentEndDelimiter = getString(attributes, "blockCommentEndDelimiter",
+		this.blockCommentEndDelimiter = getString(mergedAttributes, "blockCommentEndDelimiter",
 				ScriptUtils.DEFAULT_BLOCK_COMMENT_END_DELIMITER);
-		this.errorMode = getEnum(attributes, "errorMode", ErrorMode.DEFAULT, ErrorMode.FAIL_ON_ERROR);
+		this.errorMode = getEnum(mergedAttributes, "errorMode", ErrorMode.DEFAULT, ErrorMode.FAIL_ON_ERROR);
 	}
 
 	/**
@@ -138,10 +162,11 @@ String getSeparator() {
 	}
 
 	/**
-	 * @see SqlConfig#commentPrefix()
+	 * @see SqlConfig#commentPrefixes()
+	 * @since 5.2
 	 */
-	String getCommentPrefix() {
-		return this.commentPrefix;
+	String[] getCommentPrefixes() {
+		return this.commentPrefixes;
 	}
 
 	/**
@@ -176,7 +201,7 @@ public String toString() {
 				.append("transactionMode", this.transactionMode)
 				.append("encoding", this.encoding)
 				.append("separator", this.separator)
-				.append("commentPrefix", this.commentPrefix)
+				.append("commentPrefixes", this.commentPrefixes)
 				.append("blockCommentStartDelimiter", this.blockCommentStartDelimiter)
 				.append("blockCommentEndDelimiter", this.blockCommentEndDelimiter)
 				.append("errorMode", this.errorMode)
@@ -202,4 +227,58 @@ private static String getString(AnnotationAttributes attributes, String attribut
 		return value;
 	}
 
+	private static void enforceCommentPrefixAliases(AnnotationAttributes attributes) {
+		String commentPrefix = attributes.getString(COMMENT_PREFIX);
+		String[] commentPrefixes = attributes.getStringArray(COMMENT_PREFIXES);
+
+		boolean explicitCommentPrefix = !commentPrefix.isEmpty();
+		boolean explicitCommentPrefixes = (commentPrefixes.length != 0);
+		Assert.isTrue(!(explicitCommentPrefix && explicitCommentPrefixes),
+			"You may declare the 'commentPrefix' or 'commentPrefixes' attribute in @SqlConfig but not both");
+
+		if (explicitCommentPrefix) {
+			Assert.hasText(commentPrefix, "@SqlConfig(commentPrefix) must contain text");
+			attributes.put(COMMENT_PREFIXES, new String[] { commentPrefix });
+		}
+		else if (explicitCommentPrefixes) {
+			for (String prefix : commentPrefixes) {
+				Assert.hasText(prefix, "@SqlConfig(commentPrefixes) must not contain empty prefixes");
+			}
+			attributes.put(COMMENT_PREFIX, commentPrefixes);
+		}
+		else {
+			// We know commentPrefixes is an empty array, so make sure commentPrefix
+			// is set to that as well in order to honor the alias contract.
+			attributes.put(COMMENT_PREFIX, commentPrefixes);
+		}
+	}
+
+	private static String[] getCommentPrefixes(AnnotationAttributes attributes) {
+		String[] commentPrefix = attributes.getStringArray(COMMENT_PREFIX);
+		String[] commentPrefixes = attributes.getStringArray(COMMENT_PREFIXES);
+
+		Assert.state(Arrays.equals(commentPrefix, commentPrefixes),
+			"Failed to properly handle 'commentPrefix' and 'commentPrefixes' aliases");
+
+		return (commentPrefixes.length != 0 ? commentPrefixes : ScriptUtils.DEFAULT_COMMENT_PREFIXES);
+	}
+
+	/**
+	 * Determine if the supplied value is an explicit value (i.e., not a default).
+	 */
+	private static boolean isExplicitValue(@Nullable Object value) {
+		return !(isEmptyString(value) ||
+				isEmptyArray(value) ||
+				value == TransactionMode.DEFAULT ||
+				value == ErrorMode.DEFAULT);
+	}
+
+	private static boolean isEmptyString(@Nullable Object value) {
+		return (value instanceof String && ((String) value).isEmpty());
+	}
+
+	private static boolean isEmptyArray(@Nullable Object value) {
+		return (value != null && value.getClass().isArray() && Array.getLength(value) == 0);
+	}
+
 }

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

@@ -42,16 +42,17 @@
  * is unfortunately not possible to assign a value of {@code null} to an annotation
  * attribute. Thus, in order to support overrides of <em>inherited</em> global
  * configuration, {@code @SqlConfig} attributes have an <em>explicit</em>
- * {@code default} value of either {@code ""} for Strings or {@code DEFAULT} for
- * Enums. This approach allows local declarations of {@code @SqlConfig} to
- * selectively override individual attributes from global declarations of
- * {@code @SqlConfig} by providing a value other than {@code ""} or {@code DEFAULT}.
+ * {@code default} value of either {@code ""} for Strings, <code>{}</code> for
+ * arrays, or {@code DEFAULT} for Enums. This approach allows local declarations
+ * of {@code @SqlConfig} to selectively override individual attributes from global
+ * declarations of {@code @SqlConfig} by providing a value other than {@code ""},
+ * <code>{}</code>, or {@code DEFAULT}.
  *
  * <h3>Inheritance and Overrides</h3>
  * <p>Global {@code @SqlConfig} attributes are <em>inherited</em> whenever local
  * {@code @SqlConfig} attributes do not supply an explicit value other than
- * {@code ""} or {@code DEFAULT}. Explicit local configuration therefore
- * <em>overrides</em> global configuration.
+ * {@code ""}, <code>{}</code>, or {@code DEFAULT}. Explicit local configuration
+ * therefore <em>overrides</em> global configuration.
  *
  * @author Sam Brannen
  * @author Tadaya Tsuyukubo
@@ -145,10 +146,26 @@
 	/**
 	 * The prefix that identifies single-line comments within the SQL scripts.
 	 * <p>Implicitly defaults to {@code "--"}.
+	 * <p>This attribute may <strong>not</strong> be used in conjunction with
+	 * {@link #commentPrefixes commentPrefixes}, but it may be used instead of
+	 * {@link #commentPrefixes commentPrefixes}.
 	 * @see org.springframework.jdbc.datasource.init.ScriptUtils#DEFAULT_COMMENT_PREFIX
+	 * @see #commentPrefixes
 	 */
 	String commentPrefix() default "";
 
+	/**
+	 * The prefixes that identify single-line comments within the SQL scripts.
+	 * <p>Implicitly defaults to {@code ["--"]}.
+	 * <p>This attribute may <strong>not</strong> be used in conjunction with
+	 * {@link #commentPrefix commentPrefix}, but it may be used instead of
+	 * {@link #commentPrefix commentPrefix}.
+	 * @see org.springframework.jdbc.datasource.init.ScriptUtils#DEFAULT_COMMENT_PREFIXES
+	 * @see #commentPrefix
+	 * @since 5.2
+	 */
+	String[] commentPrefixes() default {};
+
 	/**
 	 * The start delimiter that identifies block comments within the SQL scripts.
 	 * <p>Implicitly defaults to {@code "/*"}.

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

@@ -267,7 +267,7 @@ private ResourceDatabasePopulator createDatabasePopulator(MergedSqlConfig merged
 		ResourceDatabasePopulator populator = new ResourceDatabasePopulator();
 		populator.setSqlScriptEncoding(mergedSqlConfig.getEncoding());
 		populator.setSeparator(mergedSqlConfig.getSeparator());
-		populator.setCommentPrefix(mergedSqlConfig.getCommentPrefix());
+		populator.setCommentPrefixes(mergedSqlConfig.getCommentPrefixes());
 		populator.setBlockCommentStartDelimiter(mergedSqlConfig.getBlockCommentStartDelimiter());
 		populator.setBlockCommentEndDelimiter(mergedSqlConfig.getBlockCommentEndDelimiter());
 		populator.setContinueOnError(mergedSqlConfig.getErrorMode() == ErrorMode.CONTINUE_ON_ERROR);

spring-test/src/test/java/org/springframework/test/context/configuration/interfaces/SqlConfigTestInterface.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.
@@ -27,6 +27,6 @@
  */
 @ContextConfiguration(classes = EmptyDatabaseConfig.class)
 @DirtiesContext
-@SqlConfig(commentPrefix = "`", blockCommentStartDelimiter = "#$", blockCommentEndDelimiter = "$#", separator = "@@")
+@SqlConfig(commentPrefixes = { "`", "%%" }, blockCommentStartDelimiter = "#$", blockCommentEndDelimiter = "$#", separator = "@@")
 interface SqlConfigTestInterface {
 }

spring-test/src/test/java/org/springframework/test/context/jdbc/CustomScriptSyntaxSqlScriptsTests.java

@@ -38,7 +38,7 @@ public class CustomScriptSyntaxSqlScriptsTests extends AbstractTransactionalJUni
 	@Test
 	@Sql("schema.sql")
 	@Sql(scripts = "data-add-users-with-custom-script-syntax.sql",//
-	config = @SqlConfig(commentPrefix = "`", blockCommentStartDelimiter = "#$", blockCommentEndDelimiter = "$#", separator = "@@"))
+	config = @SqlConfig(commentPrefixes = { "`", "%%" }, blockCommentStartDelimiter = "#$", blockCommentEndDelimiter = "$#", separator = "@@"))
 	public void methodLevelScripts() {
 		assertNumUsers(3);
 	}

spring-test/src/test/java/org/springframework/test/context/jdbc/GlobalCustomScriptSyntaxSqlScriptsTests.java

@@ -33,7 +33,7 @@
  */
 @ContextConfiguration(classes = EmptyDatabaseConfig.class)
 @DirtiesContext
-@SqlConfig(commentPrefix = "`", blockCommentStartDelimiter = "#$", blockCommentEndDelimiter = "$#", separator = "@@")
+@SqlConfig(commentPrefixes = { "`", "%%" }, blockCommentStartDelimiter = "#$", blockCommentEndDelimiter = "$#", separator = "@@")
 public class GlobalCustomScriptSyntaxSqlScriptsTests extends AbstractTransactionalJUnit4SpringContextTests {
 
 	@Test