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.agent;
008
009import com.oracle.database.selectai.model.agent.TaskAttributes;
010import com.oracle.database.selectai.model.agent.TaskStatus;
011import com.oracle.database.selectai.model.SelectAIException;
012
013/**
014 * Contract for Select AI agent task lifecycle management and metadata access.
015 * <p>
016 * A task is a database-side resource managed by the
017 * {@code DBMS_CLOUD_AI_AGENT} PL/SQL package. Tasks define work that can be
018 * assigned to or coordinated by an agent team.
019 * <p>
020 * A {@code Task} instance can represent an existing database task or be
021 * configured for creation. The name-only {@link SelectAIAgent#task(String)}
022 * factory verifies that the task exists and loads its metadata and attributes
023 * before returning. {@link SelectAIAgent#listTasks()} also returns handles with
024 * loaded metadata and attributes. A handle configured for creation is obtained with
025 * {@link SelectAIAgent#task(String, TaskAttributes, String, TaskStatus)}.
026 * <p>
027 * A creation-configured handle retains its supplied attributes, description,
028 * and status without querying the database. Only such a handle can call
029 * {@link #create()}; after creation succeeds, it becomes database-backed.
030 * {@link #enable()}, {@link #disable()}, and {@link #drop(boolean)} require an
031 * existing task and operate on the database-side resource.
032 * Existing tasks can update individual attributes with {@link #setAttribute(String, String)}
033 * or multiple attributes with {@link #setAttributes(TaskAttributes)}; both
034 * operations reload the typed attributes after the database update succeeds.
035 * <p>
036 * Before creation, {@link #getStatus()} and {@link #getTaskAttributes()} return
037 * the configured values. For a database-backed handle, each call to either
038 * method queries the database. {@code getStatus()} does not change the
039 * description returned by {@link #getDescription()}. The description is
040 * supplied or loaded when the handle is initialized; {@code getDescription()}
041 * does not query the database.
042 * <p>
043 * Names and required Java arguments are checked locally. Loading metadata and
044 * executing lifecycle operations require database access; the database checks
045 * privileges and validates task attributes when they are submitted.
046 * <p>
047 * For a complete runnable example, see
048 * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/CreateTaskSample.html">
049 * CreateTaskSample source</a>.
050 *
051 * @see SelectAIAgent
052 * @see <a href="https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-agent-package.html">
053 *      DBMS_CLOUD_AI_AGENT package documentation</a>
054 * @since 1.1.0
055 */
056public interface Task {
057    /**
058     * Creates this creation-configured task in the database.
059     * For a runnable example, see
060     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/CreateTaskSample.html">
061     * CreateTaskSample source</a>.
062     *
063     * @return {@code true} when the database creates the task
064     * @throws IllegalStateException when this handle was loaded from an existing task
065     * @throws SelectAIException when the database rejects or cannot complete the operation
066     */
067    boolean create() throws SelectAIException;
068    /**
069     * Enables this database-backed task.
070     * For a runnable example, see
071     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/EnableTaskSample.html">
072     * EnableTaskSample source</a>.
073     *
074     * @return {@code true} when the database enables the task
075     * @throws IllegalStateException when this task has not been created
076     * @throws SelectAIException when the database operation fails
077     */
078    boolean enable() throws SelectAIException;
079    /**
080     * Disables this database-backed task.
081     * For a runnable example, see
082     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/DisableTaskSample.html">
083     * DisableTaskSample source</a>.
084     *
085     * @return {@code true} when the database disables the task
086     * @throws IllegalStateException when this task has not been created
087     * @throws SelectAIException when the database operation fails
088     */
089    boolean disable() throws SelectAIException;
090    /**
091     * Drops this database-backed task. When {@code force} is {@code true},
092     * the operation may be retried after the handle has already been dropped;
093     * the database force-drop semantics determine the result.
094     * For a runnable example, see
095     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/DropTaskSample.html">
096     * DropTaskSample source</a>.
097     *
098     * @param force database force-drop option
099     * @return {@code true} when the drop completes
100     * @throws IllegalStateException when {@code force} is {@code false} and
101     *         this task has not been created
102     * @throws SelectAIException when the database operation fails
103     */
104    boolean drop(boolean force) throws SelectAIException;
105
106    /**
107     * Updates one task attribute in the database.
108     * For a runnable example, see
109     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetTaskAttributeSample.html">
110     * SetTaskAttributeSample source</a>.
111     *
112     * @param attributeName database task attribute name
113     * @param attributeValue string value, or {@code null} where supported
114     * @return {@code true} when the update succeeds
115     * @throws IllegalArgumentException when {@code attributeName} is null or blank
116     * @throws IllegalStateException when this task has not been created
117     * @throws SelectAIException when the database update fails
118     */
119    boolean setAttribute(String attributeName, String attributeValue) throws SelectAIException;
120
121    /**
122     * Updates one boolean task attribute in the database.
123     * For a runnable example, see
124     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetTaskAttributeSample.html">
125     * SetTaskAttributeSample source</a>.
126     *
127     * @param attributeName database task attribute name
128     * @param attributeValue boolean value
129     * @return {@code true} when the update succeeds
130     * @throws IllegalArgumentException when {@code attributeName} is null or blank
131     * @throws IllegalStateException when this task has not been created
132     * @throws SelectAIException when the database update fails
133     */
134    boolean setAttribute(String attributeName, boolean attributeValue) throws SelectAIException;
135
136    /**
137     * Updates one integer task attribute in the database.
138     * For a runnable example, see
139     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetTaskAttributeSample.html">
140     * SetTaskAttributeSample source</a>.
141     *
142     * @param attributeName database task attribute name
143     * @param attributeValue integer value
144     * @return {@code true} when the update succeeds
145     * @throws IllegalArgumentException when {@code attributeName} is null or blank,
146     *         or {@code attributeValue} is null
147     * @throws IllegalStateException when this task has not been created
148     * @throws SelectAIException when the database update fails
149     */
150    boolean setAttribute(String attributeName, Integer attributeValue) throws SelectAIException;
151
152    /**
153     * Updates one floating-point task attribute in the database.
154     * For a runnable example, see
155     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetTaskAttributeSample.html">
156     * SetTaskAttributeSample source</a>.
157     *
158     * @param attributeName database task attribute name
159     * @param attributeValue floating-point value
160     * @return {@code true} when the update succeeds
161     * @throws IllegalArgumentException when {@code attributeName} is null or blank,
162     *         or {@code attributeValue} is null
163     * @throws IllegalStateException when this task has not been created
164     * @throws SelectAIException when the database update fails
165     */
166    boolean setAttribute(String attributeName, Float attributeValue) throws SelectAIException;
167
168    /**
169     * Updates multiple task attributes in one database operation.
170     * For a runnable example, see
171     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetTaskAttributesSample.html">
172     * SetTaskAttributesSample source</a>.
173     *
174     * @param taskAttributes task attributes to update
175     * @return {@code true} when the update succeeds
176     * @throws IllegalArgumentException when {@code taskAttributes} is null
177     * @throws IllegalStateException when this task has not been created
178     * @throws SelectAIException when the database update fails
179     */
180    boolean setAttributes(TaskAttributes taskAttributes) throws SelectAIException;
181
182    /**
183     * Returns the configured or database-reported task name without database access.
184     * For a runnable example, see
185     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadTaskSample.html">
186     * LoadTaskSample source</a>.
187     *
188     * @return configured or database-reported task name
189     */
190    String getTaskName();
191    /**
192     * Returns the description supplied or loaded when this handle was initialized.
193     * This method does not access the database and the value is not changed by
194     * {@link #getStatus()}.
195     * For a runnable example, see
196     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadTaskSample.html">
197     * LoadTaskSample source</a>.
198     *
199     * @return supplied or loaded task description, or {@code null} when absent
200     */
201    String getDescription();
202    /**
203     * Returns the configured status before creation or the current database
204     * status for an existing task. A pending task with no configured status
205     * returns {@code null}. This method does not change the description.
206     * For a runnable example, see
207     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadTaskSample.html">
208     * LoadTaskSample source</a>.
209     *
210     * @return configured or current task status
211     * @throws SelectAIException when current task metadata cannot be fetched
212     */
213    TaskStatus getStatus() throws SelectAIException;
214    /**
215     * Returns task attributes for this handle.
216     * <p>
217     * For a database-backed task, this method reloads the attributes from the
218     * database on each call and therefore can fail if the resource was deleted.
219     * For a creation-configured task, it returns the configured attributes
220     * without querying the database.
221     * For a runnable example, see
222     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadTaskSample.html">
223     * LoadTaskSample source</a>.
224     *
225     * @return current task attributes for an existing task, or configured
226     *         attributes for a task pending creation
227     * @throws SelectAIException when the task no longer exists or current attributes cannot be fetched
228     */
229    TaskAttributes getTaskAttributes() throws SelectAIException;
230}