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.model;
008
009/**
010 * SDK execution settings for {@link com.oracle.database.selectai.SelectAI},
011 * {@link com.oracle.database.selectai.DatabaseAdmin}, and
012 * {@link com.oracle.database.selectai.agent.SelectAIAgent} clients.
013 * <p>
014 * These options control SDK-managed JDBC execution behavior. They do not
015 * configure database identity, JDBC URL, passwords, wallet settings, or
016 * connection-pool settings.
017 */
018public final class SelectAIOptions {
019    /** Default options with no SDK-level query timeout. */
020    private static final SelectAIOptions DEFAULTS = new Builder().build();
021
022    /** Query timeout, in seconds, applied to JDBC statements created by SDK operations. */
023    private final Integer queryTimeoutSeconds;
024
025    private SelectAIOptions(Builder builder) {
026        this.queryTimeoutSeconds = builder.queryTimeoutSeconds;
027    }
028
029    /**
030     * Returns default SelectAI options.
031     *
032     * @return default options with no SDK-level query timeout
033     */
034    public static SelectAIOptions defaults() {
035        return DEFAULTS;
036    }
037
038    /**
039     * Creates a builder for SelectAI execution options.
040     *
041     * @return new builder
042     */
043    public static Builder builder() {
044        return new Builder();
045    }
046
047    /**
048     * Returns the configured JDBC statement query timeout.
049     *
050     * @return timeout in seconds, {@code 0} for JDBC no-timeout behavior, or
051     *         {@code null} when the SDK does not call
052     *         {@link java.sql.Statement#setQueryTimeout(int)}
053     */
054    public Integer getQueryTimeoutSeconds() {
055        return queryTimeoutSeconds;
056    }
057
058    /**
059     * Builder for {@link SelectAIOptions}.
060     */
061    public static final class Builder {
062        /** Query timeout being assembled, in seconds. */
063        private Integer queryTimeoutSeconds;
064
065        private Builder() {
066        }
067
068        /**
069         * Sets the JDBC statement query timeout applied to SDK operations.
070         * <p>
071         * A {@code null} value means the SDK does not call
072         * {@link java.sql.Statement#setQueryTimeout(int)}. A value of {@code 0}
073         * uses JDBC's no-timeout behavior. Negative values are rejected.
074         *
075         * @param queryTimeoutSeconds timeout in seconds, or {@code null} for no SDK timeout
076         * @return this builder instance
077         */
078        public Builder queryTimeoutSeconds(Integer queryTimeoutSeconds) {
079            if (queryTimeoutSeconds != null && queryTimeoutSeconds < 0) {
080                throw new IllegalArgumentException("queryTimeoutSeconds must be greater than or equal to 0");
081            }
082            this.queryTimeoutSeconds = queryTimeoutSeconds;
083            return this;
084        }
085
086        /**
087         * Builds immutable SelectAI options.
088         *
089         * @return SelectAI options
090         */
091        public SelectAIOptions build() {
092            return new SelectAIOptions(this);
093        }
094    }
095}