com.hazelcast.scheduledexecutor

## Interface IScheduledExecutorService

- All Superinterfaces:
    DistributedObject
  All Known Implementing Classes:
    ClientScheduledExecutorProxy

      public interface IScheduledExecutorService
      extends DistributedObject

  Distributed & durable implementation similar to, but not directly inherited `ScheduledExecutorService`. `IScheduledExecutorService` provides similar API to the `ScheduledExecutorService` with some exceptions but also additional methods like scheduling tasks on a specific member, on a member who is owner of a specific key, executing a tasks on multiple members etc.

  Tasks (`Runnable` and/or `Callable`) scheduled on any partition through an `IScheduledExecutorService`, yield some durability characteristics.

  - When a node goes down (up to `durability` config), the scheduled task will get re-scheduled on a replica node.
  - In the event of a partition migration, the task will be re-scheduled on the destination node.
  Note: The above characteristics don't apply when scheduled on a `Member`.

  Upon scheduling, a task acquires a resource handler, see `ScheduledTaskHandler`. The handler is generated before the actual scheduling of the task on the node, which allows for a way to access the future in an event of a node failure, immediately after scheduling, and also guarantees no duplicates in the cluster by utilising a unique name per task. A name can also be defined by the user by having the `Runnable` or `Callable` implement the `NamedTask`. Alternatively, one can wrap any task using the `TaskUtils.named(String, Callable)` or `TaskUtils.named(String, Runnable)` for simplicity.

  One difference of this service in comparison to `ScheduledExecutorService` is the `scheduleAtFixedRate(Runnable, long, long, TimeUnit)` which has similar semantic to `ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit)`. It guarantees a task won't be executed by multiple threads concurrently. The difference is that this service will skip a scheduled execution if another thread is still running the same task, instead of postponing its execution.

  The other difference is this service does not offer an equivalent of `ScheduledExecutorService.scheduleWithFixedDelay(Runnable, long, long, TimeUnit)`

  Tasks that are holding state that needs to be also durable across partitions, will need to implement the `StatefulTask` interface.

  Supports Quorum `QuorumConfig` since 3.10 in cluster versions 3.10 and higher.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `<V> Map<Member,List<IScheduledFuture<V>>>` | `getAllScheduledFutures()` Fetches and returns all scheduled (not disposed yet) futures from all members in the cluster.
    `<V> IScheduledFuture<V>` | `getScheduledFuture(ScheduledTaskHandler handler)` Creates a new `IScheduledFuture` from the given handler.
    `<V> IScheduledFuture<V>` | `schedule(Callable<V> command, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay.
    `IScheduledFuture<?>` | `schedule(Runnable command, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay.
    `IScheduledFuture<?>` | `scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)` Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period.
    `<V> Map<Member,IScheduledFuture<V>>` | `scheduleOnAllMembers(Callable<V> command, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay on all cluster `Member`s.
    `Map<Member,IScheduledFuture<?>>` | `scheduleOnAllMembers(Runnable command, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay on all cluster `Member`s.
    `Map<Member,IScheduledFuture<?>>` | `scheduleOnAllMembersAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)` Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all cluster `Member`s.
    `<V> IScheduledFuture<V>` | `scheduleOnKeyOwner(Callable<V> command, Object key, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
    `IScheduledFuture<?>` | `scheduleOnKeyOwner(Runnable command, Object key, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
    `IScheduledFuture<?>` | `scheduleOnKeyOwnerAtFixedRate(Runnable command, Object key, long initialDelay, long period, TimeUnit unit)` Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on the partition owner of the given key.
    `<V> IScheduledFuture<V>` | `scheduleOnMember(Callable<V> command, Member member, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay at the given `Member`.
    `IScheduledFuture<?>` | `scheduleOnMember(Runnable command, Member member, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay at the given `Member`.
    `IScheduledFuture<?>` | `scheduleOnMemberAtFixedRate(Runnable command, Member member, long initialDelay, long period, TimeUnit unit)` Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period at the given `Member`.
    `<V> Map<Member,IScheduledFuture<V>>` | `scheduleOnMembers(Callable<V> command, Collection<Member> members, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay on all `Member`s given.
    `Map<Member,IScheduledFuture<?>>` | `scheduleOnMembers(Runnable command, Collection<Member> members, long delay, TimeUnit unit)` Creates and executes a one-shot action that becomes enabled after the given delay on all `Member`s given.
    `Map<Member,IScheduledFuture<?>>` | `scheduleOnMembersAtFixedRate(Runnable command, Collection<Member> members, long initialDelay, long period, TimeUnit unit)` Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all `Member`s given.
    `void` | `shutdown()` Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.

    - ### Methods inherited from interface com.hazelcast.core.DistributedObject

      `destroy, getName, getPartitionKey, getServiceName`

- - ### Method Detail

    - #### schedule

          IScheduledFuture<?> schedule(Runnable command,
                                       long delay,
                                       TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay.
      Parameters:
        `command` - the task to execute
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### schedule

          <V> IScheduledFuture<V> schedule(Callable<V> command,
                                           long delay,
                                           TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay.
      Parameters:
        `command` - the task to execute
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleAtFixedRate

          IScheduledFuture<?> scheduleAtFixedRate(Runnable command,
                                                  long initialDelay,
                                                  long period,
                                                  TimeUnit unit)

      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period. Executions will commence after `initialDelay` then `initialDelay+period`, then `initialDelay + 2 * period`, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.
      Parameters:
        `command` - the task to execute
        `initialDelay` - the time to delay first execution
        `period` - the period between successive executions
        `unit` - the time unit of the initialDelay and period parameters
      Returns:
        a ScheduledFuture representing pending completion of the task, and whose `get()` method will throw an exception upon cancellation
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnMember

          IScheduledFuture<?> scheduleOnMember(Runnable command,
                                               Member member,
                                               long delay,
                                               TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay at the given `Member`.
      Parameters:
        `command` - the task to execute
        `member` - the member to execute the task
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnMember

          <V> IScheduledFuture<V> scheduleOnMember(Callable<V> command,
                                                   Member member,
                                                   long delay,
                                                   TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay at the given `Member`.
      Parameters:
        `command` - the task to execute
        `member` - the member to execute the task
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnMemberAtFixedRate

          IScheduledFuture<?> scheduleOnMemberAtFixedRate(Runnable command,
                                                          Member member,
                                                          long initialDelay,
                                                          long period,
                                                          TimeUnit unit)

      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period at the given `Member`. Executions will commence after `initialDelay` then `initialDelay+period`, then `initialDelay + 2 * period`, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.
      Parameters:
        `command` - the task to execute
        `member` - the member to execute the task
        `initialDelay` - the time to delay first execution
        `period` - the period between successive executions
        `unit` - the time unit of the initialDelay and period parameters
      Returns:
        a ScheduledFuture representing pending completion of the task, and whose `get()` method will throw an exception upon cancellation
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnKeyOwner

          IScheduledFuture<?> scheduleOnKeyOwner(Runnable command,
                                                 Object key,
                                                 long delay,
                                                 TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
      Parameters:
        `command` - the task to execute
        `key` - the key to identify the partition owner, which will execute the task
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnKeyOwner

          <V> IScheduledFuture<V> scheduleOnKeyOwner(Callable<V> command,
                                                     Object key,
                                                     long delay,
                                                     TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
      Parameters:
        `command` - the task to execute
        `key` - the key to identify the partition owner, which will execute the task
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnKeyOwnerAtFixedRate

          IScheduledFuture<?> scheduleOnKeyOwnerAtFixedRate(Runnable command,
                                                            Object key,
                                                            long initialDelay,
                                                            long period,
                                                            TimeUnit unit)

      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on the partition owner of the given key. Executions will commence after `initialDelay` then `initialDelay+period`, then `initialDelay + 2 * period`, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.
      Parameters:
        `command` - the task to execute
        `key` - the key to identify the partition owner, which will execute the task
        `initialDelay` - the time to delay first execution
        `period` - the period between successive executions
        `unit` - the time unit of the initialDelay and period parameters
      Returns:
        a ScheduledFuture representing pending completion of the task, and whose `get()` method will throw an exception upon cancellation
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnAllMembers

          Map<Member,IScheduledFuture<?>> scheduleOnAllMembers(Runnable command,
                                                               long delay,
                                                               TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay on all cluster `Member`s.

      Note: In the event of Member leaving the cluster, for whatever reason, the task is lost. If a new member is added, the task will not get scheduled there automatically.

      Parameters:
        `command` - the task to execute
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnAllMembers

          <V> Map<Member,IScheduledFuture<V>> scheduleOnAllMembers(Callable<V> command,
                                                                   long delay,
                                                                   TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay on all cluster `Member`s.

      Note: In the event of Member leaving the cluster, for whatever reason, the task is lost. If a new member is added, the task will not get scheduled there automatically.

      Parameters:
        `command` - the task to execute
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnAllMembersAtFixedRate

          Map<Member,IScheduledFuture<?>> scheduleOnAllMembersAtFixedRate(Runnable command,
                                                                          long initialDelay,
                                                                          long period,
                                                                          TimeUnit unit)

      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all cluster `Member`s. Executions will commence after `initialDelay` then `initialDelay+period`, then `initialDelay + 2 * period`, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

      Note: In the event of Member leaving the cluster, for whatever reason, the task is lost. If a new member is added, the task will not get scheduled there automatically.

      Parameters:
        `command` - the task to execute
        `initialDelay` - the time to delay first execution
        `period` - the period between successive executions
        `unit` - the time unit of the initialDelay and period parameters
      Returns:
        a ScheduledFuture representing pending completion of the task, and whose `get()` method will throw an exception upon cancellation
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnMembers

          Map<Member,IScheduledFuture<?>> scheduleOnMembers(Runnable command,
                                                            Collection<Member> members,
                                                            long delay,
                                                            TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay on all `Member`s given.

      Note: In the event of Member leaving the cluster, for whatever reason, the task is lost.

      Parameters:
        `command` - the task to execute
        `members` - the collections of members - where to execute the task
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnMembers

          <V> Map<Member,IScheduledFuture<V>> scheduleOnMembers(Callable<V> command,
                                                                Collection<Member> members,
                                                                long delay,
                                                                TimeUnit unit)

      Creates and executes a one-shot action that becomes enabled after the given delay on all `Member`s given.

      Note: In the event of Member leaving the cluster, for whatever reason, the task is lost.

      Parameters:
        `command` - the task to execute
        `members` - the collections of members - where to execute the task
        `delay` - the time from now to delay execution
        `unit` - the time unit of the delay parameter
      Returns:
        a ScheduledFuture representing pending completion of the task and whose `get()` method will return `null` upon completion
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### scheduleOnMembersAtFixedRate

          Map<Member,IScheduledFuture<?>> scheduleOnMembersAtFixedRate(Runnable command,
                                                                       Collection<Member> members,
                                                                       long initialDelay,
                                                                       long period,
                                                                       TimeUnit unit)

      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all `Member`s given. Executions will commence after `initialDelay` then `initialDelay+period`, then `initialDelay + 2 * period`, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

      Note: In the event of Member leaving the cluster, for whatever reason, the task is lost.

      Parameters:
        `command` - the task to execute
        `members` - the collections of members - where to execute the task
        `initialDelay` - the time to delay first execution
        `period` - the period between successive executions
        `unit` - the time unit of the initialDelay and period parameters
      Returns:
        a ScheduledFuture representing pending completion of the task, and whose `get()` method will throw an exception upon cancellation
      Throws:
        `RejectedExecutionException` - if the task cannot be scheduled for execution
        `NullPointerException` - if command is null

    - #### getScheduledFuture

          <V> IScheduledFuture<V> getScheduledFuture(ScheduledTaskHandler handler)

      Creates a new `IScheduledFuture` from the given handler. This is useful in case your member node or client from which the original scheduling happened, went down, and now you want to access the `ScheduledFuture` again.
      Type Parameters:
        `V` - The return type of callable tasks
      Parameters:
        `handler` - The handler of the task as found from `IScheduledFuture.getHandler()`
      Returns:
        A new `IScheduledFuture` from the given handler.

    - #### getAllScheduledFutures

          <V> Map<Member,List<IScheduledFuture<V>>> getAllScheduledFutures()

      Fetches and returns all scheduled (not disposed yet) futures from all members in the cluster. If a member has no running tasks for this scheduler, it wont be included in the returned `Map`.
      Returns:
        A `Map` with `Member` keys and a List of `IScheduledFuture` found for this scheduler.

    - #### shutdown

          void shutdown()

      Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted. Invocation has no additional effect if already shut down.

      This method does not wait for previously submitted tasks to complete execution.

Copyright © 2019. All rights reserved.