001/*
002 * Copyright (c) 2026, Oracle and/or its affiliates.
003 *
004 * Licensed under the Universal Permissive License Version 1.0 as shown at
005 * https://oss.oracle.com/licenses/upl/
006 */
007package com.oracle.database.selectai;
008
009import com.oracle.database.selectai.model.SelectAIException;
010
011import java.sql.Connection;
012import java.sql.SQLException;
013
014/**
015 * Functional unit of JDBC work executed synchronously with a connection
016 * supplied by a {@link ConnectionProvider}.
017 * <p>
018 * The callback does not own the supplied connection and must not close it,
019 * retain it, or use it after this method returns. Connection acquisition and
020 * operation lifecycle are controlled by the {@link ConnectionProvider}; a
021 * retained connection is closed by its owning {@link SelectAI},
022 * {@link DatabaseAdmin}, or {@link DbConnection} object.
023 * <p>
024 * Depending on the provider, the connection may be borrowed for one operation
025 * or reused across multiple SDK operations.
026 *
027 * @param <T> result type returned by the JDBC work; may be {@code null}
028 */
029@FunctionalInterface
030public interface ConnectionCallback<T> {
031    /**
032     * Executes JDBC work with the connection supplied by the provider.
033     * <p>
034     * This method is invoked synchronously. Any JDBC resources created by the
035     * callback, such as statements or result sets, must be closed by the
036     * callback. The callback must not close the supplied connection.
037     *
038     * @param connection non-null JDBC connection supplied for the current operation
039     * @return result produced by the JDBC work, or {@code null}
040     * @throws SQLException if a JDBC operation performed by the callback fails
041     * @throws SelectAIException when SDK-specific validation or nested work fails
042     * @throws RuntimeException when the callback fails with an unchecked exception
043     */
044    T execute(Connection connection) throws SQLException, SelectAIException;
045}