Package com.scivicslab.pojoactor.workflow.scheduler

Class WorkflowScheduler

java.lang.Object
com.scivicslab.pojoactor.workflow.scheduler.WorkflowScheduler
All Implemented Interfaces:
CallableByActionName, AutoCloseable
public class WorkflowScheduler extends Object implements CallableByActionName, AutoCloseable
A scheduler for periodic task execution with IIActorRef (workflow actors).

This class provides scheduling capabilities for workflow actors using action names and string arguments. Tasks are executed on actors via IIActorRef.callByActionName(String, String).

Usage Example:


 IIActorSystem system = new IIActorSystem("my-system");
 WorkflowScheduler scheduler = new WorkflowScheduler(system);

 // Schedule a task to run every 10 seconds
 scheduler.scheduleAtFixedRate("health-check", "serverActor", "checkHealth", "", 0, 10, TimeUnit.SECONDS);

 // Cancel a task
 scheduler.cancelTask("health-check");

 // Cleanup
 scheduler.close();

For lambda-based scheduling with ActorRef, use Scheduler instead.

Since:
2.11.0
Author:
devteam@scivics-lab.com
See Also:

  • Constructor Details

    • WorkflowScheduler

      public WorkflowScheduler(IIActorSystem actorSystem)
      Constructs a new WorkflowScheduler with the specified actor system.
      Parameters:
      actorSystem - the actor system containing target actors

    • WorkflowScheduler

      public WorkflowScheduler(IIActorSystem actorSystem, int poolSize)
      Constructs a new WorkflowScheduler with the specified actor system and pool size.
      Parameters:
      actorSystem - the actor system containing target actors
      poolSize - the number of threads in the scheduler's thread pool

  • Method Details

    • scheduleAtFixedRate

      public String scheduleAtFixedRate(String taskId, String targetActorName, String actionName, String actionArgs, long initialDelay, long period, TimeUnit unit)
      Schedules a task to execute periodically at a fixed rate.

      Fixed Rate vs Fixed Delay:

      With scheduleAtFixedRate, executions are scheduled to start at regular intervals (0, period, 2*period, 3*period, ...) regardless of how long each execution takes. If an execution takes longer than the period, the next execution starts immediately after the previous one completes (no delay accumulation).

      Use this method when you need consistent timing intervals, such as metrics collection or heartbeat checks at precise intervals.

      In contrast, scheduleWithFixedDelay(java.lang.String, java.lang.String, java.lang.String, java.lang.String, long, long, java.util.concurrent.TimeUnit) waits for a fixed delay after each execution completes before starting the next one.

       scheduleAtFixedRate (period=100ms, task takes 30ms):
 |task|          |task|          |task|
 0    30   100   130   200   230   300ms
      └─period─┘      └─period─┘
      Parameters:
      taskId - unique identifier for this scheduled task
      targetActorName - name of the target actor in the system
      actionName - action to invoke on the actor
      actionArgs - arguments to pass to the action
      initialDelay - delay before first execution
      period - interval between successive execution starts
      unit - time unit for the delays
      Returns:
      the taskId for reference
      See Also:

    • scheduleWithFixedDelay

      public String scheduleWithFixedDelay(String taskId, String targetActorName, String actionName, String actionArgs, long initialDelay, long delay, TimeUnit unit)
      Schedules a task to execute periodically with a fixed delay between executions.

      Fixed Delay vs Fixed Rate:

      With scheduleWithFixedDelay, the delay between the termination of one execution and the start of the next is always delay time units. This ensures that executions never overlap and there is always a guaranteed rest period between executions.

      Use this method when you need to ensure a minimum gap between executions, such as polling operations where you want to avoid overwhelming a resource, or when each execution depends on external state that needs time to stabilize.

      In contrast, scheduleAtFixedRate(java.lang.String, java.lang.String, java.lang.String, java.lang.String, long, long, java.util.concurrent.TimeUnit) schedules executions at fixed intervals regardless of execution duration.

       scheduleWithFixedDelay (delay=100ms, task takes 30ms):
 |task|              |task|              |task|
 0    30        130  160        260  290ms
      └──delay──┘    └──delay──┘
      Parameters:
      taskId - unique identifier for this scheduled task
      targetActorName - name of the target actor in the system
      actionName - action to invoke on the actor
      actionArgs - arguments to pass to the action
      initialDelay - delay before first execution
      delay - delay between termination of one execution and start of next
      unit - time unit for the delays
      Returns:
      the taskId for reference
      See Also:

    • scheduleOnce

      public String scheduleOnce(String taskId, String targetActorName, String actionName, String actionArgs, long delay, TimeUnit unit)
      Schedules a task to execute once after a specified delay.
      Parameters:
      taskId - unique identifier for this scheduled task
      targetActorName - name of the target actor in the system
      actionName - action to invoke on the actor
      actionArgs - arguments to pass to the action
      delay - delay before execution
      unit - time unit for the delay
      Returns:
      the taskId for reference

    • cancelTask

      public boolean cancelTask(String taskId)
      Cancels a scheduled task.
      Parameters:
      taskId - identifier of the task to cancel
      Returns:
      true if the task was found and cancelled, false otherwise

    • getScheduledTaskCount

      public int getScheduledTaskCount()
      Returns the number of currently scheduled tasks.
      Returns:
      the number of active scheduled tasks

    • isScheduled

      public boolean isScheduled(String taskId)
      Checks if a task with the given ID is currently scheduled.
      Parameters:
      taskId - the task identifier to check
      Returns:
      true if the task exists and is not cancelled, false otherwise

    • close

      public void close()
      Shuts down the scheduler and cancels all scheduled tasks.
      Specified by:
      close in interface AutoCloseable

    • callByActionName

      public ActionResult callByActionName(String actionName, String arg)
      Executes an action by name with the given arguments.

      Supported actions:

      • scheduleAtFixedRate - Args: taskId,targetActor,action,args,initialDelay,period,unit
      • scheduleWithFixedDelay - Args: taskId,targetActor,action,args,initialDelay,delay,unit
      • scheduleOnce - Args: taskId,targetActor,action,args,delay,unit
      • cancel - Args: taskId
      • getTaskCount - Args: (none)
      • isScheduled - Args: taskId
      Specified by:
      callByActionName in interface CallableByActionName
      Parameters:
      actionName - the action to execute
      arg - comma-separated arguments
      Returns:
      ActionResult indicating success or failure