org.apache.flink.statefun.sdk

Interface Context

All Known Subinterfaces:

ApplyingContext, InternalContext

public interface Context

Provides context for a single StatefulFunction invocation.

The invocation's context may be used to obtain the Address of itself or the calling function (if the function was invoked by another function), or used to invoke other functions (including itself) and to send messages to egresses.

Method Summary

Modifier and Type	Method and Description
Address	caller() Returns the Address of the invoking function.
void	cancelDelayedMessage(java.lang.String cancellationToken) Cancel a delayed message (a message that was send via sendAfter(Duration, Address, Object, String)).
Metrics	metrics()
<M,T> void	registerAsyncOperation(M metadata, java.util.concurrent.CompletableFuture<T> future) Registers an asynchronous operation.
default void	reply(java.lang.Object message) Invokes the calling function of the current invocation under context.
Address	self() Returns the Address of the invoked function.
void	send(Address to, java.lang.Object message) Invokes another function with an input, identified by the target function's Address.
<T> void	send(EgressIdentifier<T> egress, T message) Sends an output to an egress, identified by the egress' EgressIdentifier.
default void	send(FunctionType functionType, java.lang.String id, java.lang.Object message) Invokes another function with an input, identified by the target function's FunctionType and unique id.
void	sendAfter(java.time.Duration delay, Address to, java.lang.Object message) Invokes another function with an input, identified by the target function's Address, after a given delay.
void	sendAfter(java.time.Duration delay, Address to, java.lang.Object message, java.lang.String cancellationToken) Invokes another function with an input (associated with a cancellationToken), identified by the target function's Address, after a given delay.
default void	sendAfter(java.time.Duration delay, FunctionType functionType, java.lang.String id, java.lang.Object message) Invokes another function with an input, identified by the target function's FunctionType and unique id.

Method Detail

self

Address self()

Returns the Address of the invoked function.

Returns:

the invoked function's own address.

caller

Address caller()

Returns the Address of the invoking function. This is null if the function under context was not invoked by another function.

Returns:

the address of the invoking function; null if the function under context was not invoked by another function.

send

void send(Address to,
          java.lang.Object message)

Invokes another function with an input, identified by the target function's Address.

Parameters:

to - the target function's address.

message - the input to provide for the invocation.

send

<T> void send(EgressIdentifier<T> egress,
              T message)

Sends an output to an egress, identified by the egress' EgressIdentifier.

Type Parameters:

T - type of the inputs that the target egress consumes

Parameters:

egress - the target egress' identifier

message - the output to send

sendAfter

void sendAfter(java.time.Duration delay,
               Address to,
               java.lang.Object message)

Invokes another function with an input, identified by the target function's Address, after a given delay.

Parameters:

delay - the amount of delay before invoking the target function. Value needs to be >= 0.

to - the target function's address.

message - the input to provide for the delayed invocation.

sendAfter

void sendAfter(java.time.Duration delay,
               Address to,
               java.lang.Object message,
               java.lang.String cancellationToken)

Invokes another function with an input (associated with a cancellationToken), identified by the target function's Address, after a given delay.

Providing an id to a message, allows "unsending" this message later. (cancelDelayedMessage(String)).

Parameters:

delay - the amount of delay before invoking the target function. Value needs to be >= 0.

to - the target function's address.

message - the input to provide for the delayed invocation.

cancellationToken - the non-empty, non-null, unique token to attach to this message, to be used for message cancellation. (see cancelDelayedMessage(String).)

cancelDelayedMessage

void cancelDelayedMessage(java.lang.String cancellationToken)

Cancel a delayed message (a message that was send via sendAfter(Duration, Address, Object, String)).

NOTE: this is a best-effort operation, since the message might have been already delivered. If the message was delivered, this is a no-op operation.

Parameters:

cancellationToken - the id of the message to un-send.

send

default void send(FunctionType functionType,
                  java.lang.String id,
                  java.lang.Object message)

Invokes another function with an input, identified by the target function's FunctionType and unique id.

Parameters:

functionType - the target function's type.

id - the target function's id within its type.

message - the input to provide for the invocation.

sendAfter

default void sendAfter(java.time.Duration delay,
                       FunctionType functionType,
                       java.lang.String id,
                       java.lang.Object message)

Invokes another function with an input, identified by the target function's FunctionType and unique id.

Parameters:

delay - the amount of delay before invoking the target function. Value needs to be >= 0.

functionType - the target function's type.

id - the target function's id within its type.

message - the input to provide for the delayed invocation.

reply

default void reply(java.lang.Object message)

Invokes the calling function of the current invocation under context. This has the same effect as calling send(Address, Object) with the address obtained from caller(), and will not work if the current function was not invoked by another function.

Parameters:

message - the input to provide to the replying invocation.

registerAsyncOperation

<M,T> void registerAsyncOperation(M metadata,
                                  java.util.concurrent.CompletableFuture<T> future)

Registers an asynchronous operation.

Register an asynchronous operation represented by a future, and associated with metadata.

The runtime would invoke (at some time in the future) the currently executing stateful function with a AsyncOperationResult argument, that represents the completion of that asynchronous operation.

If the supplied future was completed successfully, then the result can be obtained via AsyncOperationResult.value(). If it is completed exceptionally, then the failure cause can be obtain via AsyncOperationResult.throwable().

Please note that if, for some reason, the processes executing the stateful had fail, the status of the asynchronous operation is unknown (it might have succeeded or failed before the stateful function was notified). In that case the status of the AsyncOperationResult would be UNKNOWN.

metadata - Each asynchronous operation is also associated with a metadata object that can be used to correlate multiple in flight asynchronous operations. This object can be obtained via AsyncOperationResult.metadata(). This object would be serialized with the same serializer used to serializer the messages.

Type Parameters:

M - metadata type.

T - value type.

Parameters:

metadata - a meta data object to associated with this in flight async operation.

future - the CompletableFuture that represents the async operation.

metrics

Metrics metrics()

Returns:

a function type scoped metrics.