Remove EventSourcedEntity, #27724

Move utils to construct PersistenceId

* Move from EntityTypeKey to PersistenceId
* Thereby no persistence dependencies in sharding
* Reference documentation PersistenceId and how to use with Sharding
* Add EntityTypeKey to EntityContext to make it "complete"
* One consequence of adding EntityTypeKey to EntityContext is that
  now requires additional message type parameter and then type inference
  for `init` (Entity) breaks down. Solved by using two parameter lists in
  Entity.apply, which is pretty nice anyway since the second parameter is
  a function.
* as bonus the dependency can be removed

akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md

@@ -508,9 +508,6 @@ Akka Typed APIs are still marked as [may change](../common/may-change.md) and a
 made before finalizing the APIs. Compared to Akka 2.5.x the source incompatible changes are:
 
 * `Behaviors.intercept` now takes a factory function for the interceptor.
-* Factory method `Entity.ofPersistentEntity` is renamed to `Entity.ofEventSourcedEntity` in the Java API for Akka Cluster Sharding Typed.
-* New abstract class `EventSourcedEntityWithEnforcedReplies` in Java API for Akka Cluster Sharding Typed and corresponding factory method `Entity.ofEventSourcedEntityWithEnforcedReplies` to ease the creation of `EventSourcedBehavior` with enforced replies.
-* New method `EventSourcedEntity.withEnforcedReplies` added to Scala API to ease the creation of `EventSourcedBehavior` with enforced replies.
 * `ActorSystem.scheduler` previously gave access to the classic `akka.actor.Scheduler` but now returns a typed specific `akka.actor.typed.Scheduler`.
   Additionally `schedule` method has been replaced by `scheduleWithFixedDelay` and `scheduleAtFixedRate`. Actors that needs to schedule tasks should
   prefer `Behaviors.withTimers`.
@@ -539,6 +536,12 @@ made before finalizing the APIs. Compared to Akka 2.5.x the source incompatible
 * `GetDataDeleted` and `UpdateDataDeleted` introduced as described in @ref[DataDeleted](#datadeleted).
 * `SubscribeResponse` introduced in `Subscribe` because the responses can be both `Changed` and `Deleted`.
 * `ReplicationDeleteFailure` renamed to `DeleteFailure`.
+* `EventSourcedEntity` removed in favor using plain `EventSourcedBehavior` because the alternative way was
+  causing more confusion than adding value. Construction of `PersistentId` for the `EventSourcedBehavior` is
+  facilitated by factory methods in `PersistenceId`.
+* `akka.cluster.sharding.typed.scaladsl.Entity.apply` changed to use two parameter lists because the new
+  `EntityContext.entityTypeKey` required additional type parameter that is inferred better with a secondary
+  parameter list.
 * `EventSourcedBehavior.withEnforcedReplies` signature changed. Command is not required to extend `ExpectingReply` anymore. `ExpectingReply` has been removed therefore.  
 
 #### Akka Typed Stream API changes

akka-docs/src/main/paradox/typed/cluster-sharding.md

@@ -89,10 +89,10 @@ Java
 When using sharding entities can be moved to different nodes in the cluster. Persistence can be used to recover the state of
 an actor after it has moved.
 
-Akka Persistence is based on the single-writer principle, for a particular `persitenceId` only one persistent actor
+Akka Persistence is based on the single-writer principle, for a particular `PersistenceId` only one persistent actor
 instance should be active. If multiple instances were to persist events at the same time, the events would be
-interleaved and might not be interpreted correctly on replay. Cluster sharding is typically used together with
-persistence to ensure that there is only one active entity for each `persistenceId` (`entityId`).
+interleaved and might not be interpreted correctly on replay. Cluster Sharding is typically used together with
+persistence to ensure that there is only one active entity for each `PersistenceId` (`entityId`).
 
 Here is an example of a persistent actor that is used as a sharded entity:
 
@@ -102,11 +102,6 @@ Scala
 Java
 :  @@snip [HelloWorldPersistentEntityExample.java](/akka-cluster-sharding-typed/src/test/java/jdocs/akka/cluster/sharding/typed/HelloWorldPersistentEntityExample.java) { #persistent-entity-import #persistent-entity }
 
-Note that `EventSourcedEntity` is used in this example. Any `Behavior` can be used as a sharded entity actor,
-but the combination of sharding and persistent actors is very common and therefore the `EventSourcedEntity`
-@scala[factory]@java[class] is provided as convenience. It selects the `persistenceId` automatically from
-the `EntityTypeKey` and `entityId` @java[constructor] parameters by using `EntityTypeKey.persistenceIdFrom`.
-
 To initialize and use the entity:
 
 Scala
@@ -115,6 +110,11 @@ Scala
 Java
 :  @@snip [HelloWorldPersistentEntityExample.java](/akka-cluster-sharding-typed/src/test/java/jdocs/akka/cluster/sharding/typed/HelloWorldPersistentEntityExample.java) { #persistent-entity-usage-import #persistent-entity-usage }
 
+Note how an unique @apidoc[akka.persistence.typed.PersistenceId] can be constructed from the `EntityTypeKey` and the `entityId`
+provided by the @apidoc[typed.*.EntityContext] in the factory function for the `Behavior`. This is a typical way
+of defining the `PersistenceId` but formats are possible, as described in the
+@ref:[PersistenceId section](persistence.md#persistenceid).
+
 Sending messages to persistent entities is the same as if the entity wasn't persistent. The only difference is
 when an entity is moved the state will be restored. In the above example @ref:[ask](interaction-patterns.md#outside-ask)
 is used but `tell` or any of the other @ref:[Interaction Patterns](interaction-patterns.md) can be used.

akka-docs/src/main/paradox/typed/from-classic.md

@@ -380,7 +380,7 @@ Links to reference documentation:
 The correspondence of the classic `PersistentActor` is @scala[`akka.persistence.typed.scaladsl.EventSourcedBehavior`]@java[`akka.persistence.typed.javadsl.EventSourcedBehavior`].
 
 The Typed API is much more guided to facilitate event sourcing best practises. It also has tighter integration with
-Cluster Sharding via `EventSourcedEntity`.
+Cluster Sharding.
 
 Links to reference documentation:
 

akka-docs/src/main/paradox/typed/persistence.md

@@ -58,6 +58,36 @@ based on the events.
 
 Next we'll discuss each of these in detail.
 
+### PersistenceId
+
+The @apidoc[akka.persistence.typed.PersistenceId] is the stable unique identifier for the persistent actor in the backend
+event journal and snapshot store.
+
+@ref:[Cluster Sharding](cluster-sharding.md) is typically used together with `EventSourcedBehavior` to ensure
+that there is only one active entity for each `PersistenceId` (`entityId`).
+
+The `entityId` in Cluster Sharding is the business domain identifier of the entity. The `entityId` might not
+be unique enough to be used as the `PersistenceId` by itself. For example two different types of
+entities may have the same `entityId`. To create a unique `PersistenceId` the `entityId` is can be prefixed
+with a stable name of the entity type, which typically is the same as the `EntityTypeKey.name` that
+is used in Cluster Sharding. There are @scala[`PersistenceId.apply`]@java[`PersistenceId.of`] factory methods
+to help with constructing such `PersistenceId` from a `entityTypeHint` and `entityId`.
+
+The default separator when concatenating the `entityTypeHint` and `entityId` is `|`, but a custom separator
+is supported.
+
+@@@ note
+
+The `|` separator is also used in Lagom's `scaladsl.PersistentEntity` but no separator is used
+in Lagom's `javadsl.PersistentEntity`. For compatibility with Lagom's `javadsl.PersistentEntity`
+you should use `""` as the separator.
+
+@@@
+
+The @ref:[Persistence example in the Cluster Sharding documentation](cluster-sharding.md#persistence-example)
+illustrates how to construct the `PersistenceId` from the `entityTypeKey` and `entityId` provided by the
+`EntityContext`.
+
 ### Command handler
 
 The command handler is a function with 2 parameters, the current `State` and the incoming `Command`.