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.impl.DbConnectionFactory;
010import com.oracle.database.selectai.model.DbConnectionConfig;
011import com.oracle.database.selectai.model.SelectAIException;
012
013import java.sql.Connection;
014
015/**
016 * Connection contract used by SDK implementations to execute SQL and PL/SQL
017 * against an Oracle database that has access to {@code DBMS_CLOUD_AI}.
018 * <p>
019 * {@code DbConnection} extends {@link AutoCloseable}. A {@code DbConnection}
020 * instance represents a JDBC-backed database connection used by the SDK.
021 * Callers should close the {@code DbConnection} when they own it and no longer
022 * need it, either by using try-with-resources or by calling {@link #close()}
023 * explicitly.
024 * <p>
025 * When a {@link SelectAI} client is created from
026 * {@link com.oracle.database.selectai.model.DbConnectionConfig}, the SDK owns the
027 * underlying JDBC connection and closes it when {@link SelectAI#close()} is
028 * called. When application code creates or holds a {@code DbConnection}
029 * directly, that application code is responsible for closing it.
030 */
031public interface DbConnection extends AutoCloseable {
032
033    /**
034     * Creates a JDBC-backed DbConnection from database connection configuration.
035     * <p>
036     * The returned object owns one JDBC connection. Call {@link #close()} when
037     * the connection is no longer needed.
038     *
039     * @param dbConnectionConfig database connection configuration
040     * @return initialized DbConnection
041     * @throws IllegalArgumentException when {@code dbConnectionConfig} is null
042     * @throws SelectAIException when the JDBC connection cannot be initialized
043     */
044    static DbConnection create(DbConnectionConfig dbConnectionConfig) throws SelectAIException {
045        return DbConnectionFactory.create(dbConnectionConfig);
046    }
047
048    /**
049     * Returns the JDBC URL used to create the underlying connection.
050     *
051     * @return JDBC URL
052     */
053    String getJdbcUrl();
054
055    /**
056     * Returns the database user that owns or invokes the Select AI resources.
057     *
058     * @return database username
059     */
060    String getDbUser();
061
062    /**
063     * Returns the underlying JDBC connection used by SDK operations.
064     * <p>
065     * The returned connection is not a defensive copy. Closing or mutating it
066     * directly affects SDK operations that use this {@code DbConnection}. Do not
067     * share one returned JDBC connection across multiple application threads
068     * unless caller-side synchronization is used.
069     * For a complete runnable sample source, see
070     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/selectai/GetConnectionSample.html">
071     * GetConnectionSample source</a>.
072     *
073     * @return JDBC connection
074     */
075    Connection getConnection();
076
077    /**
078     * Closes the JDBC connection owned by this DbConnection.
079     * <p>
080     * Calling this method is idempotent for SDK-provided implementations. After
081     * close, callers must not continue using SDK objects that depend on this
082     * connection.
083     * For a complete runnable sample source, see
084     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/selectai/CloseSelectAISample.html">
085     * CloseSelectAISample source</a>.
086     *
087     * @throws SelectAIException when the underlying JDBC connection cannot be closed
088     */
089    @Override
090    void close() throws SelectAIException;
091}