Entity

As explained in Akka in Action, Second Edition

A sharding entity is an actor instance identified and placed by cluster sharding, with at most one instance active in the cluster.

A sharding entity is an actor managed by Akka Cluster Sharding. It is identified by an entity type key and a string ID; that pair is unique across the cluster, so at most one active instance represents it at a time. Sharding distributes entities across nodes to spread memory use and relocates them when membership changes or a node fails. section 9.1 section 9.1.2

Figure 9.1 Relationships among nodes, shared regions, shards, and entities

Entities sit inside shards, while shard regions on cluster nodes route messages toward them. The shard coordinator tracks shard placement and helps regions find the destination before they cache routing information. section 9.1.1

An application addresses an entity through a shard region rather than relying on its underlying ActorRef. Send a message in a sharding envelope with the entity ID; if no instance exists, sharding creates one automatically. An EntityRef offers a similar messaging API, but it is not an ActorRef. section 9.1.1 section 9.1.2

Shipping container entity

A freight container can be modeled as one entity per container ID. Its behavior starts with no cargo, accepts AddCargo commands, and replies to GetCargos. Initialize ClusterSharding with the container type key and a behavior factory that receives the entity ID, then send ShardingEnvelope("id-1", AddCargo(cargo)) to the shard region. Different entity types may reuse the same ID without collision. section 9.1.2 section 9.1.3

Treat entity lifecycle as sharding infrastructure rather than ordinary actor ownership:

• Let the sharding module create, maintain, rebalance, and relocate entities; direct ActorRef interaction can bypass expected lifecycle behavior. section 9.1.3
• Route normal traffic through a shard region. Direct messages to the underlying ActorRef do not count as activity for passivation. section 9.1.3 section 9.1.5
• Expect a relocated entity to restart without its in-memory state. Use Akka Persistence when that state must survive movement or failure. section 9.1
• Passivate idle entities when their stored objects make memory costly. New routed messages are buffered until a passivated entity becomes active, subject to a buffer limit. section 9.1.5

How Akka in Action, Second Edition covers it

How deep it goes

Explains identity, routing, automatic creation, lifecycle ownership, relocation, and passivation, while deferring persistence and later passivation details.

Examples

Demonstrates a shipping-container actor that adds cargo and reports cargo through a shard region using a container ID.

What it assumes

Assumes typed actor protocols and cluster configuration while introducing entity identity, EntityRef, and shard-region messaging from examples.

What you can do after

Apply it via Akka Cluster Sharding to initialize typed entities and route ID-addressed messages through shard regions.

How it connects

Connects entities to cluster sharding, shards, shard regions, shard coordinators, ActorRef, EntityRef, passivation, and Akka Persistence.

liveBookmanning.com

Read Akka in Action, Second Edition on liveBook Get the book at manning.com

Related concepts

• dataset splitpart of · A dataset split is the division of a dataset into distinct subsets, typically assigned separate roles or distributed for independent storage or processing.
• cluster shardingused by · Cluster sharding is an Akka technique that distributes actors across cluster nodes according to a partition key.
• actorkind of · An actor is an independent entity or participant that performs actions, maintains or pursues state or goals, and interacts with other entities or systems.
• Akka Persistenceuses · Akka Persistence is an Akka module for building actors whose state can be durably stored and recovered from persisted events or snapshots.
• shard regionused by · A shard region is an Akka Cluster Sharding component on a node that routes messages to entities and contains or communicates with shards.

This explainer was generated by Manning's knowledge graph from the text of Akka in Action, Second Edition. The section links point to the parts of the book it draws on.