Chapter 11. Creating Custom Tasks

Documentation

VoltDB Home » Documentation » Guide to Performance and Customization
< previoustable of contentsnext >

Chapter 11. Creating Custom Tasks

You can schedule common repetitive tasks using the CREATE TASK SQL statement. CREATE TASK lets you schedule any system or user-defined stored procedure to be run on a specified schedule. However, there are times when you need the schedule, or the procedure itself, to be more responsive: adjusting to the current state of the database or the results of the previous task runs. This is what custom tasks help you accomplish.

Custom tasks let you modify the characteristics of the task, including:

  • What procedure is executed by the task

  • The arguments to the task procedure

  • The time interval between executions of the task

The following sections describe how to design, develop and implement custom tasks.

11.1. Overview of How Custom Tasks Work

You write custom tasks as Java classes implementing one of three interfaces, depending on what you want to customize:

  • ActionGenerator — Customizes the stored procedure to call and the parameters to use

  • IntervalGenerator — Customizes the interval between procedure calls

  • ActionScheduler — Customizes all three aspects of the task: the stored procedure to call, its parameters, and the interval between calls

Once you write the class for a custom task, you implement it in VoltDB in two steps:

  1. You load the class into the database the same way you would a stored procedure, by compiling and packaging it as a JAR file and then loading the JAR file into the database with the LOAD CLASSES directive.

  2. You then declare the custom task using the CREATE TASK statement, replacing the argument to the appropriate clause with FROM CLASS. For example, a custom procedure call replaces PROCEDURE {procedure-name} with PROCEDURE FROM CLASS {class-name}, a custom interval replaces ON SCHEDULE {type-and-value} with ON SCHEDULE FROM CLASS {class-name}, and a custom scheduler replaces both the PROCEDURE and ON SCHEDULE clauses with FROM CLASS {class-name}. You can optionally specify arguments to the custom class using the WITH clause.

For example, the following SQL statements declare one custom task of each type, assuming their classes are packaged in the JAR mytasks.jar:

LOAD CLASSES mytasks.jar;
CREATE TASK variableproc 
   ON SCHEDULE EVERY 5 SECONDS
   PROCEDURE FROM CLASS MyVariableProc WITH (1,2,3);
CREATE TASK variableinterval 
   ON SCHEDULE FROM CLASS MyVariableInterval WITH (1,2,3)
   PROCEDURE cleanupchoir;
CREATE TASK variabletask 
   FROM CLASS MyVariableTask WITH (1,2,3);

In all three cases, the sequence of events at run time is the same. Once you declare and enable a custom task, the database:

  1. Invokes the custom task's initialize() method once, passing the parameters specified in the WITH clause of the CREATE TASK statement.

  2. Invokes the custom task's getFirst<item>() method once. The actual method name varies depending on the interface; getFirstAction() for actions, getFirstInterval for intervals, and getFirstScheduledAction() for both action and interval. The method must return an object with the custom values and a callback method. VoltDB uses this information to schedule the first invocation of the task.

  3. Iteratively, invokes the specified callback method, passing the results of the stored procedure as an argument. The callback then repeats the process of returning an object with the next custom values and callback.

This sequence of events is repeated any time the database is restarted, the schema is changed, or the database is paused and then resumed.

The following sections provide examples of using each type of customization. See the javadoc for additional details about the classes and methods that can assist your task design.

< previoustable of contentsnext >