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
011/**
012 * Contract for managing database credentials used by Select AI.
013 * <p>
014 * A credential is stored in the database so PL/SQL packages can authenticate to
015 * an external service without the Java application sending secrets on every
016 * call. Select AI profiles commonly reference credentials for AI provider API
017 * access, and vector-index or summarization flows may reference credentials for
018 * object storage access.
019 * <p>
020 * A {@code Credential} object is initialized from credential configuration and
021 * is associated with the configured database credential name. Create and drop
022 * operations require a valid credential name and, for creation, a complete
023 * supported credential configuration. The SDK rejects invalid create
024 * configuration with {@link IllegalArgumentException} before JDBC execution.
025 *
026 * @see <a href="https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/select-ai-manage-profiles.html">
027 *      Select AI prerequisites and credentials</a>
028 */
029public interface Credential {
030    /**
031     * Creates the database credential represented by this instance.
032     * <p>
033     * Use this before creating profiles or vector indexes that reference the
034     * credential for provider or object-storage access.
035     * For a complete runnable sample source, see
036     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/credential/CreateCredentialSample.html">
037     * CreateCredentialSample source</a>.
038     *
039     * @return {@code true} when credential is created successfully
040     * @throws IllegalArgumentException when credential configuration is invalid,
041     *         such as missing credential material, mixed credential modes, or
042     *         incomplete OCI key material
043     * @throws SelectAIException when credential creation fails
044     */
045    boolean create() throws SelectAIException;
046
047    /**
048     * Drops the database credential represented by this instance.
049     * <p>
050     * Dropping a credential can break profiles or indexes that still reference
051     * it, so callers should remove or update dependent resources first.
052     * For a complete runnable sample source, see
053     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/credential/DropCredentialSample.html">
054     * DropCredentialSample source</a>.
055     *
056     * @return {@code true} when credential is dropped successfully
057     * @throws SelectAIException when credential drop fails
058     */
059    boolean drop() throws SelectAIException;
060
061    /**
062     * Drops the database credential represented by this instance, optionally
063     * treating an already absent credential as success.
064     * <p>
065     * For a complete runnable sample source, see
066     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/credential/DropCredentialSample.html">
067     * DropCredentialSample source</a>.
068     *
069     * @param force when {@code true}, return success if the credential does not exist
070     * @return {@code true} when credential is dropped successfully, or when
071     *         {@code force} is {@code true} and the credential is already absent
072     * @throws SelectAIException when credential drop fails
073     */
074    boolean drop(boolean force) throws SelectAIException;
075}