de.fhg.fokus.xtensions.concurrent

Class SchedulingUtil

java.lang.Object

de.fhg.fokus.xtensions.concurrent.SchedulingUtil

public final class SchedulingUtil
extends Object

This class provides static functions that can be used to schedule tasks that are either repeated or delayed by a given amount of time. The provided functions are wrappers around ScheduledExecutorService, but provides more readable method names and work with CompletableFutures for better composability of actions.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SchedulingUtil.DelaySpecifier Adds delay information to an action to be scheduled.
static class	SchedulingUtil.ScheduledCompletableFuture<T> This class implements both CompletableFuture and ScheduledFuture, so it can be used in a non-blocking fashion, but still be asked for the delay for the next execution of a scheduled task. This class is not intended to be sub-classed outside of the SchedulingUtil.

Method Summary

Modifier and Type	Method and Description
static <T> SchedulingUtil.ScheduledCompletableFuture<T>	delay(Duration delayBy, Functions.Function1<? super SchedulingUtil.ScheduledCompletableFuture<?>,? extends T> delayed) This method will run the given delayed function after the delay provided via the delayBy parameter.
static <T> SchedulingUtil.ScheduledCompletableFuture<T>	delay(long delayTime, TimeUnit delayUnit, Functions.Function1<? super SchedulingUtil.ScheduledCompletableFuture<?>,? extends T> delayed) This method will run the given delayed function after the delay provided via the parameters delayTime and delayUnit.
static <T> SchedulingUtil.ScheduledCompletableFuture<T>	delay(ScheduledExecutorService scheduler, long delayTime, TimeUnit delayUnit, Functions.Function1<? super SchedulingUtil.ScheduledCompletableFuture<?>,? extends T> delayed) This method will run the given delayed function after the delay provided via the parameters delayTime and delayUnit.
static SchedulingUtil.ScheduledCompletableFuture<?>	repeatEvery(Duration period, Procedures.Procedure1<? super SchedulingUtil.ScheduledCompletableFuture<?>> action) This method will schedule the given action to run in a fixed interval specified via period starting from the time this method is called.
static SchedulingUtil.DelaySpecifier	repeatEvery(long period, TimeUnit unit) This method specifies the fixed time interval in which an action will be repeatedly invoked.
static SchedulingUtil.ScheduledCompletableFuture<?>	repeatEvery(long period, TimeUnit unit, Procedures.Procedure1<? super SchedulingUtil.ScheduledCompletableFuture<?>> action) This method will schedule the given action to run in a fixed time interval specified via period and unit starting from the time this method is called.
static SchedulingUtil.ScheduledCompletableFuture<?>	repeatEvery(ScheduledExecutorService scheduler, Duration period, Procedures.Procedure1<? super CompletableFuture<?>> action) This method will schedule the given action to run in a fixed interval specified via period starting from the time this method is called.
static SchedulingUtil.DelaySpecifier	repeatEvery(ScheduledExecutorService scheduler, long period, TimeUnit unit) This method specifies the fixed time interval in which an action will be repeatedly invoked.
static SchedulingUtil.ScheduledCompletableFuture<?>	repeatEvery(ScheduledExecutorService scheduler, long period, TimeUnit unit, Procedures.Procedure1<? super SchedulingUtil.ScheduledCompletableFuture<?>> action) This method will schedule the given action to run in a fixed time interval specified via period and unit starting from the time this method is called.
static SchedulingUtil.ScheduledCompletableFuture<?>	waitFor(Duration duration) This method returns a CompletableFuture which will be completed with a null value on a new thread after after the delay time specified by the duration parameter. The thread calling this method will not block. Note: The use of Duration may cause a loss in time precision, if the overall duration exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years.
static SchedulingUtil.ScheduledCompletableFuture<?>	waitFor(Duration duration, Procedures.Procedure1<? super CompletableFuture<?>> then) This method will run the given then callback after the delay provided via the parameter duration.
static SchedulingUtil.ScheduledCompletableFuture<?>	waitFor(long time, TimeUnit unit) This method returns a CompletableFuture which will be completed with a null value on a new thread after after the delay time specified by the parameters. The thread calling this method will not block.
static SchedulingUtil.ScheduledCompletableFuture<?>	waitFor(long time, TimeUnit unit, Procedures.Procedure1<? super CompletableFuture<?>> then) This method will run the given then callback after the delay provided via the parameters time and unit.
static SchedulingUtil.ScheduledCompletableFuture<?>	waitFor(ScheduledExecutorService scheduler, long time, TimeUnit unit, Procedures.Procedure1<? super CompletableFuture<?>> then) This method will run the given then callback after the delay provided via the parameters time and unit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

repeatEvery

public static SchedulingUtil.ScheduledCompletableFuture<?> repeatEvery(Duration period,
                                                                       Procedures.Procedure1<? super SchedulingUtil.ScheduledCompletableFuture<?>> action)

This method will schedule the given action to run in a fixed interval specified via period starting from the time this method is called. If action throws, the action will un-scheduled and not called anymore. The returned ScheduledCompletableFuture will also be passed to the action on every scheduled call. The future will only completed via an exception thrown from action, from the outside by the caller or by the action. When the future is be completed (no matter how), the action will be un-scheduled and not be called again.

Be aware that the execution of action will be performed on a single Thread, so if the execution of action takes longer than the specified period, following executions are delayed. Consider using repeatEvery(ScheduledExecutorService, Duration, (CompletableFuture<?>)=>void) to specify an own ScheduledExecutorService which may provide more threads for execution.

Note: The use of Duration may cause a loss in time precision, if the overall period exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years. At most at most 999,999,999 nanoseconds (less than one second) may be stripped. Alternatively you can call repeatEvery(long, TimeUnit, (CompletableFuture<?>)=>void) or repeatEvery(ScheduledExecutorService, long, TimeUnit, (CompletableFuture<?>)=>void) to specify the time without loss of precision.

Parameters:

period - at which the given action should be called.

action - action to be scheduled to be repeatedly called at the given period. The action will be called with the returned ScheduledCompletableFuture which can be used to check for cancellation or complete to stop further executions of the action. If the action throws and exception the future will be completed exceptionally with the thrown exception and the action will not be un-scheduled and not called again.

Returns:

a future that can be checked for the delay until next execution of action and completed to stop further executions of action.

Throws:

NullPointerException - if period or action is null

IllegalArgumentException - if period is a negative duration

See Also:

repeatEvery(long, TimeUnit, org.eclipse.xtext.xbase.lib.Procedures.Procedure1)

repeatEvery

public static SchedulingUtil.ScheduledCompletableFuture<?> repeatEvery(ScheduledExecutorService scheduler,
                                                                       Duration period,
                                                                       Procedures.Procedure1<? super CompletableFuture<?>> action)

This method will schedule the given action to run in a fixed interval specified via period starting from the time this method is called. If action throws, the action will un-scheduled and not called anymore. The returned ScheduledCompletableFuture will also be passed to the action on every scheduled call. The future will only completed via an exception thrown from action, from the outside by the caller or by the action. When the future is be completed (no matter how), the action will be un-scheduled and not be called again.

The action will be scheduled and then executed on the given scheduler.

Note: The use of Duration may cause a loss in time precision, if the overall period exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years. At most at most 999,999,999 nanoseconds (less than one second) may be stripped. Alternatively you can call repeatEvery(long, TimeUnit, (CompletableFuture<?>)=>void) or repeatEvery(ScheduledExecutorService, long, TimeUnit, (CompletableFuture<?>)=>void) to specify the time without loss of precision.

Parameters:

scheduler - the executor service used for scheduling the given action.

period - at which the given action should be called.

action - action to be scheduled to be repeatedly called at the given period. The action will be called with the returned ScheduledCompletableFuture which can be used to check for cancellation or complete to stop further executions of the action. If the action throws and exception the future will be completed exceptionally with the thrown exception and the action will not be un-scheduled and not called again.

Returns:

a future that can be checked for the delay until next execution of action and completed to stop further executions of action.

Throws:

NullPointerException - if period, scheduler, or action is null

IllegalArgumentException - if period is a negative duration

repeatEvery

public static SchedulingUtil.ScheduledCompletableFuture<?> repeatEvery(long period,
                                                                       TimeUnit unit,
                                                                       Procedures.Procedure1<? super SchedulingUtil.ScheduledCompletableFuture<?>> action)

This method will schedule the given action to run in a fixed time interval specified via period and unit starting from the time this method is called. If action throws, the action will un-scheduled and not called anymore. The returned ScheduledCompletableFuture will also be passed to the action on every scheduled call. The future will only completed via an exception thrown from action, from the outside by the caller or by the action. When the future is be completed (no matter how), the action will be un-scheduled and not be called again.

Be aware that the execution of action will be performed on a single Thread, so if the execution of action takes longer than the specified period, following executions are delayed. Consider using repeatEvery(ScheduledExecutorService, Duration, (CompletableFuture<?>)=>void) to specify an own ScheduledExecutorService which may provide more threads for execution.

Parameters:

period - duration in unit at which the given action should be called.

unit - time unit of period for scheduling action.

action - action to be scheduled to be repeatedly called at the given period. The action will be called with the returned ScheduledCompletableFuture which can be used to check for cancellation or complete to stop further executions of the action. If the action throws and exception the future will be completed exceptionally with the thrown exception and the action will not be un-scheduled and not called again.

Returns:

the future that can be used to check for delay till next periodic execution of action or cancellation of further executions of action.

Throws:

NullPointerException - if action or unit is null.

IllegalArgumentException - if period is <= 0

repeatEvery

public static SchedulingUtil.ScheduledCompletableFuture<?> repeatEvery(ScheduledExecutorService scheduler,
                                                                       long period,
                                                                       TimeUnit unit,
                                                                       Procedures.Procedure1<? super SchedulingUtil.ScheduledCompletableFuture<?>> action)

This method will schedule the given action to run in a fixed time interval specified via period and unit starting from the time this method is called. If action throws, the action will un-scheduled and not called anymore. The returned ScheduledCompletableFuture will also be passed to the action on every scheduled call. The future will only completed via an exception thrown from action, from the outside by the caller or by the action. When the future is be completed (no matter how), the action will be un-scheduled and not be called again.

The action will be scheduled and executed on the given scheduler.

Parameters:

scheduler - will be used to schedule repeated execution of action

period - duration in unit at which the given action should be called.

unit - time unit of period for scheduling action.

action - action to be scheduled to be repeatedly called at the given period. The action will be called with the returned ScheduledCompletableFuture which can be used to check for cancellation or complete to stop further executions of the action. If the action throws and exception the future will be completed exceptionally with the thrown exception and the action will not be un-scheduled and not called again.

Returns:

the future that can be used to check for delay till next periodic execution of action or cancellation

Throws:

NullPointerException - if action or unit is null.

IllegalArgumentException - if period is <= 0

repeatEvery

public static SchedulingUtil.DelaySpecifier repeatEvery(long period,
                                                        TimeUnit unit)

This method specifies the fixed time interval in which an action will be repeatedly invoked. The returned SchedulingUtil.DelaySpecifier allows to specify an initial delay and the actual action to be scheduled.
Be aware that the execution of the scheduled action will be performed on a single Thread, so if the execution of the action takes longer than the specified period, following executions are delayed. Consider using repeatEvery(ScheduledExecutorService, long, TimeUnit) if you want to provide a custom ScheduledExecutorService.

Parameters:

period - duration in unit at which action, specified on the returned DelaySpecifier, should be called.

unit - time unit of period for scheduling action specified on the returned DelaySpecifier.

Returns:

object to specify initial delay (of time unit unit) and the action to be scheduled.

Throws:

NullPointerException - if unit is null.

IllegalArgumentException - if period is <= 0

repeatEvery

public static SchedulingUtil.DelaySpecifier repeatEvery(ScheduledExecutorService scheduler,
                                                        long period,
                                                        TimeUnit unit)

This method specifies the fixed time interval in which an action will be repeatedly invoked. The returned SchedulingUtil.DelaySpecifier allows to specify an initial delay and the actual action to be scheduled.
The action is scheduled using the given scheduler.

Parameters:

scheduler - the executor service used for scheduling the action provided to the returned DelaySpecifier.

period - duration in unit at which action, specified on the returned DelaySpecifier, should be called.

unit - time unit of period for scheduling action specified on the returned DelaySpecifier.

Returns:

object to specify initial delay (of time unit unit) and the action to be scheduled.

Throws:

NullPointerException - if unit or scheduler is null.

IllegalArgumentException - if period is <= 0

waitFor

public static SchedulingUtil.ScheduledCompletableFuture<?> waitFor(long time,
                                                                   TimeUnit unit)

This method returns a CompletableFuture which will be completed with a null value on a new thread after after the delay time specified by the parameters.
The thread calling this method will not block.

Parameters:

time - in unit after which the returned future will be completed with null value. The value of this parameter must be > 0.

unit - is the time unit of time

Returns:

the future that can be used to check for delay till completion of the future or to cancel the completion

Throws:

NullPointerException - if unit is null

IllegalArgumentException - if time <= 0

waitFor

public static SchedulingUtil.ScheduledCompletableFuture<?> waitFor(Duration duration)

This method returns a CompletableFuture which will be completed with a null value on a new thread after after the delay time specified by the duration parameter.
The thread calling this method will not block.

Note: The use of Duration may cause a loss in time precision, if the overall duration exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years. At most at most 999,999,999 nanoseconds (less than one second) may be stripped.

Parameters:

duration - is the time after which the returned future will be completed with null value. The value of this parameter must be > 0.

Returns:

the future that can be used to check for delay till completion of the future or to cancel the completion

Throws:

NullPointerException - if duration is null

IllegalArgumentException - if duration value is <= 0

waitFor

public static SchedulingUtil.ScheduledCompletableFuture<?> waitFor(Duration duration,
                                                                   Procedures.Procedure1<? super CompletableFuture<?>> then)

This method will run the given then callback after the delay provided via the parameter duration. The then callback will be executed on a new thread and the future which will be returned will be passed to it. . This allows the callback to check for cancellation during execution. The returned future will complete with a null value after the then procedure returns without throwing an exception. If then throws an exception the returned future will be completed exceptionally with the thrown exception. If the returned future is cancelled before then is executed, the callback will not be called at all.
The thread calling this method will not block.

Note: The use of Duration may cause a loss in time precision, if the overall duration exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years. At most at most 999,999,999 nanoseconds (less than one second) may be stripped.

Parameters:

duration - the time that will at least pass between the method call and the execution of the then procedure. Must be a positive value.

then - the action to be executed when the delay specified via duration expires. This procedure will be called on a new tread. If the action throws an exception, the returned future will be completed exceptionally with the thrown exception. Otherwise the future will be completed with a null value after the successful execution of this action.

Returns:

future that will be completed exceptionally if then throws an exception. Otherwise the future will be completed with a null value after the successful execution of then. If this future is completed by the caller of this method before then is started executing, the action will not be called.

Throws:

NullPointerException - if duration or then is null

IllegalArgumentException - if duration value is <= 0

See Also:

waitFor(ScheduledExecutorService, long, TimeUnit, org.eclipse.xtext.xbase.lib.Procedures.Procedure1), waitFor(long, TimeUnit, org.eclipse.xtext.xbase.lib.Procedures.Procedure1)

waitFor

public static SchedulingUtil.ScheduledCompletableFuture<?> waitFor(long time,
                                                                   TimeUnit unit,
                                                                   Procedures.Procedure1<? super CompletableFuture<?>> then)

This method will run the given then callback after the delay provided via the parameters time and unit. The then callback will be executed on a new thread and the future which will be returned will be passed to it. This allows the callback to check for cancellation during execution. The returned future will complete with a null value after the then procedure returns without throwing an exception. If then throws an exception the returned future will be completed exceptionally with the thrown exception. If the returned future is cancelled before then is executed, the callback will not be called at all.
The thread calling this method will not block.

Parameters:

time - minimum amount of time specified in unit that has to elapse before the then action is executed. This parameter must be a value > 0.

unit - the unit of time defined for time.

then - the action to be executed when the delay specified via time and unit expires. This procedure will be called on a new tread. If the action throws an exception, the returned future will be completed exceptionally with the thrown exception. Otherwise the future will be completed with a null value after the successful execution of this action.

Returns:

future that will be completed exceptionally if then throws an exception. Otherwise the future will be completed with a null value after the successful execution of then. If this future is completed by the caller of this method before then is started executing, the action will not be called.

Throws:

NullPointerException - if then or unit is null

IllegalArgumentException - if time value is <= 0

See Also:

waitFor(ScheduledExecutorService, long, TimeUnit, org.eclipse.xtext.xbase.lib.Procedures.Procedure1), waitFor(Duration, org.eclipse.xtext.xbase.lib.Procedures.Procedure1)

waitFor

public static SchedulingUtil.ScheduledCompletableFuture<?> waitFor(ScheduledExecutorService scheduler,
                                                                   long time,
                                                                   TimeUnit unit,
                                                                   Procedures.Procedure1<? super CompletableFuture<?>> then)

This method will run the given then callback after the delay provided via the parameters time and unit. The then callback will be scheduled and executed on the given scheduler and the future which will be returned will be passed to it. This allows the callback to check for cancellation during execution. The returned future will complete with a null value after the then procedure returns without throwing an exception. If then throws an exception the returned future will be completed exceptionally with the thrown exception. If the returned future is cancelled before then is executed, the callback will not be called at all.
The thread calling this method will not block.

Parameters:

scheduler - is the executor used for scheduling the execution of the action action.

time - minimum amount of time specified in unit that has to elapse before the then action is executed. This parameter must be a value > 0.

unit - the unit of time defined for time.

then - the action to be executed when the delay specified via time and unit expires. This procedure will be scheduled and called on the scheduler. If the action throws an exception, the returned future will be completed exceptionally with the thrown exception. Otherwise the future will be completed with a null value after the successful execution of this action.

Returns:

future that will be completed exceptionally if then throws an exception. Otherwise the future will be completed with a null value after the successful execution of then. If this future is completed by the caller of this method before then is started executing, the action will not be called.

Throws:

NullPointerException - if scheduler, then or unit is null

IllegalArgumentException - if time value is <= 0

See Also:

waitFor(long, TimeUnit, org.eclipse.xtext.xbase.lib.Procedures.Procedure1), waitFor(Duration, org.eclipse.xtext.xbase.lib.Procedures.Procedure1)

delay

public static <T> SchedulingUtil.ScheduledCompletableFuture<T> delay(long delayTime,
                                                                     TimeUnit delayUnit,
                                                                     Functions.Function1<? super SchedulingUtil.ScheduledCompletableFuture<?>,? extends T> delayed)

This method will run the given delayed function after the delay provided via the parameters delayTime and delayUnit. The delayed function will be executed on a new thread and the future which will be returned will be passed to it. This allows the function to check for cancellation during execution. The returned future will complete with a the result value of the delayed function after executing it, without it throwing an exception. If delayed throws an exception the returned future will be completed exceptionally with the thrown exception. If the returned future is cancelled before delayed is executed, the function will not be called at all.
The thread calling this method will not block.

Type Parameters:

T - type of the object returned by the function delayed that will be provided by the returned future.

Parameters:

delayTime - minimum amount of time specified in delayUnit that has to elapse before the delayed action is executed. This parameter must be a value > 0.

delayUnit - the unit of time defined for delayTime.

delayed - the action to be executed when the delay specified via delayTime and delayUnit expires. This function will be called on a new tread. If the function throws an exception, the returned future will be completed exceptionally with the thrown exception. Otherwise the future will be completed with the result value returned from successful execution of this function.

Returns:

future that will be completed exceptionally if delayed throws an exception. Otherwise the future will be completed with the result value of the successful execution of delayed. If this future is completed by the caller of this method before delayed is started executing, the action will not be called.

Throws:

NullPointerException - if delayed or delayUnit is null

IllegalArgumentException - if delayTime value is <= 0

See Also:

delay(Duration, org.eclipse.xtext.xbase.lib.Functions.Function1), delay(ScheduledExecutorService, long, TimeUnit, org.eclipse.xtext.xbase.lib.Functions.Function1)

delay

public static <T> SchedulingUtil.ScheduledCompletableFuture<T> delay(Duration delayBy,
                                                                     Functions.Function1<? super SchedulingUtil.ScheduledCompletableFuture<?>,? extends T> delayed)

This method will run the given delayed function after the delay provided via the delayBy parameter. The delayed function will be executed on a new thread and the future which will be returned will be passed to it. This allows the function to check for cancellation during execution. The returned future will complete with a the result value of the delayed function after executing it, without it throwing an exception. If delayed throws an exception the returned future will be completed exceptionally with the thrown exception. If the returned future is cancelled before delayed is executed, the function will not be called at all.
The thread calling this method will not block.

Note: The use of Duration may cause a loss in time precision, if the overall duration exceeds Long.MAX_VALUE nanoseconds, which is roughly a duration of 292.5 years. At most at most 999,999,999 nanoseconds (less than one second) may be stripped.

Type Parameters:

T - type of the object returned by the function delayed that will be provided by the returned future.

Parameters:

delayBy - minimum duration specified that has to elapse before the delayed action is executed. This parameter must be a positive duration.

delayed - the action to be executed when the delay specified via delayBy expires. This function will be called on a new tread. If the function throws an exception, the returned future will be completed exceptionally with the thrown exception. Otherwise the future will be completed with the result value returned from successful execution of this function.

Returns:

future that will be completed exceptionally if delayed throws an exception. Otherwise the future will be completed with the result value of the successful execution of delayed. If this future is completed by the caller of this method before delayed is started executing, the action will not be called.

Throws:

NullPointerException - if delayed or delayUnit is null

IllegalArgumentException - if delayBy time is <= 0

See Also:

delay(long, TimeUnit, org.eclipse.xtext.xbase.lib.Functions.Function1), delay(ScheduledExecutorService, long, TimeUnit, org.eclipse.xtext.xbase.lib.Functions.Function1)

delay

public static <T> SchedulingUtil.ScheduledCompletableFuture<T> delay(ScheduledExecutorService scheduler,
                                                                     long delayTime,
                                                                     TimeUnit delayUnit,
                                                                     Functions.Function1<? super SchedulingUtil.ScheduledCompletableFuture<?>,? extends T> delayed)

This method will run the given delayed function after the delay provided via the parameters delayTime and delayUnit. The delayed function will be scheduled and executed using the given scheduler and the future which will be returned will be passed to it. This allows the function to check for cancellation during execution. The returned future will complete with a the result value of the delayed function after executing it, without it throwing an exception. If delayed throws an exception the returned future will be completed exceptionally with the thrown exception. If the returned future is cancelled before delayed is executed, the function will not be called at all.
The thread calling this method will not block.

Type Parameters:

T - type of the object returned by the function delayed that will be provided by the returned future.

Parameters:

scheduler - is the executor used for scheduling and executing of the delayed function.

delayTime - minimum amount of time specified in delayUnit that has to elapse before the delayed function is executed. This parameter must be a value > 0.

delayUnit - the unit of time defined for delayTime.

delayed - the action to be executed when the delay specified via delayTime and delayUnit expires. This function will be called on a new tread. If the function throws an exception, the returned future will be completed exceptionally with the thrown exception. Otherwise the future will be completed with the result value returned from successful execution of this function.

Returns:

future that will be completed exceptionally if delayed throws an exception. Otherwise the future will be completed with the result value of the successful execution of delayed. If this future is completed by the caller of this method before delayed is started executing, the action will not be called.

Throws:

NullPointerException - if delayed or delayUnit is null

IllegalArgumentException - if delayTime value is <= 0

See Also:

delay(Duration, org.eclipse.xtext.xbase.lib.Functions.Function1), delay(long, TimeUnit, org.eclipse.xtext.xbase.lib.Functions.Function1)