Scheduling custom server tasks
i2 Analyze supports the development of custom 'tasks' that the server executes on a user-defined schedule. A task is simply a Java class that implements a specific interface and performs a custom action when invoked.
Creating a custom task
The task class must implement the
IScheduledTask interface, which is provided by the
disco-api.jar file in the deployment toolkit.
IScheduledTask interface defines the following methods:
run()method contains the code that performs the custom action. This method is called periodically, based on the schedule specified in the deployment properties file.
onStartup()method contains any necessary start-up or initialization code. It also receives an
IScheduledTaskObjectsparameter that provides access to other i2 Analyze APIs that can be used inside the running task. For example, the scheduler tracer can be used for logging, and the alert manager can be used to send alerts.
This method is called whenever the server initializes an instance of a task, such as when it starts.
close()method contains any necessary tear-down or finalization code. This method is called whenever the server removes an instance of a task, such as when it stops.
Note: Writing implementations of the
close()methods is optional. They have default implementations that do nothing.
If the custom task fails for any reason, you can control the subsequent behavior by throwing a
CustomTaskFailedException from the
run() method. Depending on how the exception is constructed, the server might re-run the task immediately, or when it is next scheduled, or never.
Note: If an exception other than a
CustomTaskFailedExceptionescapes from the
run()method, the custom task is cancelled and will not run again until the scheduler is reinitialized - when the server is restarted, for example.
Deploying a custom task
To deploy a custom task, the Java class (and any supporting classes) must be packaged in a
.jar file. You must then copy this
.jar file to the configuration part of the toolkit. Place it the
WEB-INF/lib sub-folder of the
opal-services fragment, in the
Note: A new fragment specifically for custom tasks is also an option, provided that it is also added to the
topology.xmlfile for the deployment.
In order for the i2 Analyze server to discover the custom task, entries that identify it must be present in one of the settings files. A typical location for these entries is the
The new entries have two parts, in the following format:
<TaskName> is a name that identifies a particular task instance;
<ImplementationClass> is the fully qualified class name for the implementation of that task; and
<CronExpression> is a cron schedule expression for when the task should run.
The format of the cron expression is:
<minute> <hour> <day-of-month> <month> <day-of-week>
For example, a cron expression of
0 0 * * * results in a task running at midnight every day. See the UNIX cron format documentation for more information.
The following settings define two different tasks that use two different classes, on two different schedules:
CustomTaskScheduler.AlertUsersBeforeDeletingCharts.Class=com.example.alert.ScheduledTask CustomTaskScheduler.AlertUsersBeforeDeletingCharts.Expression=0 0 * * * CustomTaskScheduler.TableCleaner.Class=com.example.cleaner.CleanupTask CustomTaskScheduler.TableCleaner.Expression=0 */4 * * *
.jar file is copied into the toolkit, and the
DiscoServerSettingsCommon.properties file is updated with the custom task class name and the cron schedule, the task is ready for deployment to the i2 Analyze server.
To deploy the custom task to the i2 Analyze server, run
setup -t deployLiberty to update the configuration with your changes. Then, to set up the task to run according to its defined schedule, run
setup -t startLiberty.
Monitoring a custom task
The scheduler log stores information about the state of all configured tasks, including when a task was last run, when it will next run, whether it has failed, and so on.
The scheduler log can be found in the
i2_Scheduler.log file, inside the i2 Analyze server.
Note: If a custom task is configured to use the scheduler tracer (
IScheduledTaskObjects.getSchedulerTracer()) in its
onStartup()method, then anything logged through that object is also written to the