Scheduling agents to run at a specific time

You can schedule agents to run at a specific date and time, or postpone agents for a set time period. To schedule an agent, use the com.ibm.ia.agent.Agent application programming interface (API).

About this task

You can schedule an agent to run after a relative amount of time, for example, 1 hour from now, or at an absolute time, such as 11:59:59 December 31. The minimum delay time that you can specify is 1 second. The precision of the schedule is within 1 second.

If you want to cancel the scheduled agent, include the string as a key parameter in the cancelScheduled method, for example:

public void cancelScheduled( String key)

If the agent produces an error after the schedule method is called, the schedule is canceled automatically.

Procedure

Within any process method, call one of the schedule methods.

public String schedule( int delay, TimeUnit unit, String cookie )

Where:

delay: Indicates the number of time units that the agent is delayed. The minimum delay is 1 second.

unit: Is one of DAYS, HOURS, MINUTES, and SECONDS

cookie: Is a string that the agent passes back to the process method.

public String schedule( ZonedDateTime dateTime, String cookie )

Where:

dateTime: Indicates that the agent runs at specific date and time. If dateTime is before the current system time, the agent runs again as soon as possible.

cookie: Is a string that the agent passes back to the process method.

The agent tries to run at the exact second that you specified, but processing might be delayed if numerous agent instances are scheduled during the same second, or if the server is very busy.

After an agent delay completes, the process(String key, String cookie) method is called automatically. The key is the same String returned by the schedule method. The cookie is the argument that is included in the call to the schedule method. If you want the delayed agent to access information such as the event from the non-delayed process method call, store the information where it can be retrieved by the delayed process method. For example, you can use the bound entity or the cookie to help you retrieve the event.

Results

The scheduling method returns a string that represents the scheduled agent.

CAUTION:

When a solution with an updated Java™ agent is redeployed, the Java agent continues to receive previously scheduled time triggers. If the new version of the Java agent no longer requires a time trigger, the new Java agent code must ignore the trigger or process it. If the redeployed solution does not modify when or how time triggers are used, you do not need to change the way the Java agent handles time triggers.

Example

Suppose that a deployed Java agent emits event B one day after it receives event A, and the agent uses cookie X to schedule the agent. If you then want to change the time trigger to emit event B one week (instead of one day) after it receives event A in a new version of the same agent, you must make the following changes to the Java agent before you deploy the solution:

When event A is received, emit a time trigger with cookie Y after seven days.
When a time trigger with cookie X is received, emit a time trigger with cookie Y after six days.
When a time trigger with cookie Y is received, emit event B.