Package com.onenetwork.platform.ixm

Interface TaskWriter

All Known Implementing Classes:
AbstractTaskWriter
public interface TaskWriter
Use this instead of IXMEngineTaskGenerator for high-volume task generation. IXMEngineTaskGenerator works well when generating tasks on the order of hundreds or thousands. However, once you reach the tens or hundreds of thousands, it scales poorly because you must instantiate TaskInfo objects in memory and return them, after which they are created as GridTasks in the DB. Generally it is much more efficient in these scenarios to generate the tasks using a single INSERT statement or Stored Procedure invocation. (IXMEngineTaskGenerator is still generally easier to use though in scenarios where you don't have these scalability constraints.)

The TaskWriter interface supports these high volume scenarios by leaving the job of creating the tasks in the DB entirely to the engine itself instead of forcing it to create java objects to represent the tasks to be created.

Those who implement this interface are encouraged to do so by extending AbstractTaskWriter.

It is still recommended that you implement IXMEngineTaskGenerator in addition to TaskWriter if you want to support synchronous invocation of plan subsets through the JMX console.

When creating tasks, you should use the FULLY_QUALIFIED_ENGINE_NAME as the TASK_TYPE. For example, assuming you're populating $TASK_TYPE$ in a SqlDef to be set as GRID_TASKS.TASK_TYPE: 

 sqlParams.setStringValue("TASK_TYPE", taskFilters.getString(FULLY_QUALIFIED_ENGINE_NAME));

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static java.lang.String CREATE_JOB
    Deprecated.
    it is recommended that TaskWriters always create tasks in a job and ignore this param
    static java.lang.String EARLIEST_START_TIME
    Key for the parameter representing the earliest possible start time in millis since epoch)
    static java.lang.String ENGINE_RUN_ID
    Key for the parameter representing unique run id for engine execution
    static java.lang.String FULLY_QUALIFIED_ENGINE_NAME
    Key for the parameter representing modulePrefix_engineName_configName, for example ZBKS_MyEngine_DefaultConfig
    static java.lang.String JOB_TYPE
    Deprecated.
    it is recommended that TaskWriters specify their own job type and ignore this param
    static java.lang.String LATEST_START_TIME
    Key for the parameter representing the latest possible start time in millis since epoch)
    static java.lang.String LISTENER_CLASS
    Key for the parameter representing the id of the job to wait for before starting any tasks in this job
    static java.lang.String MAX_RUN_TIME
    Key for the parameter representing the max runtime in millis
    static java.lang.String SCHEDULED_TASK
    Iff this task write was initiated by a grid schedule, this param will be available and will contain a JSON representation of the task in question {@see GridTask#toJSON()}
    static java.lang.String TASK_MAX_ATTEMPTS
    Key for the parameter representing the max attempts allowed for any task
    static java.lang.String TASK_RETRY_DELAY_MILLS
    Key for the parameter representing the delay between retries in millis
    static java.lang.String USER_ID
    Key for the parameter representing the id of the user who is generating the tasks
    static java.lang.String WAIT_FOR_JOB_ID
    Key for the parameter representing the id of the job to wait for before starting any tasks in this job

  • Method Summary

    Modifier and Type Method Description
    default java.lang.Long writeTasks​(org.json.JSONObject taskFilters)
    Write rows directly into the GRID_TASKS table which are suitable to run this engine given a set of taskFilters.
    default java.util.Set<java.lang.Long> writeTasksWithJobChain​(org.json.JSONObject taskFilters)
    This method behaves same as writeTasks(JSONObject) except it returns an ordered set of all generated job ids.

  • Field Details

    • CREATE_JOB

      static final java.lang.String CREATE_JOB
      Deprecated.
      it is recommended that TaskWriters always create tasks in a job and ignore this param
      See Also:
      Constant Field Values

    • JOB_TYPE

      static final java.lang.String JOB_TYPE
      Deprecated.
      it is recommended that TaskWriters specify their own job type and ignore this param
      See Also:
      Constant Field Values

    • EARLIEST_START_TIME

      static final java.lang.String EARLIEST_START_TIME
      Key for the parameter representing the earliest possible start time in millis since epoch)
      See Also:
      Constant Field Values

    • LATEST_START_TIME

      static final java.lang.String LATEST_START_TIME
      Key for the parameter representing the latest possible start time in millis since epoch)
      See Also:
      Constant Field Values

    • MAX_RUN_TIME

      static final java.lang.String MAX_RUN_TIME
      Key for the parameter representing the max runtime in millis
      See Also:
      Constant Field Values

    • TASK_MAX_ATTEMPTS

      static final java.lang.String TASK_MAX_ATTEMPTS
      Key for the parameter representing the max attempts allowed for any task
      See Also:
      Constant Field Values

    • TASK_RETRY_DELAY_MILLS

      static final java.lang.String TASK_RETRY_DELAY_MILLS
      Key for the parameter representing the delay between retries in millis
      See Also:
      Constant Field Values

    • USER_ID

      static final java.lang.String USER_ID
      Key for the parameter representing the id of the user who is generating the tasks
      See Also:
      Constant Field Values

    • FULLY_QUALIFIED_ENGINE_NAME

      static final java.lang.String FULLY_QUALIFIED_ENGINE_NAME
      Key for the parameter representing modulePrefix_engineName_configName, for example ZBKS_MyEngine_DefaultConfig
      See Also:
      Constant Field Values

    • WAIT_FOR_JOB_ID

      static final java.lang.String WAIT_FOR_JOB_ID
      Key for the parameter representing the id of the job to wait for before starting any tasks in this job
      See Also:
      Constant Field Values

    • ENGINE_RUN_ID

      static final java.lang.String ENGINE_RUN_ID
      Key for the parameter representing unique run id for engine execution
      See Also:
      Constant Field Values

    • LISTENER_CLASS

      static final java.lang.String LISTENER_CLASS
      Key for the parameter representing the id of the job to wait for before starting any tasks in this job
      See Also:
      Constant Field Values

    • SCHEDULED_TASK

      static final java.lang.String SCHEDULED_TASK
      Iff this task write was initiated by a grid schedule, this param will be available and will contain a JSON representation of the task in question {@see GridTask#toJSON()}
      See Also:
      Constant Field Values

  • Method Details

    • writeTasks

      default java.lang.Long writeTasks​(org.json.JSONObject taskFilters) throws IXMException
      Write rows directly into the GRID_TASKS table which are suitable to run this engine given a set of taskFilters.

      The following taskFilters are required to be passed to this method and are to be interpreted as follows. (Note that static constants are available for each.)

      • EARLIEST_START_TIME (date as millis since epoch) : earliest start time to apply to all created tasks
      • LATEST_START_TIME (date as millis since epoch) : latest start time to apply to all created tasks
      • MAX_RUN_TIME (duration in millis) : maximum run time for any task created

      The following taskFilters are optional and may or may not be provided. When they are provided they are to be interpreted as follows:

      • TASK_MAX_ATTEMPTS : maximum number of times a task can run
      • TASK_RETRY_DELAY_MILLS (duration in millis) : maximum run time for any task created
      • USER_ID (long) : surrogate key of the user who initiated the task generation; recommended this be stored in GRID_TASKS.CREATED_BY_USER_ID if provided
      • SCHEDULED_TASK : iff this task write was initiated by a grid schedule, this param will be available and will contain a JSON representation of the task in question {@see GridTask#toJSON()}
      • WAIT_FOR_JOB_ID : id of a job to wait for before starting any task in this job
      • LISTENER_CLASS : class name for listener class that execute function at completion of job or tasks
      • ENGINE_RUN_ID : unique id associated with execution instance of engine. This id should be populated in parameters of each generated job/task with the same name i.e. ENGINE_RUN_ID

      The following taskFilters are deprecated and should be ignored:

      • CREATE_JOB (boolean): it is recommended that TaskWriters always create tasks in a job and ignore this param.
      • JOB_TYPE (string) : it is recommended that TaskWriters specify their own job type and ignore this param.

      The taskFilter can also contain any number of parameters specific to the engine which are not included in the list above.

      Also refer writeTasksWithJobChain(JSONObject)

      Parameters:
      taskFilters - parameters supplied during engine invocation which govern how the engine should be run; varies based on the type of engine
      Returns:
      must contain the id of a job for the entire engine run if "createJob" was true in taskFilters, else may return null
      Throws:
      IXMException - thrown to indicate that the tasks could not be properly generated. Throwing RequestedRescheduleException explicitly won't generate the tasks but retry the schedule if attempts count are remaining on GridTask.

    • writeTasksWithJobChain

      default java.util.Set<java.lang.Long> writeTasksWithJobChain​(org.json.JSONObject taskFilters) throws IXMException
      This method behaves same as writeTasks(JSONObject) except it returns an ordered set of all generated job ids.
      This method takes precedence if implementation for writeTasks(JSONObject) and this method is defined in implementer class.
      Parameters:
      taskFilters -
      Returns:
      Throws:
      IXMException