1362 * <code>PreparedStatement</code> or <code>CallableStatement</code>
1363 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1364 * @throws SQLTimeoutException when the driver has determined that the
1365 * timeout value that was specified by the {@code setQueryTimeout}
1366 * method has been exceeded and has at least attempted to cancel
1367 * the currently running {@code Statement}
1368 * @since 1.8
1369 */
1370 default long executeLargeUpdate(String sql, String columnNames[])
1371 throws SQLException {
1372 throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
1373 }
1374
1375 // JDBC 4.3
1376
1377 /**
1378 * Returns a {@code String} enclosed in single quotes. Any occurrence of a
1379 * single quote within the string will be replaced by two single quotes.
1380 *
1381 * <blockquote>
1382 * <table border = 1 cellspacing=0 cellpadding=5 >
1383 * <caption>Examples of the conversion:</caption>
1384 * <tr><th>Value</th><th>Result</th></tr>
1385 * <tr> <td align='center'>Hello</td> <td align='center'>'Hello'</td> </tr>
1386 * <tr> <td align='center'>G'Day</td> <td align='center'>'G''Day'</td> </tr>
1387 * <tr> <td align='center'>'G''Day'</td>
1388 * <td align='center'>'''G''''Day'''</td> </tr>
1389 * <tr> <td align='center'>I'''M</td> <td align='center'>'I''''''M'</td>
1390 * </tr>
1391 *
1392 * </table>
1393 * </blockquote>
1394 * @implNote
1395 * JDBC driver implementations may need to provide their own implementation
1396 * of this method in order to meet the requirements of the underlying
1397 * datasource.
1398 * @param val a character string
1399 * @return A string enclosed by single quotes with every single quote
1400 * converted to two single quotes
1401 * @throws NullPointerException if val is {@code null}
1402 * @throws SQLException if a database access error occurs
1403 *
1404 * @since 9
1405 */
1406 default String enquoteLiteral(String val) throws SQLException {
1407 return "'" + val.replace("'", "''") + "'";
1408 }
1409
1410
1411 /**
1429 * characters invalid in a delimited identifier or the identifier length is
1430 * invalid for the datasource.
1431 *
1432 * @implSpec
1433 * The default implementation uses the following criteria to
1434 * determine a valid simple SQL identifier:
1435 * <ul>
1436 * <li>The string is not enclosed in double quotes</li>
1437 * <li>The first character is an alphabetic character from a through z, or
1438 * from A through Z</li>
1439 * <li>The name only contains alphanumeric characters or the character "_"</li>
1440 * </ul>
1441 *
1442 * The default implementation will throw a {@code SQLException} if:
1443 * <ul>
1444 * <li>{@code identifier} contains a {@code null} character or double quote and is not
1445 * a simple SQL identifier.</li>
1446 * <li>The length of {@code identifier} is less than 1 or greater than 128 characters
1447 * </ul>
1448 * <blockquote>
1449 * <table border = 1 cellspacing=0 cellpadding=5 >
1450 * <caption>Examples of the conversion:</caption>
1451 * <tr>
1452 * <th>identifier</th>
1453 * <th>alwaysQuote</th>
1454 * <th>Result</th></tr>
1455 * <tr>
1456 * <td align='center'>Hello</td>
1457 * <td align='center'>false</td>
1458 * <td align='center'>Hello</td>
1459 * </tr>
1460 * <tr>
1461 * <td align='center'>Hello</td>
1462 * <td align='center'>true</td>
1463 * <td align='center'>"Hello"</td>
1464 * </tr>
1465 * <tr>
1466 * <td align='center'>G'Day</td>
1467 * <td align='center'>false</td>
1468 * <td align='center'>"G'Day"</td>
1469 * </tr>
1470 * <tr>
1471 * <td align='center'>"Bruce Wayne"</td>
1472 * <td align='center'>false</td>
1473 * <td align='center'>"Bruce Wayne"</td>
1474 * </tr>
1475 * <tr>
1476 * <td align='center'>"Bruce Wayne"</td>
1477 * <td align='center'>true</td>
1478 * <td align='center'>"Bruce Wayne"</td>
1479 * </tr>
1480 * <tr>
1481 * <td align='center'>GoodDay$</td>
1482 * <td align='center'>false</td>
1483 * <td align='center'>"GoodDay$"</td>
1484 * </tr>
1485 * <tr>
1486 * <td align='center'>Hello"World</td>
1487 * <td align='center'>false</td>
1488 * <td align='center'>SQLException</td>
1489 * </tr>
1490 * <tr>
1491 * <td align='center'>"Hello"World"</td>
1492 * <td align='center'>false</td>
1493 * <td align='center'>SQLException</td>
1494 * </tr>
1495 * </table>
1496 * </blockquote>
1497 * @implNote
1498 * JDBC driver implementations may need to provide their own implementation
1499 * of this method in order to meet the requirements of the underlying
1500 * datasource.
1501 * @param identifier a SQL identifier
1502 * @param alwaysQuote indicates if a simple SQL identifier should be
1503 * returned as a quoted identifier
1504 * @return A simple SQL identifier or a delimited identifier
1505 * @throws SQLException if identifier is not a valid identifier
1506 * @throws SQLFeatureNotSupportedException if the datasource does not support
1507 * delimited identifiers
1508 * @throws NullPointerException if identifier is {@code null}
1509 *
1510 * @since 9
1511 */
1512 default String enquoteIdentifier(String identifier, boolean alwaysQuote) throws SQLException {
1513 int len = identifier.length();
1514 if (len < 1 || len > 128) {
1525 } else {
1526 throw new SQLException("Invalid name");
1527 }
1528 }
1529
1530 /**
1531 * Retrieves whether {@code identifier} is a simple SQL identifier.
1532 *
1533 * @implSpec The default implementation uses the following criteria to
1534 * determine a valid simple SQL identifier:
1535 * <ul>
1536 * <li>The string is not enclosed in double quotes</li>
1537 * <li>The first character is an alphabetic character from a through z, or
1538 * from A through Z</li>
1539 * <li>The string only contains alphanumeric characters or the character
1540 * "_"</li>
1541 * <li>The string is between 1 and 128 characters in length inclusive</li>
1542 * </ul>
1543 *
1544 * <blockquote>
1545 * <table border = 1 cellspacing=0 cellpadding=5 >
1546 * <caption>Examples of the conversion:</caption>
1547 * <tr>
1548 * <th>identifier</th>
1549 * <th>Simple Identifier</th>
1550 *
1551 * <tr>
1552 * <td align='center'>Hello</td>
1553 * <td align='center'>true</td>
1554 * </tr>
1555 * <tr>
1556 * <td align='center'>G'Day</td>
1557 * <td align='center'>false</td>
1558 * </tr>
1559 * <tr>
1560 * <td align='center'>"Bruce Wayne"</td>
1561 * <td align='center'>false</td>
1562 * </tr>
1563 * <tr>
1564 * <td align='center'>GoodDay$</td>
1565 * <td align='center'>false</td>
1566 * </tr>
1567 * <tr>
1568 * <td align='center'>Hello"World</td>
1569 * <td align='center'>false</td>
1570 * </tr>
1571 * <tr>
1572 * <td align='center'>"Hello"World"</td>
1573 * <td align='center'>false</td>
1574 * </tr>
1575 * </table>
1576 * </blockquote>
1577 * @implNote JDBC driver implementations may need to provide their own
1578 * implementation of this method in order to meet the requirements of the
1579 * underlying datasource.
1580 * @param identifier a SQL identifier
1581 * @return true if a simple SQL identifier, false otherwise
1582 * @throws NullPointerException if identifier is {@code null}
1583 * @throws SQLException if a database access error occurs
1584 *
1585 * @since 9
1586 */
1587 default boolean isSimpleIdentifier(String identifier) throws SQLException {
1588 int len = identifier.length();
1589 return len >= 1 && len <= 128
1590 && Pattern.compile("[\\p{Alpha}][\\p{Alnum}_]*").matcher(identifier).matches();
1591 }
1592
1593 /**
1594 * Returns a {@code String} representing a National Character Set Literal
1595 * enclosed in single quotes and prefixed with a upper case letter N.
1596 * Any occurrence of a single quote within the string will be replaced
1597 * by two single quotes.
1598 *
1599 * <blockquote>
1600 * <table border = 1 cellspacing=0 cellpadding=5 >
1601 * <caption>Examples of the conversion:</caption>
1602 * <tr>
1603 * <th>Value</th>
1604 * <th>Result</th>
1605 * </tr>
1606 * <tr> <td align='center'>Hello</td> <td align='center'>N'Hello'</td> </tr>
1607 * <tr> <td align='center'>G'Day</td> <td align='center'>N'G''Day'</td> </tr>
1608 * <tr> <td align='center'>'G''Day'</td>
1609 * <td align='center'>N'''G''''Day'''</td> </tr>
1610 * <tr> <td align='center'>I'''M</td> <td align='center'>N'I''''''M'</td>
1611 * <tr> <td align='center'>N'Hello'</td> <td align='center'>N'N''Hello'''</td> </tr>
1612 *
1613 * </table>
1614 * </blockquote>
1615 * @implNote
1616 * JDBC driver implementations may need to provide their own implementation
1617 * of this method in order to meet the requirements of the underlying
1618 * datasource. An implementation of enquoteNCharLiteral may accept a different
1619 * set of characters than that accepted by the same drivers implementation of
1620 * enquoteLiteral.
1621 * @param val a character string
1622 * @return the result of replacing every single quote character in the
1623 * argument by two single quote characters where this entire result is
1624 * then prefixed with 'N'.
1625 * @throws NullPointerException if val is {@code null}
1626 * @throws SQLException if a database access error occurs
1627 *
1628 * @since 9
1629 */
1630 default String enquoteNCharLiteral(String val) throws SQLException {
1631 return "N'" + val.replace("'", "''") + "'";
1632 }
|
1362 * <code>PreparedStatement</code> or <code>CallableStatement</code>
1363 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1364 * @throws SQLTimeoutException when the driver has determined that the
1365 * timeout value that was specified by the {@code setQueryTimeout}
1366 * method has been exceeded and has at least attempted to cancel
1367 * the currently running {@code Statement}
1368 * @since 1.8
1369 */
1370 default long executeLargeUpdate(String sql, String columnNames[])
1371 throws SQLException {
1372 throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
1373 }
1374
1375 // JDBC 4.3
1376
1377 /**
1378 * Returns a {@code String} enclosed in single quotes. Any occurrence of a
1379 * single quote within the string will be replaced by two single quotes.
1380 *
1381 * <blockquote>
1382 * <table class="striped" >
1383 * <caption>Examples of the conversion:</caption>
1384 * <thead>
1385 * <tr><th>Value</th><th>Result</th></tr>
1386 * </thead>
1387 * <tbody style="text-align:center">
1388 * <tr> <td>Hello</td> <td>'Hello'</td> </tr>
1389 * <tr> <td>G'Day</td> <td>'G''Day'</td> </tr>
1390 * <tr> <td>'G''Day'</td>
1391 * <td>'''G''''Day'''</td> </tr>
1392 * <tr> <td>I'''M</td> <td>'I''''''M'</td>
1393 * </tr>
1394 *
1395 * </tbody>
1396 * </table>
1397 * </blockquote>
1398 * @implNote
1399 * JDBC driver implementations may need to provide their own implementation
1400 * of this method in order to meet the requirements of the underlying
1401 * datasource.
1402 * @param val a character string
1403 * @return A string enclosed by single quotes with every single quote
1404 * converted to two single quotes
1405 * @throws NullPointerException if val is {@code null}
1406 * @throws SQLException if a database access error occurs
1407 *
1408 * @since 9
1409 */
1410 default String enquoteLiteral(String val) throws SQLException {
1411 return "'" + val.replace("'", "''") + "'";
1412 }
1413
1414
1415 /**
1433 * characters invalid in a delimited identifier or the identifier length is
1434 * invalid for the datasource.
1435 *
1436 * @implSpec
1437 * The default implementation uses the following criteria to
1438 * determine a valid simple SQL identifier:
1439 * <ul>
1440 * <li>The string is not enclosed in double quotes</li>
1441 * <li>The first character is an alphabetic character from a through z, or
1442 * from A through Z</li>
1443 * <li>The name only contains alphanumeric characters or the character "_"</li>
1444 * </ul>
1445 *
1446 * The default implementation will throw a {@code SQLException} if:
1447 * <ul>
1448 * <li>{@code identifier} contains a {@code null} character or double quote and is not
1449 * a simple SQL identifier.</li>
1450 * <li>The length of {@code identifier} is less than 1 or greater than 128 characters
1451 * </ul>
1452 * <blockquote>
1453 * <table class="striped" >
1454 * <caption>Examples of the conversion:</caption>
1455 * <thead>
1456 * <tr>
1457 * <th>identifier</th>
1458 * <th>alwaysQuote</th>
1459 * <th>Result</th></tr>
1460 * </thead>
1461 * <tbody>
1462 * <tr>
1463 * <td>Hello</td>
1464 * <td>false</td>
1465 * <td>Hello</td>
1466 * </tr>
1467 * <tr>
1468 * <td>Hello</td>
1469 * <td>true</td>
1470 * <td>"Hello"</td>
1471 * </tr>
1472 * <tr>
1473 * <td>G'Day</td>
1474 * <td>false</td>
1475 * <td>"G'Day"</td>
1476 * </tr>
1477 * <tr>
1478 * <td>"Bruce Wayne"</td>
1479 * <td>false</td>
1480 * <td>"Bruce Wayne"</td>
1481 * </tr>
1482 * <tr>
1483 * <td>"Bruce Wayne"</td>
1484 * <td>true</td>
1485 * <td>"Bruce Wayne"</td>
1486 * </tr>
1487 * <tr>
1488 * <td>GoodDay$</td>
1489 * <td>false</td>
1490 * <td>"GoodDay$"</td>
1491 * </tr>
1492 * <tr>
1493 * <td>Hello"World</td>
1494 * <td>false</td>
1495 * <td>SQLException</td>
1496 * </tr>
1497 * <tr>
1498 * <td>"Hello"World"</td>
1499 * <td>false</td>
1500 * <td>SQLException</td>
1501 * </tr>
1502 * </tbody>
1503 * </table>
1504 * </blockquote>
1505 * @implNote
1506 * JDBC driver implementations may need to provide their own implementation
1507 * of this method in order to meet the requirements of the underlying
1508 * datasource.
1509 * @param identifier a SQL identifier
1510 * @param alwaysQuote indicates if a simple SQL identifier should be
1511 * returned as a quoted identifier
1512 * @return A simple SQL identifier or a delimited identifier
1513 * @throws SQLException if identifier is not a valid identifier
1514 * @throws SQLFeatureNotSupportedException if the datasource does not support
1515 * delimited identifiers
1516 * @throws NullPointerException if identifier is {@code null}
1517 *
1518 * @since 9
1519 */
1520 default String enquoteIdentifier(String identifier, boolean alwaysQuote) throws SQLException {
1521 int len = identifier.length();
1522 if (len < 1 || len > 128) {
1533 } else {
1534 throw new SQLException("Invalid name");
1535 }
1536 }
1537
1538 /**
1539 * Retrieves whether {@code identifier} is a simple SQL identifier.
1540 *
1541 * @implSpec The default implementation uses the following criteria to
1542 * determine a valid simple SQL identifier:
1543 * <ul>
1544 * <li>The string is not enclosed in double quotes</li>
1545 * <li>The first character is an alphabetic character from a through z, or
1546 * from A through Z</li>
1547 * <li>The string only contains alphanumeric characters or the character
1548 * "_"</li>
1549 * <li>The string is between 1 and 128 characters in length inclusive</li>
1550 * </ul>
1551 *
1552 * <blockquote>
1553 * <table class="striped" >
1554 * <caption>Examples of the conversion:</caption>
1555 * <thead>
1556 * <tr>
1557 * <th>identifier</th>
1558 * <th>Simple Identifier</th>
1559 * </thead>
1560 *
1561 * <tbody>
1562 * <tr>
1563 * <td>Hello</td>
1564 * <td>true</td>
1565 * </tr>
1566 * <tr>
1567 * <td>G'Day</td>
1568 * <td>false</td>
1569 * </tr>
1570 * <tr>
1571 * <td>"Bruce Wayne"</td>
1572 * <td>false</td>
1573 * </tr>
1574 * <tr>
1575 * <td>GoodDay$</td>
1576 * <td>false</td>
1577 * </tr>
1578 * <tr>
1579 * <td>Hello"World</td>
1580 * <td>false</td>
1581 * </tr>
1582 * <tr>
1583 * <td>"Hello"World"</td>
1584 * <td>false</td>
1585 * </tr>
1586 * </tbody>
1587 * </table>
1588 * </blockquote>
1589 * @implNote JDBC driver implementations may need to provide their own
1590 * implementation of this method in order to meet the requirements of the
1591 * underlying datasource.
1592 * @param identifier a SQL identifier
1593 * @return true if a simple SQL identifier, false otherwise
1594 * @throws NullPointerException if identifier is {@code null}
1595 * @throws SQLException if a database access error occurs
1596 *
1597 * @since 9
1598 */
1599 default boolean isSimpleIdentifier(String identifier) throws SQLException {
1600 int len = identifier.length();
1601 return len >= 1 && len <= 128
1602 && Pattern.compile("[\\p{Alpha}][\\p{Alnum}_]*").matcher(identifier).matches();
1603 }
1604
1605 /**
1606 * Returns a {@code String} representing a National Character Set Literal
1607 * enclosed in single quotes and prefixed with a upper case letter N.
1608 * Any occurrence of a single quote within the string will be replaced
1609 * by two single quotes.
1610 *
1611 * <blockquote>
1612 * <table class="striped">
1613 * <caption>Examples of the conversion:</caption>
1614 * <thead>
1615 * <tr>
1616 * <th>Value</th>
1617 * <th>Result</th>
1618 * </tr>
1619 * </thead>
1620 * <tbody>
1621 * <tr> <td>Hello</td> <td>N'Hello'</td> </tr>
1622 * <tr> <td>G'Day</td> <td>N'G''Day'</td> </tr>
1623 * <tr> <td>'G''Day'</td>
1624 * <td>N'''G''''Day'''</td> </tr>
1625 * <tr> <td>I'''M</td> <td>N'I''''''M'</td>
1626 * <tr> <td>N'Hello'</td> <td>N'N''Hello'''</td> </tr>
1627 *
1628 * </tbody>
1629 * </table>
1630 * </blockquote>
1631 * @implNote
1632 * JDBC driver implementations may need to provide their own implementation
1633 * of this method in order to meet the requirements of the underlying
1634 * datasource. An implementation of enquoteNCharLiteral may accept a different
1635 * set of characters than that accepted by the same drivers implementation of
1636 * enquoteLiteral.
1637 * @param val a character string
1638 * @return the result of replacing every single quote character in the
1639 * argument by two single quote characters where this entire result is
1640 * then prefixed with 'N'.
1641 * @throws NullPointerException if val is {@code null}
1642 * @throws SQLException if a database access error occurs
1643 *
1644 * @since 9
1645 */
1646 default String enquoteNCharLiteral(String val) throws SQLException {
1647 return "N'" + val.replace("'", "''") + "'";
1648 }
|