1521 * boundaries. Committed database state is not local.
1522 *
1523 * @implSpec
1524 * The default implementation is a no-op.
1525 * <p>
1526 * @apiNote
1527 * This method is to be used by Connection pooling managers.
1528 * <p>
1529 * The pooling manager should call {@code beginRequest} on the underlying connection
1530 * prior to returning a connection to the caller.
1531 * <p>
1532 * The pooling manager does not need to call {@code beginRequest} if:
1533 * <ul>
1534 * <li>The connection pool caches {@code PooledConnection} objects</li>
1535 * <li>Returns a logical connection handle when {@code getConnection} is
1536 * called by the application</li>
1537 * <li>The pool manager calls {@code Connection.close} on the logical connection handle
1538 * prior to returning the {@code PooledConnection} back to the cache</li>
1539 * </ul>
1540 * @throws SQLException if an error occurs
1541 * @since 1.9
1542 * @see endRequest
1543 * @see javax.sql.PooledConnection
1544 */
1545 default void beginRequest() throws SQLException {
1546 // Default method takes no action
1547 }
1548
1549 /**
1550 * Hints to the driver that a request, an independent unit of work,
1551 * has completed. Calls to {@code beginRequest}
1552 * and {@code endRequest} are not nested. Multiple
1553 * calls to {@code endRequest} without an intervening call to {@code beginRequest}
1554 * is not an error. The first {@code endRequest} call
1555 * marks the request completed and subsequent calls are treated as
1556 * a no-op. If {@code endRequest} is called without an initial call to
1557 * {@code beginRequest} is a no-op.
1558 *<p>
1559 * The exact behavior of this method is vendor specific. In particular
1560 * implementations may detect conditions that indicate dependence on
1561 * other work such as an open transaction. It is recommended though not
1563 * transaction and {@code endRequest} is called.
1564 *
1565 * @implSpec
1566 * The default implementation is a no-op.
1567 * @apiNote
1568 *
1569 * This method is to be used by Connection pooling managers.
1570 * <p>
1571 * The pooling manager should call {@code endRequest} on the underlying connection
1572 * when the applications returns the connection back to the connection pool.
1573 * <p>
1574 * The pooling manager does not need to call {@code endRequest} if:
1575 * <ul>
1576 * <li>The connection pool caches {@code PooledConnection} objects</li>
1577 * <li>Returns a logical connection handle when {@code getConnection} is
1578 * called by the application</li>
1579 * <li>The pool manager calls {@code Connection.close} on the logical connection handle
1580 * prior to returning the {@code PooledConnection} back to the cache</li>
1581 * </ul>
1582 * @throws SQLException if an error occurs
1583 * @since 1.9
1584 * @see beginRequest
1585 * @see javax.sql.PooledConnection
1586 */
1587 default void endRequest() throws SQLException {
1588 // Default method takes no action
1589 }
1590
1591 /**
1592 * Sets and validates the sharding keys for this connection.
1593 * @implSpec
1594 * The default implementation will throw a
1595 * {@code SQLFeatureNotSupportedException}.
1596 *
1597 * @apiNote
1598 * This method validates that the sharding keys are valid for the
1599 * {@code Connection}. The timeout value indicates how long the driver
1600 * should wait for the {@code Connection} to verify that the sharding key
1601 * is valid before {@code setShardingKeyIfValid} returns false.
1602 * @param shardingKey the sharding key to be validated against this connection
1603 * @param superShardingKey the super sharding key to be validated against this
1604 * connection. The super sharding key may be {@code null}.
1605 * @param timeout time in seconds before which the validation process is expected to
1606 * be completed, otherwise the validation process is aborted. A value of 0 indicates
1607 * the validation process will not time out.
1608 * @return true if the connection is valid and the sharding keys are valid
1609 * and set on this connection; false if the sharding keys are not valid or
1610 * the timeout period expires before the operation completes.
1611 * @throws SQLException if an error occurs while performing this validation;
1612 * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified
1613 * without a {@code shardingKey};
1614 * this method is called on a closed {@code connection}; or
1615 * the {@code timeout} value is less than 0.
1616 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1617 * @since 1.9
1618 * @see ShardingKey
1619 * @see ShardingKeyBuilder
1620 */
1621 default boolean setShardingKeyIfValid(ShardingKey shardingKey,
1622 ShardingKey superShardingKey, int timeout)
1623 throws SQLException {
1624 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
1625 }
1626
1627 /**
1628 * Sets and validates the sharding key for this connection.
1629 * @implSpec
1630 * The default implementation will throw a
1631 * {@code SQLFeatureNotSupportedException}.
1632 * @apiNote
1633 * This method validates that the sharding key is valid for the
1634 * {@code Connection}. The timeout value indicates how long the driver
1635 * should wait for the {@code Connection} to verify that the sharding key
1636 * is valid before {@code setShardingKeyIfValid} returns false.
1637 * @param shardingKey the sharding key to be validated against this connection
1638 * @param timeout time in seconds before which the validation process is expected to
1639 * be completed,else the validation process is aborted. A value of 0 indicates
1640 * the validation process will not time out.
1641 * @return true if the connection is valid and the sharding key is valid to be
1642 * set on this connection; false if the sharding key is not valid or
1643 * the timeout period expires before the operation completes.
1644 * @throws SQLException if there is an error while performing this validation;
1645 * this method is called on a closed {@code connection}; the {@code shardingkey}
1646 * is {@code null}; or the {@code timeout} value is less than 0.
1647 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1648 * @since 1.9
1649 * @see ShardingKey
1650 * @see ShardingKeyBuilder
1651 */
1652 default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout)
1653 throws SQLException {
1654 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
1655 }
1656
1657 /**
1658 * Specifies a shardingKey and superShardingKey to use with this Connection
1659 * @implSpec
1660 * The default implementation will throw a
1661 * {@code SQLFeatureNotSupportedException}.
1662 * @apiNote
1663 * This method sets the specified sharding keys but does not require a
1664 * round trip to the database to validate that the sharding keys are valid
1665 * for the {@code Connection}.
1666 * @param shardingKey the sharding key to set on this connection.
1667 * @param superShardingKey the super sharding key to set on this connection.
1668 * The super sharding key may be {@code null}
1669 * @throws SQLException if an error occurs setting the sharding keys;
1670 * this method is called on a closed {@code connection};
1671 * the {@code shardingkey} is {@code null}; or
1672 * a {@code superSharedingKey} is specified without a {@code shardingKey}
1673 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1674 * @since 1.9
1675 * @see ShardingKey
1676 * @see ShardingKeyBuilder
1677 */
1678 default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)
1679 throws SQLException {
1680 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
1681 }
1682
1683 /**
1684 * Specifies a shardingKey to use with this Connection
1685 * @implSpec
1686 * The default implementation will throw a
1687 * {@code SQLFeatureNotSupportedException}.
1688 * @apiNote
1689 * This method sets the specified sharding key but does not require a
1690 * round trip to the database to validate that the sharding key is valid
1691 * for the {@code Connection}.
1692 * @param shardingKey the sharding key to set on this connection.
1693 * @throws SQLException if an error occurs setting the sharding key;
1694 * this method is called on a closed {@code connection}; or the
1695 * {@code shardkingKey} is {@code null}
1696 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1697 * @since 1.9
1698 * @see ShardingKey
1699 * @see ShardingKeyBuilder
1700 */
1701 default void setShardingKey(ShardingKey shardingKey)
1702 throws SQLException {
1703 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
1704 }
1705 }
|
1521 * boundaries. Committed database state is not local.
1522 *
1523 * @implSpec
1524 * The default implementation is a no-op.
1525 * <p>
1526 * @apiNote
1527 * This method is to be used by Connection pooling managers.
1528 * <p>
1529 * The pooling manager should call {@code beginRequest} on the underlying connection
1530 * prior to returning a connection to the caller.
1531 * <p>
1532 * The pooling manager does not need to call {@code beginRequest} if:
1533 * <ul>
1534 * <li>The connection pool caches {@code PooledConnection} objects</li>
1535 * <li>Returns a logical connection handle when {@code getConnection} is
1536 * called by the application</li>
1537 * <li>The pool manager calls {@code Connection.close} on the logical connection handle
1538 * prior to returning the {@code PooledConnection} back to the cache</li>
1539 * </ul>
1540 * @throws SQLException if an error occurs
1541 * @since 9
1542 * @see endRequest
1543 * @see javax.sql.PooledConnection
1544 */
1545 default void beginRequest() throws SQLException {
1546 // Default method takes no action
1547 }
1548
1549 /**
1550 * Hints to the driver that a request, an independent unit of work,
1551 * has completed. Calls to {@code beginRequest}
1552 * and {@code endRequest} are not nested. Multiple
1553 * calls to {@code endRequest} without an intervening call to {@code beginRequest}
1554 * is not an error. The first {@code endRequest} call
1555 * marks the request completed and subsequent calls are treated as
1556 * a no-op. If {@code endRequest} is called without an initial call to
1557 * {@code beginRequest} is a no-op.
1558 *<p>
1559 * The exact behavior of this method is vendor specific. In particular
1560 * implementations may detect conditions that indicate dependence on
1561 * other work such as an open transaction. It is recommended though not
1563 * transaction and {@code endRequest} is called.
1564 *
1565 * @implSpec
1566 * The default implementation is a no-op.
1567 * @apiNote
1568 *
1569 * This method is to be used by Connection pooling managers.
1570 * <p>
1571 * The pooling manager should call {@code endRequest} on the underlying connection
1572 * when the applications returns the connection back to the connection pool.
1573 * <p>
1574 * The pooling manager does not need to call {@code endRequest} if:
1575 * <ul>
1576 * <li>The connection pool caches {@code PooledConnection} objects</li>
1577 * <li>Returns a logical connection handle when {@code getConnection} is
1578 * called by the application</li>
1579 * <li>The pool manager calls {@code Connection.close} on the logical connection handle
1580 * prior to returning the {@code PooledConnection} back to the cache</li>
1581 * </ul>
1582 * @throws SQLException if an error occurs
1583 * @since 9
1584 * @see beginRequest
1585 * @see javax.sql.PooledConnection
1586 */
1587 default void endRequest() throws SQLException {
1588 // Default method takes no action
1589 }
1590
1591 /**
1592 * Sets and validates the sharding keys for this connection.
1593 * @implSpec
1594 * The default implementation will throw a
1595 * {@code SQLFeatureNotSupportedException}.
1596 *
1597 * @apiNote
1598 * This method validates that the sharding keys are valid for the
1599 * {@code Connection}. The timeout value indicates how long the driver
1600 * should wait for the {@code Connection} to verify that the sharding key
1601 * is valid before {@code setShardingKeyIfValid} returns false.
1602 * @param shardingKey the sharding key to be validated against this connection
1603 * @param superShardingKey the super sharding key to be validated against this
1604 * connection. The super sharding key may be {@code null}.
1605 * @param timeout time in seconds before which the validation process is expected to
1606 * be completed, otherwise the validation process is aborted. A value of 0 indicates
1607 * the validation process will not time out.
1608 * @return true if the connection is valid and the sharding keys are valid
1609 * and set on this connection; false if the sharding keys are not valid or
1610 * the timeout period expires before the operation completes.
1611 * @throws SQLException if an error occurs while performing this validation;
1612 * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified
1613 * without a {@code shardingKey};
1614 * this method is called on a closed {@code connection}; or
1615 * the {@code timeout} value is less than 0.
1616 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1617 * @since 9
1618 * @see ShardingKey
1619 * @see ShardingKeyBuilder
1620 */
1621 default boolean setShardingKeyIfValid(ShardingKey shardingKey,
1622 ShardingKey superShardingKey, int timeout)
1623 throws SQLException {
1624 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
1625 }
1626
1627 /**
1628 * Sets and validates the sharding key for this connection.
1629 * @implSpec
1630 * The default implementation will throw a
1631 * {@code SQLFeatureNotSupportedException}.
1632 * @apiNote
1633 * This method validates that the sharding key is valid for the
1634 * {@code Connection}. The timeout value indicates how long the driver
1635 * should wait for the {@code Connection} to verify that the sharding key
1636 * is valid before {@code setShardingKeyIfValid} returns false.
1637 * @param shardingKey the sharding key to be validated against this connection
1638 * @param timeout time in seconds before which the validation process is expected to
1639 * be completed,else the validation process is aborted. A value of 0 indicates
1640 * the validation process will not time out.
1641 * @return true if the connection is valid and the sharding key is valid to be
1642 * set on this connection; false if the sharding key is not valid or
1643 * the timeout period expires before the operation completes.
1644 * @throws SQLException if there is an error while performing this validation;
1645 * this method is called on a closed {@code connection}; the {@code shardingkey}
1646 * is {@code null}; or the {@code timeout} value is less than 0.
1647 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1648 * @since 9
1649 * @see ShardingKey
1650 * @see ShardingKeyBuilder
1651 */
1652 default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout)
1653 throws SQLException {
1654 throw new SQLFeatureNotSupportedException("setShardingKeyIfValid not implemented");
1655 }
1656
1657 /**
1658 * Specifies a shardingKey and superShardingKey to use with this Connection
1659 * @implSpec
1660 * The default implementation will throw a
1661 * {@code SQLFeatureNotSupportedException}.
1662 * @apiNote
1663 * This method sets the specified sharding keys but does not require a
1664 * round trip to the database to validate that the sharding keys are valid
1665 * for the {@code Connection}.
1666 * @param shardingKey the sharding key to set on this connection.
1667 * @param superShardingKey the super sharding key to set on this connection.
1668 * The super sharding key may be {@code null}
1669 * @throws SQLException if an error occurs setting the sharding keys;
1670 * this method is called on a closed {@code connection};
1671 * the {@code shardingkey} is {@code null}; or
1672 * a {@code superSharedingKey} is specified without a {@code shardingKey}
1673 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1674 * @since 9
1675 * @see ShardingKey
1676 * @see ShardingKeyBuilder
1677 */
1678 default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)
1679 throws SQLException {
1680 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
1681 }
1682
1683 /**
1684 * Specifies a shardingKey to use with this Connection
1685 * @implSpec
1686 * The default implementation will throw a
1687 * {@code SQLFeatureNotSupportedException}.
1688 * @apiNote
1689 * This method sets the specified sharding key but does not require a
1690 * round trip to the database to validate that the sharding key is valid
1691 * for the {@code Connection}.
1692 * @param shardingKey the sharding key to set on this connection.
1693 * @throws SQLException if an error occurs setting the sharding key;
1694 * this method is called on a closed {@code connection}; or the
1695 * {@code shardkingKey} is {@code null}
1696 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
1697 * @since 9
1698 * @see ShardingKey
1699 * @see ShardingKeyBuilder
1700 */
1701 default void setShardingKey(ShardingKey shardingKey)
1702 throws SQLException {
1703 throw new SQLFeatureNotSupportedException("setShardingKey not implemented");
1704 }
1705 }
|