Usability issue with CRUD entity naming

[rstento]

Using ValueEntity in the .proto file and Entity for the Java implementation creates a usability issue. For Event Sourced entities, the Java annotation is @EventSourcedEntity. And, since the doc already describes how to work with Event Sourced entities, it will be awkward to have to describe how to work with Entity entities, Value entity or Persistent entity would be much easier to explain. This concern is echoed by others:

"This does make it easy to trip over."
"I agree it's rather difficult especially when using different names in different places which has to be addressed in Cloudstate as we adopt it into Akka Serverless."

[sleipnir]

This was discussed during the meeting:

Meeting: 2020-10-27 22:00 UTC
Participants: James Roper, Guy Nouaga, Peter Vlugter

[marcellanz]

To give context, also, it was discussed starting here at some length: #220 (comment) before the meeting @sleipnir mentioned
(the PR with the most comments (>180) so far I think, so don't forget to click show hidden items)

[sleipnir]

Yes, that was a memorable discussion. Many arguments were made and the choice of current names was chosen.
I was curious about how it affects Akka Serverless

[ralphlaude]

@rstento I would be curious to know how Akka Serverless is affected here. What would be your suggestions?

[pvlugter]

Using ValueEntity in the .proto file and Entity for the Java implementation creates a usability issue

I don't think there's a usability issue here. The Cloudstate protocols and other internals are not exposed to the user. The user only works with the Entity API in a language support in this case, they don't use the Cloudstate protocols directly.

[pvlugter]

There's been a lot of discussion on this already. Final decision was that there's Entity — with all the core functionality of the entity concept. Then there's Event Sourced Entity and Replicated Entity (and possibly others) which have specialised behaviour. One thought experiment we did was if the (simple value-based) entity was created first, then it would almost certainly just be called Entity, with later specialised entities for event sourcing or CRDTs being named as they are now. This is similar to other things, such as in Akka there's Actor and then Sharded Actor and Persistent Actor and so on, as specialised variants of an actor. I think the difficulty could just be from our point of view, because we're introducing this simple entity now, after creating event sourced entities — but for the user, they should have the core entity concept and behaviour and the Entity APIs introduced first, and I'd expect this to work well and for it to be a reasonable progression from Entity to Event Sourced Entity.

[rstento]

Sorry to be so late to respond here, just didn't have the bandwidth. I haven't had time to read all of the previous discussions, but plan to. However, I see the logic in @pvlugter's explanation above. It will require a significant rewrite of the Akka Serverless doc but perhaps that is a good thing.

@ralphlaude, the reason this impacts Akka Serverless is that the doc explains how to develop Cloudstate services. However, we are targeting a different audience than Cloudstate, therefore we need to provide additional concepts and hand-holding.

[kikiya]

Have I followed this thread correctly to understand that Entity and Value Entity are the same thing? Value Entity is the "non-specialized" base version? Then there's event sourced and replicated etc? @rstento @pvlugter

[ralphlaude]

@kikiya you have followed correctly. Entity and Value Entity are the same thing. Event sourced entity and replicated entity are some specialized version of Entity.