public class Deferred
extends Result

async request processing

A Deferred result, useful for async request processing.

Application can produces a result from a different thread. Once result is ready, a call to resolve(Object) is required. Please note, a call to reject(Throwable) is required in case of errors.

usage

 {
    get("/async", deferred(()  -> {
      return "Success";
    }));
  }

From MVC route:



  public class Controller {
    &#64;GET
    &#64;Path("/async")
    public Deferred async() {
      return Deferred.deferred(() -> "Success");
    }
  }

If you add the AsyncMapper then your controller method can return a Callable. Previous example runs in the default executor, which always run deferred results in the same/caller thread. To effectively run a deferred result in new/different thread you need to provide an Executor:


 {
   executor(new ForkJoinPool());
 }

This line override the default executor with a ForkJoinPool. You can add two or more named executor:


 {
   executor(new ForkJoinPool());

   executor("cached", Executors.newCachedExecutor());

   get("/async", deferred("cached", () -> "Success"));
 }

A Deferred object works as a promise too, given you resolve(Object) and reject(Throwable) methods. Examples: As promise using the default executor (execute promise in same/caller thread):

 {
    get("/async", promise(deferred  -> {
      try {
        deferred.resolve(...); // success value
      } catch (Throwable ex) {
        deferred.reject(ex); // error value
      }
    }));
  }

As promise using a custom executor:

 {
    executor(new ForkJoinPool());

    get("/async", promise(deferred  -> {
      try {
        deferred.resolve(...); // success value
      } catch (Throwable ex) {
        deferred.reject(ex); // error value
      }
    }));
  }

As promise using an alternative executor:

 {
    executor(new ForkJoinPool());

    executor("cached", Executors.newCachedExecutor());

    get("/async", promise("cached", deferred  -> {
      try {
        deferred.resolve(...); // success value
      } catch (Throwable ex) {
        deferred.reject(ex); // error value
      }
    }));
  }

Since:: 0.10.0
Author:: edgar

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Deferred.Handler` A deferred handler.
`static interface`	`Deferred.Initializer` Deferred initializer with `Request` access, useful to provide a more functional API.
`static interface`	`Deferred.Initializer0` Deferred initializer, useful to provide a more functional API.

Constructor Summary

Constructors
Constructor and Description
`Deferred()` Creates a new `Deferred`.
`Deferred(Deferred.Initializer initializer)` Creates a new `Deferred` with an initializer.
`Deferred(Deferred.Initializer0 initializer)` Creates a new `Deferred` with an initializer.
`Deferred(String executor, Deferred.Initializer initializer)` Creates a new `Deferred` with an initializer.
`Deferred(String executor, Deferred.Initializer0 initializer)` Creates a new `Deferred` with an initializer.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`String`	`callerThread()` Name of the caller thread (thread that creates this deferred object).
`static Deferred`	`deferred(Route.OneArgHandler handler)` Functional version of `Deferred(Initializer)`.
`static Deferred`	`deferred(Route.ZeroArgHandler handler)` Functional version of `Deferred(Initializer)`.
`static Deferred`	`deferred(String executor, Route.OneArgHandler handler)` Functional version of `Deferred(Initializer)`.
`static Deferred`	`deferred(String executor, Route.ZeroArgHandler handler)` Functional version of `Deferred(Initializer)`.
`Optional<String>`	`executor()` Get an executor to run this deferred result.
`void`	`handler(Request req, Deferred.Handler handler)` Setup a handler for this deferred.
`void`	`reject(Throwable cause)` Resolve the deferred with an error and handle it.
`void`	`resolve(Object value)` Resolve the deferred value and handle it.
`Result`	`set(Object value)` `resolve(Object)` or `reject(Throwable)` the given value.

Methods inherited from class org.jooby.Result
get, get, header, header, header, headers, ifGet, ifGet, status, status, status, type, type, type, when, when

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

- Constructor Detail
  - Deferred
```
public Deferred(String executor,
                Deferred.Initializer0 initializer)
```
    Creates a new Deferred with an initializer.
    
    Parameters:
    
    executor - Executor to use.
    
    initializer - An initializer.
  - Deferred
```
public Deferred(Deferred.Initializer0 initializer)
```
    Creates a new Deferred with an initializer.
    
    Parameters:
    
    initializer - An initializer.
  - Deferred
```
public Deferred(Deferred.Initializer initializer)
```
    Creates a new Deferred with an initializer.
    
    Parameters:
    
    initializer - An initializer.
  - Deferred
```
public Deferred(@Nullable
                String executor,
                Deferred.Initializer initializer)
```
    Creates a new Deferred with an initializer.
    
    Parameters:
    
    executor - Executor to use.
    
    initializer - An initializer.
  - Deferred
```
public Deferred()
```
    Creates a new Deferred.
- Method Detail
  - set
```
@Nonnull
public Result set(Object value)
```
    resolve(Object) or reject(Throwable) the given value.
    
    Overrides:
    
    set in class Result
    
    Parameters:
    
    value - Resolved value.
    
    Returns:
    
    This content.
  - executor
```
@Nonnull
public Optional<String> executor()
```
    Get an executor to run this deferred result. If the executor is present, then it will be use it to execute the deferred object. Otherwise it will use the global/application executor.
    
    Returns:
    
    Executor to use or fallback to global/application executor.
  - callerThread
```
@Nonnull
public String callerThread()
```
    Name of the caller thread (thread that creates this deferred object).
    
    Returns:
    
    Name of the caller thread (thread that creates this deferred object).
  - resolve
```
public void resolve(@Nullable
                    Object value)
```
    Resolve the deferred value and handle it. This method will send the response to a client and cleanup and close all the resources.
    
    Parameters:
    
    value - A value for this deferred.
  - reject
```
public void reject(Throwable cause)
```
    Resolve the deferred with an error and handle it. This method will handle the given exception, send the response to a client and cleanup and close all the resources.
    
    Parameters:
    
    cause - A value for this deferred.
  - handler
```
public void handler(Request req,
                    Deferred.Handler handler)
             throws Exception
```
    Setup a handler for this deferred. Application code should never call this method: INTERNAL USE ONLY.
    
    Parameters:
    
    req - Current request.
    
    handler - A response handler.
    
    Throws:
    
    Exception - If initializer fails to start.
  - deferred
```
@Nonnull
public static Deferred deferred(Route.OneArgHandler handler)
```
    Functional version of Deferred(Initializer). Using the default executor (current thread):
```
 {
   get("/fork", deferred(req -> {
     return req.param("value").value();
   }));
 }
 
```
    Using a custom executor:
```
 {
   executor(new ForkJoinPool());

   get("/fork", deferred(req -> {
     return req.param("value").value();
   }));
 }
 
```
    This handler automatically resolve(Object) or reject(Throwable) a route handler response.
    Parameters:
    
    handler - Application block.
    
    Returns:
    
    A new deferred handler.
  - deferred
```
@Nonnull
public static Deferred deferred(Route.ZeroArgHandler handler)
```
    Functional version of Deferred(Initializer). Using the default executor (current thread):
```
 {
   get("/fork", deferred(() -> {
     return req.param("value").value();
   }));
 }
 
```
    Using a custom executor:
```
 {
   executor(new ForkJoinPool());

   get("/fork", deferred(() -> {
     return req.param("value").value();
   }));
 }
 
```
    This handler automatically resolve(Object) or reject(Throwable) a route handler response.
    Parameters:
    
    handler - Application block.
    
    Returns:
    
    A new deferred.
  - deferred
```
@Nonnull
public static Deferred deferred(String executor,
                                         Route.ZeroArgHandler handler)
```
    Functional version of Deferred(Initializer). To use ideally with one or more Executor:
```
 {
   executor("cached", Executors.newCachedExecutor());

   get("/fork", deferred("cached", () -> {
     return "OK";
   }));
 }
 
```
    This handler automatically resolve(Object) or reject(Throwable) a route handler response.
    Parameters:
    
    executor - Executor to run the deferred.
    
    handler - Application block.
    
    Returns:
    
    A new deferred handler.
  - deferred
```
@Nonnull
public static Deferred deferred(String executor,
                                         Route.OneArgHandler handler)
```
    Functional version of Deferred(Initializer). To use ideally with one or more Executor:
```
 {
   executor("cached", Executors.newCachedExecutor());

   get("/fork", deferred("cached", req -> {
     return req.param("value").value();
   }));
 }
 
```
    This handler automatically resolve(Object) or reject(Throwable) a route handler response.
    Parameters:
    
    executor - Executor to run the deferred.
    
    handler - Application block.
    
    Returns:
    
    A new deferred handler.

Class Deferred

async request processing

usage

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class org.jooby.Result

Methods inherited from class java.lang.Object

Constructor Detail

Deferred

Deferred

Deferred

Deferred

Deferred

Method Detail

set

executor

callerThread

resolve

reject

handler

deferred

deferred

deferred

deferred