8144082: Add Statement.enquoteNCharLiteral

Reviewed-by: joehw

jdk/src/java.sql/share/classes/java/sql/Statement.java

@@ -1582,4 +1582,43 @@ public interface Statement extends Wrapper, AutoCloseable {
         return len >= 1 && len <= 128
                 && Pattern.compile("[\\p{Alpha}][\\p{Alnum}_]*").matcher(identifier).matches();
     }
+
+    /**
+    * Returns a {@code String} representing a National Character Set Literal
+    * enclosed in single quotes and prefixed with a upper case letter N.
+    * Any occurrence of a single quote within the string will be replaced
+    * by two single quotes.
+    *
+    * <blockquote>
+    * <table border = 1 cellspacing=0 cellpadding=5 >
+    * <caption>Examples of the conversion:</caption>
+    * <tr>
+    * <th>Value</th>
+    * <th>Result</th>
+    * </tr>
+    * <tr> <td align='center'>Hello</td> <td align='center'>N'Hello'</td> </tr>
+    * <tr> <td align='center'>G'Day</td> <td align='center'>N'G''Day'</td> </tr>
+    * <tr> <td align='center'>'G''Day'</td>
+    * <td align='center'>N'''G''''Day'''</td> </tr>
+    * <tr> <td align='center'>I'''M</td> <td align='center'>N'I''''''M'</td>
+    * <tr> <td align='center'>N'Hello'</td> <td align='center'>N'N''Hello'''</td> </tr>
+    *
+    * </table>
+    * </blockquote>
+    * @implNote
+    * JDBC driver implementations may need to provide their own implementation
+    * of this method in order to meet the requirements of the underlying
+    * datasource. An implementation of enquoteNCharLiteral may accept a different
+    * set of characters than that accepted by the same drivers implementation of
+    * enquoteLiteral.
+    * @param val a character string
+    * @return the result of replacing every single quote character in the
+    * argument by two single quote characters where this entire result is
+    * then prefixed with 'N'.
+    * @throws NullPointerException if val is {@code null}
+    * @throws SQLException if a database access error occurs
+    */
+    default String enquoteNCharLiteral(String val)  throws SQLException {
+        return "N'" + val.replace("'", "''") +  "'";
+   }
 }

jdk/test/java/sql/testng/test/sql/StatementTests.java

@@ -65,7 +65,7 @@ public class StatementTests extends BaseTest {
      * enquoteLiteral is null
      */
     @Test(expectedExceptions = NullPointerException.class)
-    public void test01()  throws SQLException {
+    public void test01() throws SQLException {
         stmt.enquoteLiteral(null);
 
     }
@@ -110,7 +110,7 @@ public class StatementTests extends BaseTest {
     }
 
     /*
-     * Validate a NullPointerException is thrown is the string passed to
+     * Validate a NullPointerException is thrown if the string passed to
      * isSimpleIdentifier is null
      */
     @Test(expectedExceptions = NullPointerException.class)
@@ -119,6 +119,24 @@ public class StatementTests extends BaseTest {
 
     }
 
+    /*
+     * Verify that enquoteLiteral creates a  valid literal and converts every
+     * single quote to two single quotes
+     */
+    @Test(dataProvider = "validEnquotedNCharLiteralValues")
+    public void test07(String s, String expected) throws SQLException {
+        assertEquals(stmt.enquoteNCharLiteral(s), expected);
+    }
+
+    /*
+     * Validate a NullPointerException is thrown if the string passed to
+     * enquoteNCharLiteral is null
+     */
+    @Test(expectedExceptions = NullPointerException.class)
+    public void test08() throws SQLException {
+        stmt.enquoteNCharLiteral(null);
+    }
+
     /*
      * DataProvider used to provide strings that will be used to validate
      * that enquoteLiteral converts a string to a literal and every instance of
@@ -169,8 +187,7 @@ public class StatementTests extends BaseTest {
             {"\"Hel\"lo\"", true},
             {"Hello" + '\0', false},
             {"", false},
-            {maxIdentifier + 'a', false},
-            };
+            {maxIdentifier + 'a', false},};
     }
 
     /*
@@ -194,4 +211,22 @@ public class StatementTests extends BaseTest {
             {"", false},};
     }
 
+    /*
+     * DataProvider used to provide strings that will be used to validate
+     * that enquoteNCharLiteral converts a string to a National Character
+     * literal and every instance of
+     * a single quote will be converted into two single quotes in the literal.
+     */
+    @DataProvider(name = "validEnquotedNCharLiteralValues")
+    protected Object[][] validEnquotedNCharLiteralValues() {
+        return new Object[][]{
+            {"Hello", "N'Hello'"},
+            {"G'Day", "N'G''Day'"},
+            {"'G''Day'", "N'''G''''Day'''"},
+            {"I'''M", "N'I''''''M'"},
+            {"N'Hello'", "N'N''Hello'''"},
+            {"The Dark Knight", "N'The Dark Knight'"}
+
+        };
+    }
 }