Package dev.restate.client

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

    • service

      @Experimental default <SVC> SVC service(Class<SVC> clazz)
      EXPERIMENTAL API: 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

      @Experimental default <SVC> ClientServiceHandle<SVC> serviceHandle(Class<SVC> clazz)
      EXPERIMENTAL API: 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

      @Experimental default <SVC> SVC virtualObject(Class<SVC> clazz, String key)
      EXPERIMENTAL API: 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

      @Experimental default <SVC> ClientServiceHandle<SVC> virtualObjectHandle(Class<SVC> clazz, String key)
      EXPERIMENTAL API: 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

      @Experimental default <SVC> SVC workflow(Class<SVC> clazz, String key)
      EXPERIMENTAL API: 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

      @Experimental default <SVC> ClientServiceHandle<SVC> workflowHandle(Class<SVC> clazz, String key)
      EXPERIMENTAL API: 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.