Class PromiseFactory


  • @ConsumerType
    public class PromiseFactory
    extends java.lang.Object
    Promise factory to create Deferred and Promise objects.

    Instances of this class can be used to create Deferred and Promise objects which use the executors used to construct this object for any callback or scheduled operation execution.

    Since:
    1.1
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  PromiseFactory.All<T,​S extends T>
      A callback used to resolve the specified Promise when the specified list of Promises are resolved for the all(Collection) method.
      private static class  PromiseFactory.DefaultExecutors
      Default executors for Promises.
      private static class  PromiseFactory.InlineExecutor
      An Executor implementation which executes the task immediately on the thread calling the Executor.execute method.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.concurrent.Executor callbackExecutor
      The executor to use for callbacks.
      (package private) static PromiseFactory defaultFactory
      The default factory which uses the default callback executor and default scheduled executor.
      private java.util.concurrent.ScheduledExecutorService scheduledExecutor
      The executor to use for scheduled operations.
    • Constructor Summary

      Constructors 
      Constructor Description
      PromiseFactory​(java.util.concurrent.Executor callbackExecutor)
      Create a new PromiseFactory with the specified callback executor.
      PromiseFactory​(java.util.concurrent.Executor callbackExecutor, java.util.concurrent.ScheduledExecutorService scheduledExecutor)
      Create a new PromiseFactory with the specified callback executor and specified scheduled executor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <T,​S extends T>
      Promise<java.util.List<T>>
      all​(java.util.Collection<Promise<S>> promises)
      Returns a new Promise that is a latch on the resolution of the specified Promises.
      <T> Deferred<T> deferred()
      Create a new Deferred with the callback executor and scheduled executor of this PromiseFactory object.
      java.util.concurrent.Executor executor()
      Returns the executor to use for callbacks.
      <T> Promise<T> failed​(java.lang.Throwable failure)
      Returns a new Promise that has been resolved with the specified failure.
      static java.util.concurrent.Executor inlineExecutor()
      Returns an Executor implementation that executes tasks immediately on the thread calling the Executor.execute method.
      <T> Promise<T> resolved​(T value)
      Returns a new Promise that has been resolved with the specified value.
      java.util.concurrent.ScheduledExecutorService scheduledExecutor()
      Returns the scheduled executor to use for scheduled operations.
      <T> Promise<T> submit​(java.util.concurrent.Callable<? extends T> task)
      Returns a new Promise that will hold the result of the specified task.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • defaultFactory

        static final PromiseFactory defaultFactory
        The default factory which uses the default callback executor and default scheduled executor.
      • callbackExecutor

        private final java.util.concurrent.Executor callbackExecutor
        The executor to use for callbacks. If null, the default callback executor is used.
      • scheduledExecutor

        private final java.util.concurrent.ScheduledExecutorService scheduledExecutor
        The executor to use for scheduled operations. If null, the default scheduled executor is used.
    • Constructor Detail

      • PromiseFactory

        public PromiseFactory​(java.util.concurrent.Executor callbackExecutor)
        Create a new PromiseFactory with the specified callback executor.

        The default scheduled executor will be used.

        Parameters:
        callbackExecutor - The executor to use for callbacks. null can be specified for the default callback executor.
      • PromiseFactory

        public PromiseFactory​(java.util.concurrent.Executor callbackExecutor,
                              java.util.concurrent.ScheduledExecutorService scheduledExecutor)
        Create a new PromiseFactory with the specified callback executor and specified scheduled executor.
        Parameters:
        callbackExecutor - The executor to use for callbacks. null can be specified for the default callback executor.
        scheduledExecutor - The scheduled executor for use for scheduled operations. null can be specified for the default scheduled executor.
    • Method Detail

      • executor

        public java.util.concurrent.Executor executor()
        Returns the executor to use for callbacks.
        Returns:
        The executor to use for callbacks. This will be the default callback executor if null was specified for the callback executor when this PromiseFactory was created.
      • scheduledExecutor

        public java.util.concurrent.ScheduledExecutorService scheduledExecutor()
        Returns the scheduled executor to use for scheduled operations.
        Returns:
        The scheduled executor to use for scheduled operations. This will be the default scheduled executor if null was specified for the scheduled executor when this PromiseFactory was created.
      • deferred

        public <T> Deferred<T> deferred()
        Create a new Deferred with the callback executor and scheduled executor of this PromiseFactory object.

        Use this method instead of Deferred() to create a new Deferred whose associated Promise uses executors other than the default executors.

        Type Parameters:
        T - The value type associated with the returned Deferred.
        Returns:
        A new Deferred with the callback and scheduled executors of this PromiseFactory object
      • resolved

        public <T> Promise<T> resolved​(T value)
        Returns a new Promise that has been resolved with the specified value.

        The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object

        Use this method instead of Promises.resolved(Object) to create a Promise which uses executors other than the default executors.

        Type Parameters:
        T - The value type associated with the returned Promise.
        Parameters:
        value - The value of the resolved Promise.
        Returns:
        A new Promise that has been resolved with the specified value.
      • failed

        public <T> Promise<T> failed​(java.lang.Throwable failure)
        Returns a new Promise that has been resolved with the specified failure.

        The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object

        Use this method instead of Promises.failed(Throwable) to create a Promise which uses executors other than the default executors.

        Type Parameters:
        T - The value type associated with the returned Promise.
        Parameters:
        failure - The failure of the resolved Promise. Must not be null.
        Returns:
        A new Promise that has been resolved with the specified failure.
      • submit

        public <T> Promise<T> submit​(java.util.concurrent.Callable<? extends T> task)
        Returns a new Promise that will hold the result of the specified task.

        The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object

        The specified task will be executed on the callback executor.

        Type Parameters:
        T - The value type associated with the returned Promise.
        Parameters:
        task - The task whose result will be available from the returned Promise.
        Returns:
        A new Promise that will hold the result of the specified task.
      • all

        public <T,​S extends T> Promise<java.util.List<T>> all​(java.util.Collection<Promise<S>> promises)
        Returns a new Promise that is a latch on the resolution of the specified Promises.

        The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object

        The returned Promise acts as a gate and must be resolved after all of the specified Promises are resolved.

        Type Parameters:
        T - The value type of the List value associated with the returned Promise.
        S - A subtype of the value type of the List value associated with the returned Promise.
        Parameters:
        promises - The Promises which must be resolved before the returned Promise must be resolved. Must not be null and all of the elements in the collection must not be null.
        Returns:
        A Promise that must be successfully resolved with a List of the values in the order of the specified Promises if all the specified Promises are successfully resolved. The List in the returned Promise is the property of the caller and is modifiable. The returned Promise must be resolved with a failure of FailedPromisesException if any of the specified Promises are resolved with a failure. The failure FailedPromisesException must contain all of the specified Promises which resolved with a failure.
      • inlineExecutor

        public static java.util.concurrent.Executor inlineExecutor()
        Returns an Executor implementation that executes tasks immediately on the thread calling the Executor.execute method.
        Returns:
        An Executor implementation that executes tasks immediately on the thread calling the Executor.execute method.