UnboundScheduledExecutorService (JOTA : Library 1.0.0-beta7 API)

java.lang.Object
- org.iota.jota.utils.thread.UnboundScheduledExecutorService

All Implemented Interfaces:

Executor, ExecutorService, ScheduledExecutorService, ReportingExecutorService
```
public class UnboundScheduledExecutorService
extends Object
implements ScheduledExecutorService, ReportingExecutorService
```
This class represents a SilentScheduledExecutorService that accepts only a pre-defined amount of tasks that can be queued or executed at the same time. All tasks exceeding the defined limit will be ignored (instead of being queued) by either throwing a RejectedExecutionException or returning null depending on the method we call (non-silent vs silent).

Whenever a non-recurring task finishes (or a recurring one is cancelled through its Future), it makes space for a new task. This is useful for classes like the com.iota.iri.utils.log.interval.IntervalLogger that want to delay an action if and only if there is no other delayed action queued already.

Note: In contrast to other existing implementations like the SizedScheduledExecutorService of the apache package, this class is thread-safe and will only allow to spawn and queue the exact amount of tasks defined during its creation (since it does not rely on approximate numbers like the queue size).

Constructor Summary

Constructors
Constructor and Description
`UnboundScheduledExecutorService()` Creates an executor service that that accepts only a pre-defined amount of tasks that can be queued and run at the same time. All tasks exceeding the defined limit will be ignored (instead of being queued) by either throwing a `RejectedExecutionException` or returning `null` depending on the method we call (non-silent vs silent).

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`awaitTermination(long timeout, TimeUnit unit)`
`void`	`execute(Runnable task)` Note: Since there is no `Future` passed to the caller, we only wrap the `Runnable` to correctly free the resources.
`<T> List<Future<T>>`	`invokeAll(Collection<? extends Callable<T>> tasks)` Note: Since the `Future`s will all be finished (and cannot be cancelled anymore) when the underlying method returns, we only wrap the `Callable`s to correctly free the resources and omit wrapping the returned `Future`s.
`<T> List<Future<T>>`	`invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)` Note: Since the `Future`s will all be finished (and cannot be cancelled anymore) when the underlying method returns, we only wrap the `Callable`s to correctly free the resources and omit wrapping the returned `Future`s.
`<T> T`	`invokeAny(Collection<? extends Callable<T>> tasks)` Note: Since the `Future`s are not passed to the caller, we only wrap the `Callable`s to correctly free the resources and omit wrapping the `Future`s as well.
`<T> T`	`invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)` Note: Since the `Future`s are not passed to the caller, we only wrap the `Callable`s to correctly free the resources and omit wrapping the related `Future`s as well.
`boolean`	`isShutdown()`
`boolean`	`isTerminated()`
`void`	`onCancelTask(TaskDetails taskDetails)` This method gets called whenever a task is cancelled through its `Future` or through the shutdown methods of the `ExecutorService`. It only gets called once for every task.
`void`	`onCompleteTask(TaskDetails taskDetails, Throwable error)` This method gets called whenever a task completes. This can be through either raising an exception, cancelling from the outside or by simply terminating in a normal manner.
`void`	`onFinishTask(TaskDetails taskDetails, Throwable error)` This method gets called whenever a task is finished. For recurring tasks it is called multiple times.
`void`	`onScheduleTask(TaskDetails taskDetails)` This method gets called whenever a new task is scheduled to run. In contrast to `ReportingExecutorService.onStartTask(TaskDetails)` this method gets called only once for "recurring" tasks that are scheduled to run in pre-defined intervals.
`void`	`onStartTask(TaskDetails taskDetails)` This method gets called whenever a task is started. For recurring tasks it is called multiple times.
`<V> ScheduledFuture<V>`	`schedule(Callable<V> task, long delay, TimeUnit unit)` Note: Since the `ScheduledFuture` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `ScheduledFuture` AND the `Callable` to correctly free the resources if its `Future.cancel(boolean)` method is called.
`ScheduledFuture<?>`	`schedule(Runnable task, long delay, TimeUnit unit)` Note: Since the `ScheduledFuture` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `ScheduledFuture` AND the `Runnable` to correctly free the resources if its `Future.cancel(boolean)` method is called.
`ScheduledFuture<?>`	`scheduleAtFixedRate(Runnable task, long initialDelay, long period, TimeUnit unit)` Note: Since the `ScheduledFuture` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `ScheduledFuture` AND the `Runnable` to correctly free the resources if its `Future.cancel(boolean)` method is called.
`ScheduledFuture<?>`	`scheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit)` Note: Since the `ScheduledFuture` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `ScheduledFuture` AND the `Runnable` to correctly free the resources if its `Future.cancel(boolean)` method is called.
`void`	`shutdown()` In addition to delegating the method call to the internal `ScheduledExecutorService`, we call the cancel logic for recurring tasks because shutdown prevents them from firing again.
`List<Runnable>`	`shutdownNow()` Before delegating the method call to the internal `ScheduledExecutorService`, we call the `onCancelTask(TaskDetails)` callback for all scheduled tasks and fire the `onCompleteTask(TaskDetails, Throwable)` callback for all tasks that are not being executed right now (otherwise this will be fired inside the wrapped task).
`<T> Future<T>`	`submit(Callable<T> task)` Note: Since the `Future` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `Future` AND the `Callable` to correctly free the resources if its `Future.cancel(boolean)` method is called.
`Future<?>`	`submit(Runnable task)` Note: Since the `Future` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `Future` AND the `Runnable` to correctly free the resources if its `Future.cancel(boolean)` method is called.
`<T> Future<T>`	`submit(Runnable task, T result)` Note: Since the `Future` returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned `Future` AND the `Runnable` to correctly free the resources if its `Future.cancel(boolean)` method is called.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - UnboundScheduledExecutorService
```
public UnboundScheduledExecutorService()
```
    Creates an executor service that that accepts only a pre-defined amount of tasks that can be queued and run at the same time.
    
    All tasks exceeding the defined limit will be ignored (instead of being queued) by either throwing a RejectedExecutionException or returning null depending on the method we call (non-silent vs silent).
    
    Parameters:
    
    capacity - the amount of tasks that can be scheduled simultaneously
- Method Detail
  - onScheduleTask
```
public void onScheduleTask(TaskDetails taskDetails)
```
    This method gets called whenever a new task is scheduled to run.
    
    In contrast to ReportingExecutorService.onStartTask(TaskDetails) this method gets called only once for "recurring" tasks that are scheduled to run in pre-defined intervals.
    
    It simply adds the task to the internal set of scheduled tasks.
    
    Specified by:
    
    onScheduleTask in interface ReportingExecutorService
    
    Parameters:
    
    taskDetails - object containing details about this task
  - onStartTask
```
public void onStartTask(TaskDetails taskDetails)
```
    Description copied from interface: ReportingExecutorService
    
    This method gets called whenever a task is started.
    
    For recurring tasks it is called multiple times.
    
    Specified by:
    
    onStartTask in interface ReportingExecutorService
    
    Parameters:
    
    taskDetails - object containing details about this task
  - onFinishTask
```
public void onFinishTask(TaskDetails taskDetails,
                         Throwable error)
```
    Description copied from interface: ReportingExecutorService
    
    This method gets called whenever a task is finished.
    
    For recurring tasks it is called multiple times.
    
    Specified by:
    
    onFinishTask in interface ReportingExecutorService
    
    Parameters:
    
    taskDetails - object containing details about this task
    
    error - Exception that caused the task to complete
  - onCancelTask
```
public void onCancelTask(TaskDetails taskDetails)
```
    Description copied from interface: ReportingExecutorService
    
    This method gets called whenever a task is cancelled through its Future or through the shutdown methods of the ExecutorService.
    
    It only gets called once for every task.
    
    Specified by:
    
    onCancelTask in interface ReportingExecutorService
    
    Parameters:
    
    taskDetails - object containing details about this task
  - onCompleteTask
```
public void onCompleteTask(TaskDetails taskDetails,
                           Throwable error)
```
    This method gets called whenever a task completes.
    
    This can be through either raising an exception, cancelling from the outside or by simply terminating in a normal manner. For recurring tasks this only gets called once.
    
    It frees the reserved resources by decrementing the scheduledTasksCounter and removing the task from the scheduledTasks set.
    
    Specified by:
    
    onCompleteTask in interface ReportingExecutorService
    
    Parameters:
    
    taskDetails - object containing details about this task
    
    error - Exception that caused the task to complete
  - schedule
```
public ScheduledFuture<?> schedule(Runnable task,
                                   long delay,
                                   TimeUnit unit)
```
    Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    schedule in interface ScheduledExecutorService
  - schedule
```
public <V> ScheduledFuture<V> schedule(Callable<V> task,
                                       long delay,
                                       TimeUnit unit)
```
    Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Callable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    schedule in interface ScheduledExecutorService
  - scheduleAtFixedRate
```
public ScheduledFuture<?> scheduleAtFixedRate(Runnable task,
                                              long initialDelay,
                                              long period,
                                              TimeUnit unit)
```
    Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    scheduleAtFixedRate in interface ScheduledExecutorService
  - scheduleWithFixedDelay
```
public ScheduledFuture<?> scheduleWithFixedDelay(Runnable task,
                                                 long initialDelay,
                                                 long delay,
                                                 TimeUnit unit)
```
    Note: Since the ScheduledFuture returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned ScheduledFuture AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    scheduleWithFixedDelay in interface ScheduledExecutorService
  - submit
```
public <T> Future<T> submit(Callable<T> task)
```
    Note: Since the Future returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned Future AND the Callable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    submit in interface ExecutorService
  - submit
```
public Future<?> submit(Runnable task)
```
    Note: Since the Future returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned Future AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    submit in interface ExecutorService
  - submit
```
public <T> Future<T> submit(Runnable task,
                            T result)
```
    Note: Since the Future returned by this method allows to cancel jobs without their unwinding logic being executed, we wrap the returned Future AND the Runnable to correctly free the resources if its Future.cancel(boolean) method is called.
    
    Specified by:
    
    submit in interface ExecutorService
  - invokeAll
```
public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
                              throws InterruptedException
```
    Note: Since the Futures will all be finished (and cannot be cancelled anymore) when the underlying method returns, we only wrap the Callables to correctly free the resources and omit wrapping the returned Futures.
    
    Specified by:
    
    invokeAll in interface ExecutorService
    
    Throws:
    
    InterruptedException
  - invokeAll
```
public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
                                     long timeout,
                                     TimeUnit unit)
                              throws InterruptedException
```
    Note: Since the Futures will all be finished (and cannot be cancelled anymore) when the underlying method returns, we only wrap the Callables to correctly free the resources and omit wrapping the returned Futures.
    
    Specified by:
    
    invokeAll in interface ExecutorService
    
    Throws:
    
    InterruptedException
  - invokeAny
```
public <T> T invokeAny(Collection<? extends Callable<T>> tasks)
                throws InterruptedException,
                       ExecutionException
```
    Note: Since the Futures are not passed to the caller, we only wrap the Callables to correctly free the resources and omit wrapping the Futures as well.
    
    Specified by:
    
    invokeAny in interface ExecutorService
    
    Throws:
    
    InterruptedException
    
    ExecutionException
  - invokeAny
```
public <T> T invokeAny(Collection<? extends Callable<T>> tasks,
                       long timeout,
                       TimeUnit unit)
                throws InterruptedException,
                       ExecutionException,
                       TimeoutException
```
    Note: Since the Futures are not passed to the caller, we only wrap the Callables to correctly free the resources and omit wrapping the related Futures as well.
    
    Specified by:
    
    invokeAny in interface ExecutorService
    
    Throws:
    
    InterruptedException
    
    ExecutionException
    
    TimeoutException
  - execute
```
public void execute(Runnable task)
```
    Note: Since there is no Future passed to the caller, we only wrap the Runnable to correctly free the resources.
    
    Specified by:
    
    execute in interface Executor
  - shutdown
```
public void shutdown()
```
    In addition to delegating the method call to the internal ScheduledExecutorService, we call the cancel logic for recurring tasks because shutdown prevents them from firing again. If these "cancelled" jobs are scheduled for execution (and not running right now), we also call their onCompleteTask(TaskDetails, Throwable) callback to "report" that hey have finished (otherwise this will be fired inside the wrapped task).
    
    Specified by:
    
    shutdown in interface ExecutorService
  - shutdownNow
```
public List<Runnable> shutdownNow()
```
    Before delegating the method call to the internal ScheduledExecutorService, we call the onCancelTask(TaskDetails) callback for all scheduled tasks and fire the onCompleteTask(TaskDetails, Throwable) callback for all tasks that are not being executed right now (otherwise this will be fired inside the wrapped task).
    
    Specified by:
    
    shutdownNow in interface ExecutorService
  - isShutdown
```
public boolean isShutdown()
```
    Specified by:
    
    isShutdown in interface ExecutorService
  - isTerminated
```
public boolean isTerminated()
```
    Specified by:
    
    isTerminated in interface ExecutorService
  - awaitTermination
```
public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException
```
    Specified by:
    
    awaitTermination in interface ExecutorService
    
    Throws:
    
    InterruptedException

Class UnboundScheduledExecutorService

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

UnboundScheduledExecutorService

Method Detail

onScheduleTask

onStartTask

onFinishTask

onCancelTask

onCompleteTask

schedule

schedule

scheduleAtFixedRate

scheduleWithFixedDelay

submit

submit

submit

invokeAll

invokeAll

invokeAny

invokeAny

execute

shutdown

shutdownNow

isShutdown

isTerminated

awaitTermination