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.SQLException;
012
013/**
014 * Supplies JDBC connections for SDK operations.
015 * <p>
016 * SDK-provided DataSource-backed implementations obtain a connection lazily
017 * for each operation and close it when the operation completes. If the
018 * DataSource is pooled, closing normally returns the connection to the pool.
019 * The SDK does not own or close the application-provided DataSource.
020 * <p>
021 * SDK-provided single-connection implementations reuse one retained JDBC
022 * connection for the lifetime of the owning client or connection object. The
023 * connection is opened when the owner is created and is closed when the owner
024 * is closed.
025 * <p>
026 * Connection ownership and cleanup depend on the implementation. A retained
027 * connection is closed by its owning {@code SelectAI}, {@code DatabaseAdmin},
028 * or {@code DbConnection} object.
029 * <p>
030 * This interface does not define transaction boundaries. SDK-provided
031 * implementations do not explicitly commit or roll back transactions and do
032 * not change the connection {@code autoCommit} setting. Any implicit commit or
033 * rollback performed by the underlying Oracle Database API is outside the
034 * SDK's transaction management.
035 * <p>
036 * Thread safety is implementation-specific and is not guaranteed by this
037 * interface. DataSource-backed implementations may support concurrent
038 * independent operations according to the {@code DataSource} contract. A
039 * single-connection implementation should be treated as single-threaded
040 * unless the connection owner provides synchronization.
041 * <p>
042 * Application code normally obtains SDK clients through public factory methods
043 * such as {@link SelectAI#create(javax.sql.DataSource)} and
044 * {@link SelectAI#create(com.oracle.database.selectai.model.DbConnectionConfig)}.
045 * Concrete provider implementations are internal SDK details.
046 */
047public interface ConnectionProvider {
048    /**
049     * Executes one SDK operation with a connection supplied by this provider.
050     * <p>
051     * The callback is invoked synchronously. The callback must close any JDBC
052     * resources it creates, such as statements and result sets, but must not
053     * close, retain, or use the supplied connection after the callback returns.
054     * <p>
055     * For SDK-provided DataSource implementations, the connection is borrowed
056     * for the operation and closed afterward. For SDK-provided single-connection
057     * implementations, the connection is reused and remains owned by the
058     * configured connection owner.
059     *
060     * @param callback non-null callback containing the JDBC operation
061     * @param <T> result type returned by the callback; may be {@code null}
062     * @return result returned by the callback
063     * @throws IllegalArgumentException when {@code callback} is null
064     * @throws SQLException if connection acquisition or a JDBC operation
065     *         performed by the callback fails
066     * @throws SelectAIException when SDK-specific work fails
067     * @throws RuntimeException when the callback fails with an unchecked exception
068     */
069    <T> T withConnection(ConnectionCallback<T> callback) throws SQLException, SelectAIException;
070}