Interface Client

All Known Implementing Classes:
BaseClient, JdkClient
public interface Client

  • Method Details

    • callAsync

      <Req,Res> CompletableFuture<Response<Res>> callAsync(Request<Req,Res> request)
      Future version of call(Request)
      See Also:

    • call

      default <Req,Res> Response<Res> call(Request<Req,Res> request) throws IngressException
      Call a service and wait for the response.
      Throws:
      IngressException

    • sendAsync

      default <Req,Res> CompletableFuture<SendResponse<Res>> sendAsync(Request<Req,Res> request)
      Future version of send(Request)
      See Also:

    • send

      default <Req,Res> SendResponse<Res> send(Request<Req,Res> request) throws IngressException
      Send a request to a service without waiting for the response.
      Throws:
      IngressException

    • sendAsync

      <Req,Res> CompletableFuture<SendResponse<Res>> sendAsync(Request<Req,Res> request, @Nullable Duration delay)
      Future version of send(Request, Duration)
      See Also:

    • send

      default <Req,Res> SendResponse<Res> send(Request<Req,Res> request, @Nullable Duration delay) throws IngressException
      Send a request to a service without waiting for the response, optionally providing an execution delay to wait for.
      Throws:
      IngressException

    • submitAsync

      default <Req,Res> CompletableFuture<SendResponse<Res>> submitAsync(WorkflowRequest<Req,Res> request)
      Future version of submit(WorkflowRequest)
      See Also:

    • submit

      default <Req,Res> SendResponse<Res> submit(WorkflowRequest<Req,Res> request) throws IngressException
      Submit a workflow.
      Throws:
      IngressException

    • submitAsync

      default <Req,Res> CompletableFuture<SendResponse<Res>> submitAsync(WorkflowRequest<Req,Res> request, @Nullable Duration delay)
      Future version of submit(WorkflowRequest, Duration)
      See Also:

    • submit

      default <Req,Res> SendResponse<Res> submit(WorkflowRequest<Req,Res> request, @Nullable Duration delay) throws IngressException
      Submit a workflow, optionally providing an execution delay to wait for.
      Throws:
      IngressException

    • awakeableHandle

      Client.AwakeableHandle awakeableHandle(String id)
      Create a new Client.AwakeableHandle for the provided identifier. You can use it to Client.AwakeableHandle.resolve(TypeTag, Object) or Client.AwakeableHandle.reject(String) an Awakeable from the ingress.

    • invocationHandle

      <Res> Client.InvocationHandle<Res> invocationHandle(String invocationId, TypeTag<Res> resTypeTag)
      Create a new Client.InvocationHandle for the provided invocation identifier.
      Parameters:
      invocationId - the invocation identifier
      resTypeTag - type tag used to deserialize the invocation result
      Returns:
      the invocation handle

    • invocationHandle

      default <Res> Client.InvocationHandle<Res> invocationHandle(String invocationId, Class<Res> clazz)
      Create a new Client.InvocationHandle for the provided invocation identifier.
      Parameters:
      invocationId - the invocation identifier
      clazz - used to deserialize the invocation result
      Returns:
      the invocation handle

    • idempotentInvocationHandle

      <Res> Client.IdempotentInvocationHandle<Res> idempotentInvocationHandle(Target target, String idempotencyKey, TypeTag<Res> resTypeTag)
      Create a new Client.IdempotentInvocationHandle for the provided target and idempotency key.
      Parameters:
      target - the target service/method
      idempotencyKey - the idempotency key
      resTypeTag - type tag used to deserialize the invocation result
      Returns:
      the idempotent invocation handle

    • idempotentInvocationHandle

      default <Res> Client.IdempotentInvocationHandle<Res> idempotentInvocationHandle(Target target, String idempotencyKey, Class<Res> clazz)
      Create a new Client.IdempotentInvocationHandle for the provided target and idempotency key.
      Parameters:
      target - the target service/method
      idempotencyKey - the idempotency key
      clazz - used to deserialize the invocation result
      Returns:
      the idempotent invocation handle

    • workflowHandle

      <Res> Client.WorkflowHandle<Res> workflowHandle(String workflowName, String workflowId, TypeTag<Res> resTypeTag)
      Create a new Client.WorkflowHandle for the provided workflow name and identifier.
      Parameters:
      workflowName - the workflow name
      workflowId - the workflow identifier
      resTypeTag - type tag used to deserialize the invocation result
      Returns:
      the workflow handle

    • workflowHandle

      default <Res> Client.WorkflowHandle<Res> workflowHandle(String workflowName, String workflowId, Class<Res> clazz)
      Create a new Client.WorkflowHandle for the provided workflow name and identifier.
      Parameters:
      workflowName - the workflow name
      workflowId - the workflow identifier
      clazz - used to deserialize the workflow result
      Returns:
      the workflow handle

    • scope

      @Experimental default ScopedClient scope(String scopeKey)
      PREVIEW: Returns a ScopedClient that routes all outgoing calls within the given scope.

      NOTE: This API is in preview and is not enabled by default. To use it in restate-server 1.7, enable the flow control and protocol v7 experimental features, via RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true and RESTATE_EXPERIMENTAL_ENABLE_VQUEUES=true. These can be enabled only on new clusters, for more info check out https://docs.restate.dev/services/flow-control#enabling-flow-control. If these experimental features aren't enabled, the call fails with a retryable error and keeps retrying until they are.

      A scope is a sub-grouping of resources (invocations, virtual object instances, workflow instances, concurrency limits) within the Restate cluster. It becomes part of the target identity tuple:

      • scope, service, handler, idempotencyKey?
      • scope, virtualObject, objectKey, handler, idempotencyKey?
      • scope, workflow, workflowKey, handler

      Under the hood, the scope contributes to the partition key, so all resources in a scope get co-located by the restate-server.

      Omitting the scope (i.e. using the regular service(Class) / workflow(Class, String) methods) is equivalent to calling with no scope, which is the existing behavior.

      The scope key must consist only of [a-zA-Z0-9_.-] characters, with 1 <= length <= 36 chars. 

      Client client = Client.connect("http://localhost:8080");

// Route a call into a named scope
client.scope("tenant-123").service(MyService.class).process(payload);

// Idempotency keys are scoped — "req-1" in "tenant-123" is distinct from "req-1" in "tenant-456"
client.scope("tenant-123").serviceHandle(MyService.class)
    .call(MyService::process, payload, InvocationOptions.idempotencyKey("req-1").build());

// Combine with a limit key to enforce per-scope concurrency limits
client.scope("tenant-123").workflowHandle(MyWorkflow.class, "wf-key")
    .call(MyWorkflow::run, input, InvocationOptions.limitKey("api-key/user42").build());
      Parameters:
      scopeKey - the scope identifier
      Returns:
      a ScopedClient
      See Also:

    • service

      default <SVC> SVC service(Class<SVC> clazz)
      Simple API to invoke a Restate service from the ingress.

      Create a proxy client that allows calling service methods directly and synchronously, returning just the output (not wrapped in Response). This is the recommended approach for straightforward request-response interactions. 

      Client client = Client.connect("http://localhost:8080");

var greeterProxy = client.service(Greeter.class);
GreetingResponse output = greeterProxy.greet(new Greeting("Alice"));

      For advanced use cases requiring asynchronous request handling, access to Response metadata, or invocation options (such as idempotency keys), use serviceHandle(Class) instead.

      Parameters:
      clazz - the service class annotated with Service
      Returns:
      a proxy client to invoke the service

    • serviceHandle

      default <SVC> ClientServiceHandle<SVC> serviceHandle(Class<SVC> clazz)
      Advanced API to invoke a Restate service from the ingress with full control.

      Create a handle that provides advanced invocation capabilities including:

      • Async request handling with CompletableFuture
      • Invocation options such as idempotency keys
      • Fire-and-forget requests via send()
      • Access to full Response metadata 
      Client client = Client.connect("http://localhost:8080");

// Use call() with method reference and wait for the result
Response<GreetingResponse> response = client.serviceHandle(Greeter.class)
  .call(Greeter::greet, new Greeting("Alice"));

// Use send() for one-way invocation without waiting
SendResponse<GreetingResponse> sendResponse = client.serviceHandle(Greeter.class)
  .send(Greeter::greet, new Greeting("Alice"));

      For simple synchronous request-response interactions, consider using service(Class) instead.

      Parameters:
      clazz - the service class annotated with Service
      Returns:
      a handle to invoke the service with advanced options

    • virtualObject

      default <SVC> SVC virtualObject(Class<SVC> clazz, String key)
      Simple API to invoke a Restate Virtual Object from the ingress.

      Create a proxy client that allows calling virtual object methods directly and synchronously, returning just the output (not wrapped in Response). This is the recommended approach for straightforward request-response interactions. 

      Client client = Client.connect("http://localhost:8080");

var counterProxy = client.virtualObject(Counter.class, "my-counter");
int count = counterProxy.increment();

      For advanced use cases requiring asynchronous request handling, access to Response metadata, or invocation options (such as idempotency keys), use virtualObjectHandle(Class, String) instead.

      Parameters:
      clazz - the virtual object class annotated with VirtualObject
      key - the key identifying the specific virtual object instance
      Returns:
      a proxy client to invoke the virtual object

    • virtualObjectHandle

      default <SVC> ClientServiceHandle<SVC> virtualObjectHandle(Class<SVC> clazz, String key)
      Advanced API to invoke a Restate Virtual Object from the ingress with full control.

      Create a handle that provides advanced invocation capabilities including:

      • Async request handling with CompletableFuture
      • Invocation options such as idempotency keys
      • Fire-and-forget requests via send()
      • Access to full Response metadata 
      Client client = Client.connect("http://localhost:8080");

// Use call() with method reference and wait for the result
Response<Integer> response = client.virtualObjectHandle(Counter.class, "my-counter")
  .call(Counter::increment);

// Use send() for one-way invocation without waiting
SendResponse<Integer> sendResponse = client.virtualObjectHandle(Counter.class, "my-counter")
  .send(Counter::increment);

      For simple synchronous request-response interactions, consider using virtualObject(Class, String) instead.

      Parameters:
      clazz - the virtual object class annotated with VirtualObject
      key - the key identifying the specific virtual object instance
      Returns:
      a handle to invoke the virtual object with advanced options

    • workflow

      default <SVC> SVC workflow(Class<SVC> clazz, String key)
      Simple API to invoke a Restate Workflow from the ingress.

      Create a proxy client that allows calling workflow methods directly and synchronously, returning just the output (not wrapped in Response). This is the recommended approach for straightforward request-response interactions. 

      Client client = Client.connect("http://localhost:8080");

var workflowProxy = client.workflow(OrderWorkflow.class, "order-123");
OrderResult result = workflowProxy.start(new OrderRequest(...));

      For advanced use cases requiring asynchronous request handling, access to Response metadata, or invocation options (such as idempotency keys), use workflowHandle(Class, String) instead.

      Parameters:
      clazz - the workflow class annotated with Workflow
      key - the key identifying the specific workflow instance
      Returns:
      a proxy client to invoke the workflow

    • workflowHandle

      default <SVC> ClientServiceHandle<SVC> workflowHandle(Class<SVC> clazz, String key)
      Advanced API to invoke a Restate Workflow from the ingress with full control.

      Create a handle that provides advanced invocation capabilities including:

      • Async request handling with CompletableFuture
      • Invocation options such as idempotency keys
      • Fire-and-forget requests via send()
      • Access to full Response metadata 
      Client client = Client.connect("http://localhost:8080");

// Use call() with method reference and wait for the result
Response<OrderResult> response = client.workflowHandle(OrderWorkflow.class, "order-123")
  .call(OrderWorkflow::start, new OrderRequest(...));

// Use send() for one-way invocation without waiting
SendResponse<OrderResult> sendResponse = client.workflowHandle(OrderWorkflow.class, "order-123")
  .send(OrderWorkflow::start, new OrderRequest(...));

      For simple synchronous request-response interactions, consider using workflow(Class, String) instead.

      Parameters:
      clazz - the workflow class annotated with Workflow
      key - the key identifying the specific workflow instance
      Returns:
      a handle to invoke the workflow with advanced options

    • connect

      static Client connect(String baseUri)
      Create a default JDK client.
      Parameters:
      baseUri - uri to connect to.

    • connect

      static Client connect(String baseUri, RequestOptions options)
      Create a default JDK client.
      Parameters:
      baseUri - uri to connect to
      options - default options to use in all the requests.

    • connect

      static Client connect(String baseUri, SerdeFactory serdeFactory)
      Create a default JDK client.
      Parameters:
      baseUri - uri to connect to
      serdeFactory - Serde factory to use. If you're just wrapping this client in a code-generated client, you don't need to provide this parameter.

    • connect

      static Client connect(String baseUri, SerdeFactory serdeFactory, RequestOptions options)
      Create a default JDK client.
      Parameters:
      baseUri - uri to connect to
      serdeFactory - Serde factory to use. If you're just wrapping this client in a code-generated client, you don't need to provide this parameter.
      options - default options to use in all the requests.