oracle.dmt.odm.task
Class MiningTask

java.lang.Object
  |
  +--oracle.dmt.odm.MiningObject
        |
        +--oracle.dmt.odm.LocatableObject
              |
              +--oracle.dmt.odm.task.MiningTask

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

MiningDataTask, ModelExportTask, ModelImportTask

public abstract class MiningTask

extends oracle.dmt.odm.LocatableObject

The abstract class MiningTask is the common superclass for all data mining task classes. A mining task will be executed asynchronously in the database. A mining task must have all the input parameters required for performing the task. This class has utility methods to retrieve the task status information.

A mining task must be persisted using the store(dmsConn, taskName) method before execution. A mining task can be executed more than once in 10.x.x version of the oracle database, oracle.dmt.odm.task.ExecutionHandle object returned when a mining task is executed.

When a MiningTask object is created and stored it will be set to ready state. A mining task can be executed only when it is in ready state. Once persisted, a MiningTask goes through the following states:

• queued - task is queued for execution
• initiated - task is initiated to execute
• executing - task is actually getting executed in the DMS
• success - if the task got successfully completed,
• error - if the task failed to complete.

When a mining task is terminated, it will immediately come to terminating state. After succeefully terminating, the task state will come to terminated state. If the task comes to error/success state while terminating the task, then task state will come to error/success state.

A task status history is persisted along with the task details. A user can get the current status information of a task by calling the getCurrentStatus(dmsConn, taskName) method. This returns a MiningTaskStatus object, which provides more details about the state. A user can get the complete status history of a task by calling the getStatusHistory(dmsConn, taskName) method.

To list all the tasks that are currently at a particular state, invoke the listTasks method. For example, to list all the tasks currently getting executed by the user, invoke

• listTasks(dmsConn, MiningTaskState.executing, null, null)

Since:

ODM 9.2.0

See Also:

oracle.dmt.odm.MiningTaskState, oracle.dmt.odm.task.MiningTaskStatus, Serialized Form

Method Summary

ExecutionHandle	execute(Connection dmsConn) Submits the mining task for asynchronous execution in the DMS.
static ExecutionHandle	getActiveExecutionHandle(Connection dmsConn, java.lang.String taskName) An execution handle is active only when it is in queued/initiated/executing/terminating states.
static MiningTaskStatus	getCurrentStatus(Connection dmsConn, java.lang.String taskName) Returns the current status of the task.
static long	getExecutionDuration(Connection dmsConn, java.lang.String taskName) Returns the duration of the execution of a succesfully completed task.
static ExecutionHandle	getExecutionHandle(Connection dmsConn, java.lang.String taskName, java.lang.String execID) Execution handle associated with the specified task and the id.
static ExecutionHandle	getLatestExecutionHandle(Connection dmsConn, java.lang.String taskName) Latest execution handle associated with the task.
java.lang.String	getName() Returns the task name of a stored mining task, because name is assigned to a task only after storing the task in DMS.
static MiningTaskStatus[]	getStatusHistory(Connection dmsConn, java.lang.String taskName) Returns an array of task statuses sorted by timestamp in decending order of the status entry timestamp.
static java.lang.String	getTaskType(Connection dmsConn, java.lang.String taskName) Returns the task type of a mining task.
MiningTaskType	getType() Returns the task Type Enumeration
static MiningTask[]	listTasks(Connection dmsConn, MiningTaskState currentState, java.util.Date afterStateEntryTime, java.util.Date beforeStateEntryTime) Returns the tasks that are currently in the specified state.
static boolean	remove(Connection dmsConn, java.lang.String taskName) Removes the named task from the database.
static boolean	rename(Connection dmsConn, java.lang.String oldTaskName, java.lang.String newTaskName) Renames the specified mining task.
void	store(Connection dmsConn, java.lang.String taskName) Persist the mining task details in the DMS with the specified name.
static void	terminate(Connection dmsConn, java.lang.String taskName) Terminates (kills) a queued/initiated/executing task in the DMS.
MiningTaskStatus	waitForCompletion(Connection dmsConn) Waits for task completion after executing the task.
MiningTaskStatus	waitForCompletion(Connection dmsConn, long timeOutInSeconds) Waits for the task completion after executing the task.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

store

public void store(Connection dmsConn,
                  java.lang.String taskName)
           throws InvalidArgumentException,
MiningTaskException,
                  java.sql.SQLException,
ODMException

Persist the mining task details in the DMS with the specified name. The task name must be unique in the users mining object name space of the DMS and it must not exceed 25 charcaters.

Parameters:

dmsConn - Data mining server connection.

taskName - Task name.

Throws:

InvalidArgumentException - is thrown
- when the dmsConn or taskName is null
- when the taskName length > 25

MiningTaskException - is thrown
- when the taskName is already in use
- when the store fails due to an internal failure

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

ODMException

getName

public java.lang.String getName()

Returns the task name of a stored mining task, because name is assigned to a task only after storing the task in DMS. If the mining task is not stored, it returns null.

Returns:

String - task name

getType

public MiningTaskType getType()

Returns the task Type Enumeration

Returns:

MiningTaskType - Task Type

Since:

10.1.0

getTaskType

public static java.lang.String getTaskType(Connection dmsConn,
                                           java.lang.String taskName)
                                    throws InvalidArgumentException,
MiningTaskException,
                                           java.sql.SQLException

Returns the task type of a mining task.

Returns:

String - task type

InvalidArgumentException

MiningTaskException

java.sql.SQLException

execute

public ExecutionHandle execute(Connection dmsConn)
                                            throws InvalidArgumentException,
MiningTaskException,
                                                   java.sql.SQLException

Submits the mining task for asynchronous execution in the DMS. MiningTask must be stored before executing it. This method returns after enqueuing the task to the specified DMS. To wait for task completion, use waitForCompletion(dmsConn) method.

Parameters:

dmsConn - Data mining server connection

Returns:

execution handle associated with the current execution of the task

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null

MiningTaskException - is thrown
- when the task is not stored in the data mining server - when there is an active execution already running associated with the task

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

waitForCompletion

public MiningTaskStatus waitForCompletion(Connection dmsConn)
                                                       throws InvalidArgumentException,
MiningTaskException,
                                                              java.sql.SQLException

Waits for task completion after executing the task.

Parameters:

dmsConn - Data mining server connection

Returns:

MiningTaskStatus - status of the task, after completion

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null

MiningTaskException - is thrown
- when the task is not executed i.e., task is in ready state

SQLException - is thrown
- when here is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

waitForCompletion

public MiningTaskStatus waitForCompletion(Connection dmsConn,
                                          long timeOutInSeconds)
                                                       throws InvalidArgumentException,
MiningTaskException,
                                                              java.sql.SQLException

Waits for the task completion after executing the task. It also allows the user to specify a timeout in seconds. If the task is not completed by the timeout period, this method returns the mining task status at the timeout.

Parameters:

dmsConn - Data mining server connection

timeOutInSeconds - number of seconds until the method will return unless it returns sooner because the task completes

Returns:

status of the task when the method returns

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null

MiningTaskException - is thrown
- when the task is not executed i.e., task is in ready state or not stored in the DMS

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

getCurrentStatus

public static MiningTaskStatus getCurrentStatus(Connection dmsConn,
                                                java.lang.String taskName)
                                                             throws InvalidArgumentException,
MiningTaskException,
                                                                    java.sql.SQLException

Returns the current status of the task.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Returns:

current task status

Throws:

InvalidArgumentException - is thrown
- when the arguments are null or if the taskName length exceeds the limit

MiningTaskException - is thrown
- when the named task does not exist in the data mining server.

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

getStatusHistory

public static MiningTaskStatus[] getStatusHistory(Connection dmsConn,
                                                  java.lang.String taskName)
                                                               throws InvalidArgumentException,
MiningTaskException,
                                                                      java.sql.SQLException,
ODMException

Returns an array of task statuses sorted by timestamp in decending order of the status entry timestamp.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Returns:

MiningTaskStatus[] - history of statuses

Throws:

InvalidArgumentException - is thrown
If the dmsConn or taskName are null or if the taskName length exceeds the limit

MiningTaskException - is thrown
If the named task does not exist in the data mining server.

SQLException - is thrown
If there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

ODMException

terminate

public static void terminate(Connection dmsConn,
                             java.lang.String taskName)
                      throws InvalidArgumentException,
MiningTaskException,
                             java.sql.SQLException,
ODMException

Terminates (kills) a queued/initiated/executing task in the DMS. If the task is in the queued state, this operation dequeues the task. If the task is in initiated/executing state, it terminates and rollsback the task-related transactions. If the task is a ModelSeekerTask, then after a successful termination of the task, invokes ModelSeekerResult.remove to remove all named result objects built by the task from the database. If exceptions occur during this remove operation, they are ignored. It is possible due to such ignored exceptions that named objects will remain in the database.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Returns:

void

Throws:

InvalidArgumentException - is thrown
- when the dmsConn or taskName are null
- when the taskName length exceeds the limit

MiningTaskException - is thrown
- when the named task does not exist in the data mining server
- when the terminate operation failed.

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

ODMException

rename

public static boolean rename(Connection dmsConn,
                             java.lang.String oldTaskName,
                             java.lang.String newTaskName)
                      throws java.sql.SQLException,
MiningObjectException,
InvalidArgumentException,
ODMException

Renames the specified mining task.

Parameters:

dmsConn - A connection to the data mining server

oldTaskName - The name of the mining task to be renamed

newTaskName - The new name of the mining task to be assigned

Returns:

boolean - A flag indicating whether the specified object has been renamed successfully.

Throws:

InvalidArgumentException - is thrown
- when dmsConn is null, or
- when oldTaskName is null,
- when newTaskName is null.

ODMException - is thrown
- when oldTaskName is empty or exceeds 64 characters in length.
- when newTaskName is empty or length exceeds 25 characters.

SQLException - is thrown
- when there is a failure in the JDBC calls

java.sql.SQLException

MiningObjectException

Since:

10.1

remove

public static boolean remove(Connection dmsConn,
                             java.lang.String taskName)
                      throws InvalidArgumentException,
MiningTaskException,
                             java.sql.SQLException,
ODMException

Removes the named task from the database. A task can be removed only if it is not in the queued/initiated/executing/terminating statuses. Termination needs to be done before removing a currently executing task.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Returns:

true if removed successfully, otherwise false

Throws:

InvalidArgumentException - is thrown
- when the dmsConn or taskName are null or taskName length exceeds 64 characters in length.

MiningTaskException - is thrown
- when the task does not exist in the data mining server
- when the task remove failed, because task is not in the queued/initiated/executing/terminating statuses

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

ODMException

listTasks

public static MiningTask[] listTasks(Connection dmsConn,
MiningTaskState currentState,
                                     java.util.Date afterStateEntryTime,
                                     java.util.Date beforeStateEntryTime)
                                                  throws InvalidArgumentException,
MiningTaskException,
                                                         java.sql.SQLException,
ODMException

Returns the tasks that are currently in the specified state. For example, to list all the user tasks that are currently executing in the data mining server, invoke

• listTasks(dmsConn, MiningTaskState.executing, null, null);

To list the tasks currently at a specified state and their state entry time is after 'afterStateEntryTime', invoke

• listTasks(dmsConn, MiningTaskState.executing, afterStateEntryTime, null);

Similarly, to list the tasks currently at a specified state and their state entry time is before 'beforeStateEntryTime', invoke

• listTasks(dmsConn, MiningTaskState.executing, null, beforeStateEntryTime);

To list the tasks currently at a specified state whose state entry time is between 'afterStateEntryTime' and 'beforeStateEntryTime', invoke

• listTasks(dmsConn, MiningTaskState.executing, afterStateEntryTime, beforeStateEntryTime);

To list all the tasks in the user schema, invoke

• listTasks(dmsConn, null, null, null);

Parameters:

dmsConn - Data mining server connection

currentState - Current state of the task

afterStateEntryTime - After the task state entry time

beforeStateEntryTime - Before the task state entry time

Returns:

void

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null

MiningTaskException - is thrown
- when there is a failure in listing the tasks

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

ODMException

getExecutionDuration

public static long getExecutionDuration(Connection dmsConn,
                                        java.lang.String taskName)
                                 throws InvalidArgumentException,
MiningTaskException,
                                        java.sql.SQLException,
ODMException

Returns the duration of the execution of a succesfully completed task. If the task is still executing, it returns the duration of this execution. If the task is in ready/queued/initiated/terminating/terminated state, throws MiningTaskException.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Throws:

InvalidArgumentException - is thrown
- when the arguments are null or if the taskName length exceeds the limit

MiningTaskException - is thrown
- when the named task does not exist in the data mining server - when task is in ready/queued/initiated/terminating/terminated state

java.sql.SQLException - is thrown
- when there is a failure in the JDBC calls

ODMException

getActiveExecutionHandle

public static ExecutionHandle getActiveExecutionHandle(Connection dmsConn,
                                                       java.lang.String taskName)
                                                                    throws InvalidArgumentException,
MiningTaskException,
                                                                           java.sql.SQLException

An execution handle is active only when it is in queued/initiated/executing/terminating states. This method returns an active execution handle with the associated task. If there is no active execution handle, it returns null.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Returns:

ExecutionHandle active execution handle associated with the task

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null - when the taskName is null or length exceeds the limit

MiningTaskException - is thrown
- when there is no task object with the specified name in the DMS

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

getLatestExecutionHandle

public static ExecutionHandle getLatestExecutionHandle(Connection dmsConn,
                                                       java.lang.String taskName)
                                                                    throws InvalidArgumentException,
MiningTaskException,
                                                                           java.sql.SQLException

Latest execution handle associated with the task. If there are no executions for this task, it returns null.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

Returns:

ExecutionHandle latest execution handle associated with the task

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null - when the taskName is null or length exceeds the limit

MiningTaskException - is thrown
- when there is no task object with the specified name in the DMS

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException

getExecutionHandle

public static ExecutionHandle getExecutionHandle(Connection dmsConn,
                                                 java.lang.String taskName,
                                                 java.lang.String execID)
                                                              throws InvalidArgumentException,
MiningTaskException,
                                                                     java.sql.SQLException

Execution handle associated with the specified task and the id. If there are no executions for this task, it returns null.

Parameters:

dmsConn - Data mining server connection

taskName - Name of the task

execID - execution id of the task

Returns:

ExecutionHandle latest execution handle associated with the task

Throws:

InvalidArgumentException - is thrown
- when the dmsConn is null - when the taskName is null or length exceeds the limit

MiningTaskException - is thrown
- when there is no task object with the specified name in the DMS

SQLException - is thrown
- when there is a failure in the JDBC calls

InvalidArgumentException

MiningTaskException

java.sql.SQLException