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 LocatableObject

The abstract class MiningTask is the common superclass for all data mining task classes. A mining task will be executed asynchronously in the DMS. 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 in the DMS using the store(dmsConn, taskName) method before execution. A mining task can be executed only once; it cannot be re-executed.

The DMS stores the state information of a task. When a MiningTask object is created and stored in the DMS it is the ready state. A mining task can be executed only when it is in ready state. Once created, a MiningTask goes through the following states:


When a mining task is terminated, it will immediately come to terminating state. After succeefully terminating, the task state will come to terminated state.

A task status history is persisted in the DMS 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 in the DMS, invoke


Since:
ODM 9.2.0
See Also:
oracle.dmt.odm.MiningTaskState, oracle.dmt.odm.task.MiningTaskStatus, Serialized Form

Method Summary
TypeMethod
 void execute(Connection dmsConn)
          Submits the mining task for asynchronous execution in the DMS.
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.
 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 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 void remove(Connection dmsConn, java.lang.String taskName)
          Removes the named task from the DMS.
 void store(Connection dmsConn, java.lang.String taskName)
          Persists persist the mining task details in the DMS with the specified name.
static void terminate(Connection dmsConn, java.lang.String taskName)
          Terminates 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 oracle.dmt.odm.LocatableObject
deserialize, serialize
 
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
Persists persist the mining task details in the DMS with the specified name. The task name must be unique in the task name space of the DMS and it must not exceed 64 characters.
Parameters:
dmsConn - Data mining server connection.
taskName - Task name.
Returns:
void
Throws:
InvalidArgumentException - is thrown
- when the dmsConn or taskName is null
- when the taskName length > 64
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

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

execute

public void 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:
void
Throws:
InvalidArgumentException - is thrown
- when the dmsConn is null
MiningTaskException - is thrown
- when there is a failure to enqueue in the DMS
SQLException - is thrown
- when there is a failure in the JDBC calls

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

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:
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 or not stored in the DMS
SQLException - is thrown
- when there is a failure in the JDBC calls

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:
MiningTaskStatus - current task status
Throws:
InvalidArgumentException - is thrown
- when the arguments are null or if the taskName length is >64
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

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 is >64
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

terminate

public static void terminate(Connection dmsConn,
                             java.lang.String taskName)
                      throws InvalidArgumentException,
                             MiningTaskException,
                             java.sql.SQLException,
                             ODMException,
                             ODMException
Terminates 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.
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 is >64
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

remove

public static void remove(Connection dmsConn,
                          java.lang.String taskName)
                   throws InvalidArgumentException,
                          MiningTaskException,
                          java.sql.SQLException,
                          ODMException
Removes the named task from the DMS. 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:
void
Throws:
InvalidArgumentException - is thrown
- when the dmsConn or taskName are null or taskName length is >64
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

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 tasks that are currently executing in the data mining server, invoke

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

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

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

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 or currentState 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

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.
Throws:
InvalidArgumentException - is thrown
- when the arguments are null or if the taskName length is >64
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