Deprecate internal APIs in ScriptUtils in spring-jdbc

Many of the utility methods in ScriptUtils are public only because they
were once invoked from JdbdTestUtils in spring-test, which is no longer
the case. Consequently, there should no longer be a need for any
external clients to invoke such methods.

To address this, this commit formally deprecates the following methods
in ScriptUtils in spring-jdbc.

- readScript(...)
- containsSqlScriptDelimiters(...)
- splitSqlScript(...)

Closes gh-26947

Author: sbrannen

spring-jdbc/src/main/java/org/springframework/jdbc/datasource/init/ScriptUtils.java

@@ -345,7 +345,10 @@ static String readScript(EncodedResource resource, @Nullable String separator,
 	 * @param blockCommentEndDelimiter the <em>end</em> block comment delimiter
 	 * @return a {@code String} containing the script lines
 	 * @throws IOException in case of I/O errors
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static String readScript(LineNumberReader lineNumberReader, @Nullable String commentPrefix,
 			@Nullable String separator, @Nullable String blockCommentEndDelimiter) throws IOException {
 
@@ -369,7 +372,10 @@ public static String readScript(LineNumberReader lineNumberReader, @Nullable Str
 	 * @return a {@code String} containing the script lines
 	 * @throws IOException in case of I/O errors
 	 * @since 5.2
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static String readScript(LineNumberReader lineNumberReader, @Nullable String[] commentPrefixes,
 			@Nullable String separator, @Nullable String blockCommentEndDelimiter) throws IOException {
 
@@ -417,7 +423,10 @@ private static void appendSeparatorToScriptIfNecessary(StringBuilder scriptBuild
 	 * @see #DEFAULT_COMMENT_PREFIXES
 	 * @see #DEFAULT_BLOCK_COMMENT_START_DELIMITER
 	 * @see #DEFAULT_BLOCK_COMMENT_END_DELIMITER
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static boolean containsSqlScriptDelimiters(String script, String delimiter) {
 		return containsStatementSeparator(null, script, delimiter, DEFAULT_COMMENT_PREFIXES,
 			DEFAULT_BLOCK_COMMENT_START_DELIMITER, DEFAULT_BLOCK_COMMENT_END_DELIMITER);
@@ -520,7 +529,10 @@ else if (script.startsWith(blockCommentStartDelimiter, i)) {
 	 * @throws ScriptException if an error occurred while splitting the SQL script
 	 * @see #splitSqlScript(String, String, List)
 	 * @see #splitSqlScript(EncodedResource, String, String, String, String, String, List)
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static void splitSqlScript(String script, char separator, List<String> statements) throws ScriptException {
 		splitSqlScript(script, String.valueOf(separator), statements);
 	}
@@ -544,7 +556,10 @@ public static void splitSqlScript(String script, char separator, List<String> st
 	 * @throws ScriptException if an error occurred while splitting the SQL script
 	 * @see #splitSqlScript(String, char, List)
 	 * @see #splitSqlScript(EncodedResource, String, String, String, String, String, List)
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static void splitSqlScript(String script, String separator, List<String> statements) throws ScriptException {
 		splitSqlScript(null, script, separator, DEFAULT_COMMENT_PREFIX, DEFAULT_BLOCK_COMMENT_START_DELIMITER,
 				DEFAULT_BLOCK_COMMENT_END_DELIMITER, statements);
@@ -573,7 +588,10 @@ public static void splitSqlScript(String script, String separator, List<String>
 	 * never {@code null} or empty
 	 * @param statements the list that will contain the individual statements
 	 * @throws ScriptException if an error occurred while splitting the SQL script
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static void splitSqlScript(@Nullable EncodedResource resource, String script,
 			String separator, String commentPrefix, String blockCommentStartDelimiter,
 			String blockCommentEndDelimiter, List<String> statements) throws ScriptException {
@@ -607,7 +625,10 @@ public static void splitSqlScript(@Nullable EncodedResource resource, String scr
 	 * @param statements the list that will contain the individual statements
 	 * @throws ScriptException if an error occurred while splitting the SQL script
 	 * @since 5.2
+	 * @deprecated as of Spring Framework 5.2.16 with no plans for replacement.
+	 * This is an internal API and will likely be removed in Spring Framework 6.0.
 	 */
+	@Deprecated
 	public static void splitSqlScript(@Nullable EncodedResource resource, String script,
 			String separator, String[] commentPrefixes, String blockCommentStartDelimiter,
 			String blockCommentEndDelimiter, List<String> statements) throws ScriptException {

spring-jdbc/src/test/java/org/springframework/jdbc/datasource/init/ScriptUtilsUnitTests.java

@@ -49,6 +49,7 @@
 public class ScriptUtilsUnitTests {
 
 	@Test
+	@SuppressWarnings("deprecation")
 	public void splitSqlScriptDelimitedWithSemicolon() {
 		String rawStatement1 = "insert into customer (id, name)\nvalues (1, 'Rod ; Johnson'), (2, 'Adrian \n Collier')";
 		String cleanedStatement1 = "insert into customer (id, name) values (1, 'Rod ; Johnson'), (2, 'Adrian \n Collier')";
@@ -67,6 +68,7 @@ public void splitSqlScriptDelimitedWithSemicolon() {
 	}
 
 	@Test
+	@SuppressWarnings("deprecation")
 	public void splitSqlScriptDelimitedWithNewLine() {
 		String statement1 = "insert into customer (id, name) values (1, 'Rod ; Johnson'), (2, 'Adrian \n Collier')";
 		String statement2 = "insert into orders(id, order_date, customer_id) values (1, '2008-01-02', 2)";
@@ -82,6 +84,7 @@ public void splitSqlScriptDelimitedWithNewLine() {
 	}
 
 	@Test
+	@SuppressWarnings("deprecation")
 	public void splitSqlScriptDelimitedWithNewLineButDefaultDelimiterSpecified() {
 		String statement1 = "do something";
 		String statement2 = "do something else";
@@ -96,6 +99,7 @@ public void splitSqlScriptDelimitedWithNewLineButDefaultDelimiterSpecified() {
 	}
 
 	@Test  // SPR-13218
+	@SuppressWarnings("deprecation")
 	public void splitScriptWithSingleQuotesNestedInsideDoubleQuotes() {
 		String statement1 = "select '1' as \"Dogbert's owner's\" from dual";
 		String statement2 = "select '2' as \"Dilbert's\" from dual";
@@ -110,6 +114,7 @@ public void splitScriptWithSingleQuotesNestedInsideDoubleQuotes() {
 	}
 
 	@Test  // SPR-11560
+	@SuppressWarnings("deprecation")
 	public void readAndSplitScriptWithMultipleNewlinesAsSeparator() throws Exception {
 		String script = readScript("db-test-data-multi-newline.sql");
 		List<String> statements = new ArrayList<>();
@@ -139,6 +144,7 @@ public void readAndSplitScriptContainingCommentsWithMultiplePrefixes() throws Ex
 		splitScriptContainingComments(script, "--", "#", "^");
 	}
 
+	@SuppressWarnings("deprecation")
 	private void splitScriptContainingComments(String script, String... commentPrefixes) {
 		List<String> statements = new ArrayList<>();
 		splitSqlScript(null, script, ";", commentPrefixes, DEFAULT_BLOCK_COMMENT_START_DELIMITER,
@@ -154,6 +160,7 @@ private void splitScriptContainingComments(String script, String... commentPrefi
 	}
 
 	@Test  // SPR-10330
+	@SuppressWarnings("deprecation")
 	public void readAndSplitScriptContainingCommentsWithLeadingTabs() throws Exception {
 		String script = readScript("test-data-with-comments-and-leading-tabs.sql");
 		List<String> statements = new ArrayList<>();
@@ -167,6 +174,7 @@ public void readAndSplitScriptContainingCommentsWithLeadingTabs() throws Excepti
 	}
 
 	@Test  // SPR-9531
+	@SuppressWarnings("deprecation")
 	public void readAndSplitScriptContainingMultiLineComments() throws Exception {
 		String script = readScript("test-data-with-multi-line-comments.sql");
 		List<String> statements = new ArrayList<>();
@@ -179,6 +187,7 @@ public void readAndSplitScriptContainingMultiLineComments() throws Exception {
 	}
 
 	@Test
+	@SuppressWarnings("deprecation")
 	public void readAndSplitScriptContainingMultiLineNestedComments() throws Exception {
 		String script = readScript("test-data-with-multi-line-nested-comments.sql");
 		List<String> statements = new ArrayList<>();
@@ -222,6 +231,7 @@ public void readAndSplitScriptContainingMultiLineNestedComments() throws Excepti
 		"'/* double \" quotes */\ninsert into colors(color_num) values(42);'                # ;      # true",
 		"'/* double \\\" quotes */\ninsert into colors(color_num) values(42);'              # ;      # true"
 	})
+	@SuppressWarnings("deprecation")
 	public void containsStatementSeparator(String script, String delimiter, boolean expected) {
 		// Indirectly tests ScriptUtils.containsStatementSeparator(EncodedResource, String, String, String[], String, String).
 		assertThat(containsSqlScriptDelimiters(script, delimiter)).isEqualTo(expected);