com.fnproject.fn.api.flow

Interface Flow

All Superinterfaces:

Serializable

public interface Flow
extends Serializable

A reference to the Flow object attached to the current invocation context.

This provides an API that can be used to trigger asynchronous work within a flow.

The methods return FlowFuture objects that act as the root of an asynchronous computation

See Also:

for details of how to chain subsequent work onto these initial methods.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Flow.FlowState Represents the possible end states of a Flow object, i.e.

Method Summary

Modifier and Type	Method and Description
Flow	addTerminationHook(Flows.SerConsumer<Flow.FlowState> hook) Adds a termination hook that will be executed upon completion of the whole flow; the provided hook will received input according to how the flow terminated.
FlowFuture<Void>	allOf(FlowFuture<?>... flowFutures) Wait for all a list of tasks to complete
FlowFuture<Object>	anyOf(FlowFuture<?>... flowFutures) Wait for any of a list of tasks to complete
<T> FlowFuture<T>	completedValue(T value) Create a completed future for a specified value.
<T> FlowFuture<T>	createFlowFuture() Create an uncompleted future
FlowFuture<Void>	delay(long i, TimeUnit tu) Create a future that completes successfully after a specified delay
<T> FlowFuture<T>	failedFuture(Throwable ex) Create a completed future that propagates a failed value
default FlowFuture<HttpResponse>	invokeFunction(String functionId, HttpMethod method) Invoke a function by ID with no headers
default FlowFuture<HttpResponse>	invokeFunction(String functionId, HttpMethod method, com.fnproject.fn.api.Headers headers) Invoke a function by ID with headers and an empty body
FlowFuture<HttpResponse>	invokeFunction(String functionId, HttpMethod method, com.fnproject.fn.api.Headers headers, byte[] data) Invoke a fn function and yield the result
<U> FlowFuture<HttpResponse>	invokeFunction(String functionId, HttpMethod method, com.fnproject.fn.api.Headers headers, U input) Invoke a function by ID using input and output coercion and a specified method and headers
<T extends Serializable,U> FlowFuture<T>	invokeFunction(String functionId, HttpMethod method, com.fnproject.fn.api.Headers headers, U input, Class<T> responseType) Invoke a function by ID using input and output coercion and a specified method and headers
default <U> FlowFuture<HttpResponse>	invokeFunction(String functionId, U input) Invoke a function by ID using input and output coercion, default method (POST) and no response type
default <T extends Serializable,U> FlowFuture<T>	invokeFunction(String functionId, U input, Class<T> responseType) Invoke a function by ID using input and output coercion
<T> FlowFuture<T>	supply(Flows.SerCallable<T> c) Invoke an asynchronous task that yields a value
FlowFuture<Void>	supply(Flows.SerRunnable runnable) Invoke an asynchronous task that does not yield a value

Method Detail

invokeFunction

FlowFuture<HttpResponse> invokeFunction(String functionId,
                                        HttpMethod method,
                                        com.fnproject.fn.api.Headers headers,
                                        byte[] data)

Invoke a fn function and yield the result

When this function is called, the flow server will send a request with the body to the given function ID within the fn and provide a future that can chain on the response of the function.

         Flow fl = Flows.currentFlow();
         fl.invokeFunction("myapp/myfn", HttpMethod.GET, Headers.emptyHeaders(), "input".getBytes())
           .thenAccept((result)->{
               System.err.println("Result was " + new String(result));
           });
 <p>
 

Function IDs should be of the form "APPID/path/in/app" (without leading slash) where APPID may either be a named application or ".", indicating the appID of the current (calling) function.

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

method - HTTP method to invoke function

headers - Headers to add to the HTTP request representing the function invocation

data - input data to function as a byte array -

Returns:

a future which completes normally if the function succeeded and fails if it fails

invokeFunction

default FlowFuture<HttpResponse> invokeFunction(String functionId,
                                                HttpMethod method,
                                                com.fnproject.fn.api.Headers headers)

Invoke a function by ID with headers and an empty body

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

method - HTTP method to invoke function

headers - Headers to add to the HTTP request representing the function invocation

Returns:

a future which completes normally if the function succeeded and fails if it fails

See Also:

invokeFunction(String, HttpMethod, Headers, byte[])

invokeFunction

default <T extends Serializable,U> FlowFuture<T> invokeFunction(String functionId,
                                                                U input,
                                                                Class<T> responseType)

Invoke a function by ID using input and output coercion

This currently only maps to JSON via the default JSON mapper in the FDK

Type Parameters:

T - The Response type

U - The Input type of the function

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

input - The input object to send to the function input

responseType - The expected response type of the target function

Returns:

a flow future that completes with the result of the function, or an error if the function invocation failed

Throws:

IllegalArgumentException - if the input cannot be coerced to the callA

invokeFunction

<T extends Serializable,U> FlowFuture<T> invokeFunction(String functionId,
                                                        HttpMethod method,
                                                        com.fnproject.fn.api.Headers headers,
                                                        U input,
                                                        Class<T> responseType)

Invoke a function by ID using input and output coercion and a specified method and headers

This currently only maps to JSON via the default JSON mapper in the FDK

Type Parameters:

T - The Response type

U - The Input type of the function

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

method - the HTTP method to use for this call

headers - additional HTTP headers to pass to this function -

input - The input object to send to the function input

responseType - The expected response type of the target function

Returns:

a flow future that completes with the result of the function, or an error if the function invocation failed

Throws:

IllegalArgumentException - if the input cannot be coerced to the call

invokeFunction

default <U> FlowFuture<HttpResponse> invokeFunction(String functionId,
                                                    U input)

Invoke a function by ID using input and output coercion, default method (POST) and no response type

Returns a future that completes with the HttpResponse of the function on success if the function returns a successful http response, and completes with an FunctionInvocationException if the function invocation fails with a non-succesful http status

This currently only maps to JSON via the default JSON mapper in the FDK

Type Parameters:

U - The Input type of the function

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

input - The input object to send to the function input

Returns:

a flow future that completes with the result of the function, or an error if the function invocation failed

Throws:

IllegalArgumentException - if the input cannot be coerced to the call

invokeFunction

<U> FlowFuture<HttpResponse> invokeFunction(String functionId,
                                            HttpMethod method,
                                            com.fnproject.fn.api.Headers headers,
                                            U input)

Invoke a function by ID using input and output coercion and a specified method and headers

Returns a future that completes with the HttpResponse of the function on success if the function returns a successful http response, and completes with an FunctionInvocationException if the function invocation fails with a non-succesful http status

This currently only maps to JSON via the default JSON mapper in the FDK

Type Parameters:

U - The Input type of the function

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

method - the HTTP method to use for this call

headers - additional HTTP headers to pass to this function -

input - The input object to send to the function input

Returns:

a flow future that completes with the result of the function, or an error if the function invocation failed

Throws:

IllegalArgumentException - if the input cannot be coerced to the call

invokeFunction

default FlowFuture<HttpResponse> invokeFunction(String functionId,
                                                HttpMethod method)

Invoke a function by ID with no headers

Parameters:

functionId - Function ID of function to invoke - this should be the function ID returned by `fn inspect function appName fnName`

method - HTTP method to invoke function

Returns:

a future which completes normally if the function succeeded and fails if it fails

See Also:

invokeFunction(String, HttpMethod, Headers, byte[])

supply

<T> FlowFuture<T> supply(Flows.SerCallable<T> c)

Invoke an asynchronous task that yields a value

         Flow fl = Flows.currentFlow();
         fl.supply(()->{
            int someVal
            someVal = ... // some long running computation.
            return someVal;
         }).thenAccept((val)->{
               System.err.println("Result was " + val);
         });
 

Type Parameters:

T - the type of the future

Parameters:

c - a callable value to invoke via a flow

Returns:

a com.fnproject.fn.api.flow.FlowFuture on

supply

FlowFuture<Void> supply(Flows.SerRunnable runnable)

Invoke an asynchronous task that does not yield a value

         Flow fl = Flows.currentFlow();
         fl.supply(()->{
            System.err.println("I have run asynchronously");
         });
 <p>
 

Parameters:

runnable - a serializable runnable object

Returns:

a completable future that yields when the runnable completes

delay

FlowFuture<Void> delay(long i,
                       TimeUnit tu)

Create a future that completes successfully after a specified delay

         Flow fl = Flows.currentFlow();
         fl.delay(5,TimeUnit.Seconds)
            .thenAccept((ignored)->{
               System.err.println("I have run asynchronously");
            });
 

Parameters:

i - amount to delay

tu - time unit

Returns:

a completable future that completes when the delay expires

completedValue

<T> FlowFuture<T> completedValue(T value)

Create a completed future for a specified value.

         Flow fl = Flows.currentFlow();
         fl.delay(5,TimeUnit.Seconds)
            .thenCompose((ignored)->{
                if(shouldRunFn){
                    return rt.invokeAsync("testapp/testfn","input".getBytes()).thenApply(String::new);
                }else{
                    return rt.completedValue("some value");
                }
            })
            .thenAccept((x)->System.err.println("Result " + x));
 

Type Parameters:

T - the type of the future value

Parameters:

value - a value to assign to the futures

Returns:

a completed flow future based on the specified value

failedFuture

<T> FlowFuture<T> failedFuture(Throwable ex)

Create a completed future that propagates a failed value

         Flow fl = Flows.currentFlow();
         fl.delay(5,TimeUnit.Seconds)
            .thenCompose((ignored)->{
                if(shouldRunFn){
                    return rt.invokeAsync("testapp/testfn","input".getBytes()).thenApply(String::new);
                }else{
                    return rt.failedFuture(new RuntimeException("Immediate Failure"));
                }
            })
            .whenComplete((x,t)->{
                if (t !=null){
                   // Will print "Immediate Failure";
                   System.err.println("error in flow", t.getMessage());
                }else{
                   System.err.println("Success! , x);
                }
            });
 

Type Parameters:

T - the type of the future

Parameters:

ex - an exception to publish to the future

Returns:

a future that always completes with the specified exception

createFlowFuture

<T> FlowFuture<T> createFlowFuture()

Create an uncompleted future

Type Parameters:

T - the type of the future

Returns:

a flow future that can only be completed via FlowFuture.complete(Object) or FlowFuture.completeExceptionally(Throwable)

allOf

FlowFuture<Void> allOf(FlowFuture<?>... flowFutures)

Wait for all a list of tasks to complete

         Flow fl = Flows.currentFlow();
         FlowFuture<Integer> f1 = fl.delay(5, TimeUnit.SECONDS).thenApply((ignored)-> 10);
         FlowFuture<String> f2 = fl.delay(3, TimeUnit.SECONDS).thenApply((ignored)-> "Hello");
         FlowFuture<Void> f3 = fl.delay(1, TimeUnit.SECONDS);
         fl.allOf(f1,f2,f3)
            .thenAccept((ignored)->{
            System.err.println("all done");
         });
 

The resulting future will complete successfully if all provided futures complete successfully and will complete exception as soon as any of the provided futures do.

Parameters:

flowFutures - a list of futures to aggregate, must contain at least one future.

Returns:

a future that completes when all futures are complete and fails when any one fails

anyOf

FlowFuture<Object> anyOf(FlowFuture<?>... flowFutures)

Wait for any of a list of tasks to complete

         Flow fl = Flows.currentFlow();
         FlowFuture<Integer> f1 = fl.delay(5, TimeUnit.SECONDS).thenApply((ignored)-> 10);
         FlowFuture<String> f2 = fl.delay(3, TimeUnit.SECONDS).thenApply((ignored)-> "Hello");
         FlowFuture<Void> f3 = fl.supply(()->throw new RuntimeException("err"));
         fl.anyOf(f1,f2,f3)
            .thenAccept((ignored)->{
            System.err.println("at least one done");
         });
 

The resulting future will complete successfully as soon as any of the provided futures completes successfully and only completes exceptionally if all provided futures do.

Parameters:

flowFutures - a list of futures to aggregate, must contain at least one future

Returns:

a future that completes when all futures are complete and fails when any one fails

addTerminationHook

Flow addTerminationHook(Flows.SerConsumer<Flow.FlowState> hook)

Adds a termination hook that will be executed upon completion of the whole flow; the provided hook will received input according to how the flow terminated.

The framework will make a best effort attempt to execute the termination hooks in LIFO order with respect to when they were added.

         Flow fl = Flows.currentFlow();
         fl.addTerminationHook( (ignored) -> { System.err.println("Flow terminated"); } )
           .addTerminationHook( (endState) -> { System.err.println("End state was " + endState.asText()); } );
 

This example will first run a stage that prints the end state, and then run a stage that prints 'Flow terminated'.

Parameters:

hook - The code to execute

Returns:

This same Flow, so that calls can be chained