What is the difference between reply, asyncEffect, asyncReply, and forward method?

I am trying to call the Kalix components from Kalix Action. I used different options in the test, including:

  • effects().reply()
  • effects().forward()
  • effects().asyncReply()
  • effects().asyncEffect()

During my test, it seems that all four methods get the similar blocking behaviours. Is there any meaning behind the scene (e.g. thread)? and which option should we use in which scenario?

Then, if my application has the following typical logic, where should I put in the Kalix entity implementation (e.g. command handler, event handler, action)?

  • request validation
  • request data mapping
  • response data mapping
  • business logic with orchestration to other backend
  • other backend call using client
  • error handling on backend client

Hi Faichun,

this is covered in the docs but I don’t think we have a single page giving an overview.

Here’s a quick summary:

  • effects().reply() - replies immediately with the given value
  • effects().forward() - passes the request, or possibly a transformed request to another component and the reply to the client will be the direct reply from that call, the method forwarded to must have the same reply message type as the one forwarding it.
  • effects().asyncReply() - allows an arbitrary Java Completion Stage/Scala Future async completion be sent, more expensive than forward but allows transforming a reply message type
  • effects().asyncEffect() - allows a Java Completion Stage/Scala Future async result to not only reply but also the other types of effects, like fail for example

Entities cannot do async effects because that would break their boundary of consistency where a command can safely be validated against the current state of the entity instance and make business decisions knowing that the state does not change until the state change/events from that decision has been stored.

This means that orchestration and interactions with other components currently needs to go into Actions, more or less described here in the docs: Actions as Controllers :: Kalix Documentation

I hope this helps.


Thank you so much. This summary makes me more clear. :sweat_smile: