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