root/akka.cluster.sharding/ClusterSharding

ClusterSharding

class ClusterSharding(system: ExtendedActorSystem) extends Extension
See also:
Companion:
object
trait Extension
class Object
trait Matchable
class Any

Value members

Concrete methods

def defaultShardAllocationStrategy(settings: ClusterShardingSettings): ShardAllocationStrategy

The default ShardAllocationStrategy is configured by least-shard-allocation-strategy properties.

The default ShardAllocationStrategy is configured by least-shard-allocation-strategy properties.

def getShardTypeNames: Set[String]

Java API: get all currently defined sharding type names.

Java API: get all currently defined sharding type names.

def shardRegion(typeName: String): ActorRef

Retrieve the actor reference of the ShardRegion actor responsible for the named entity type. The entity type must be registered with the start or startProxy method before it can be used here. Messages to the entity is always sent via the ShardRegion.

Retrieve the actor reference of the ShardRegion actor responsible for the named entity type. The entity type must be registered with the start or startProxy method before it can be used here. Messages to the entity is always sent via the ShardRegion.

def shardRegionProxy(typeName: String, dataCenter: DataCenter): ActorRef

Retrieve the actor reference of the ShardRegion actor that will act as a proxy to the named entity type running in another data center. A proxy within the same data center can be accessed with shardRegion instead of this method. The entity type must be registered with the startProxy method before it can be used here. Messages to the entity is always sent via the ShardRegion.

Retrieve the actor reference of the ShardRegion actor that will act as a proxy to the named entity type running in another data center. A proxy within the same data center can be accessed with shardRegion instead of this method. The entity type must be registered with the startProxy method before it can be used here. Messages to the entity is always sent via the ShardRegion.

def shardTypeNames: Set[String]

Scala API: get all currently defined sharding type names.

Scala API: get all currently defined sharding type names.

def start(typeName: String, entityProps: Props, settings: ClusterShardingSettings, extractEntityId: ExtractEntityId, extractShardId: ExtractShardId, allocationStrategy: ShardAllocationStrategy, handOffStopMessage: Any): ActorRef

Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

This method will start a ShardRegion in proxy mode when there is no match between the roles of the current cluster node and the role specified in ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
allocationStrategy

possibility to use a custom shard allocation and rebalancing logic

entityProps

the Props of the entity actors that will be created by the ShardRegion

extractEntityId

partial function to extract the entity id and the message to send to the entity from the incoming message, if the partial function does not match the message will be unhandled, i.e. posted as Unhandled messages on the event stream

extractShardId

function to determine the shard id for an incoming message, only messages that passed the extractEntityId will be used

handOffStopMessage

the message that will be sent to entities when they are to be stopped for a rebalance or graceful shutdown of a ShardRegion, e.g. PoisonPill.

settings

configuration settings, see ClusterShardingSettings

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def start(typeName: String, entityProps: Props, extractEntityId: ExtractEntityId, extractShardId: ExtractShardId, allocationStrategy: ShardAllocationStrategy, handOffStopMessage: Any): ActorRef

Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

This method will start a ShardRegion in proxy mode when there is no match between the roles of the current cluster node and the role specified in ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
allocationStrategy

possibility to use a custom shard allocation and rebalancing logic

entityProps

the Props of the entity actors that will be created by the ShardRegion

extractEntityId

partial function to extract the entity id and the message to send to the entity from the incoming message, if the partial function does not match the message will be unhandled, i.e. posted as Unhandled messages on the event stream

extractShardId

function to determine the shard id for an incoming message, only messages that passed the extractEntityId will be used

handOffStopMessage

the message that will be sent to entities when they are to be stopped for a rebalance or graceful shutdown of a ShardRegion, e.g. PoisonPill.

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def start(typeName: String, entityProps: Props, settings: ClusterShardingSettings, extractEntityId: ExtractEntityId, extractShardId: ExtractShardId): ActorRef

Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. akka.actor.PoisonPill is used as handOffStopMessage.

This method will start a ShardRegion in proxy mode when there is no match between the node roles and the role specified in the ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
entityProps

the Props of the entity actors that will be created by the ShardRegion

extractEntityId

partial function to extract the entity id and the message to send to the entity from the incoming message, if the partial function does not match the message will be unhandled, i.e. posted as Unhandled messages on the event stream

extractShardId

function to determine the shard id for an incoming message, only messages that passed the extractEntityId will be used

settings

configuration settings, see ClusterShardingSettings

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def start(typeName: String, entityProps: Props, extractEntityId: ExtractEntityId, extractShardId: ExtractShardId): ActorRef

Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. akka.actor.PoisonPill is used as handOffStopMessage.

This method will start a ShardRegion in proxy mode when there is no match between the node roles and the role specified in the ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
entityProps

the Props of the entity actors that will be created by the ShardRegion

extractEntityId

partial function to extract the entity id and the message to send to the entity from the incoming message, if the partial function does not match the message will be unhandled, i.e. posted as Unhandled messages on the event stream

extractShardId

function to determine the shard id for an incoming message, only messages that passed the extractEntityId will be used

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def start(typeName: String, entityProps: Props, settings: ClusterShardingSettings, messageExtractor: MessageExtractor, allocationStrategy: ShardAllocationStrategy, handOffStopMessage: Any): ActorRef

Java/Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Java/Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

This method will start a ShardRegion in proxy mode when there is no match between the node roles and the role specified in the ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
allocationStrategy

possibility to use a custom shard allocation and rebalancing logic

entityProps

the Props of the entity actors that will be created by the ShardRegion

handOffStopMessage

the message that will be sent to entities when they are to be stopped for a rebalance or graceful shutdown of a ShardRegion, e.g. PoisonPill.

messageExtractor

functions to extract the entity id, shard id, and the message to send to the entity from the incoming message, see ShardRegion.MessageExtractor

settings

configuration settings, see ClusterShardingSettings

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def start(typeName: String, entityProps: Props, settings: ClusterShardingSettings, messageExtractor: MessageExtractor): ActorRef

Java/Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Java/Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. akka.actor.PoisonPill is used as handOffStopMessage.

This method will start a ShardRegion in proxy mode when there is no match between the node roles and the role specified in the ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
entityProps

the Props of the entity actors that will be created by the ShardRegion

messageExtractor

functions to extract the entity id, shard id, and the message to send to the entity from the incoming message

settings

configuration settings, see ClusterShardingSettings

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def start(typeName: String, entityProps: Props, messageExtractor: MessageExtractor): ActorRef

Java/Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Java/Scala API: Register a named entity type by defining the akka.actor.Props of the entity actor and functions to extract entity and shard identifier from messages. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. akka.actor.PoisonPill is used as handOffStopMessage.

This method will start a ShardRegion in proxy mode when there is no match between the node roles and the role specified in the ClusterShardingSettings passed to this method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
entityProps

the Props of the entity actors that will be created by the ShardRegion

messageExtractor

functions to extract the entity id, shard id, and the message to send to the entity from the incoming message

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def startProxy(typeName: String, role: Option[String], extractEntityId: ExtractEntityId, extractShardId: ExtractShardId): ActorRef

Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
extractEntityId

partial function to extract the entity id and the message to send to the entity from the incoming message, if the partial function does not match the message will be unhandled, i.e. posted as Unhandled messages on the event stream

extractShardId

function to determine the shard id for an incoming message, only messages that passed the extractEntityId will be used

role

specifies that this entity type is located on cluster nodes with a specific role. If the role is not specified all nodes in the cluster are used.

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def startProxy(typeName: String, role: Option[String], dataCenter: Option[DataCenter], extractEntityId: ExtractEntityId, extractShardId: ExtractShardId): ActorRef

Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
dataCenter

The data center of the cluster nodes where the cluster sharding is running. If None then the same data center as current node.

extractEntityId

partial function to extract the entity id and the message to send to the entity from the incoming message, if the partial function does not match the message will be unhandled, i.e. posted as Unhandled messages on the event stream

extractShardId

function to determine the shard id for an incoming message, only messages that passed the extractEntityId will be used

role

specifies that this entity type is located on cluster nodes with a specific role. If the role is not specified all nodes in the cluster are used.

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def startProxy(typeName: String, role: Optional[String], messageExtractor: MessageExtractor): ActorRef

Java/Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Java/Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
messageExtractor

functions to extract the entity id, shard id, and the message to send to the entity from the incoming message

role

specifies that this entity type is located on cluster nodes with a specific role. If the role is not specified all nodes in the cluster are used.

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard

def startProxy(typeName: String, role: Optional[String], dataCenter: Optional[String], messageExtractor: MessageExtractor): ActorRef

Java/Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Java/Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e. it will delegate messages to other ShardRegion actors on other nodes, but not host any entity actors itself. The ShardRegion actor for this type can later be retrieved with the shardRegion method.

Some settings can be configured as described in the akka.cluster.sharding section of the reference.conf.

Value parameters:
dataCenter

The data center of the cluster nodes where the cluster sharding is running. If None then the same data center as current node.

messageExtractor

functions to extract the entity id, shard id, and the message to send to the entity from the incoming message

role

specifies that this entity type is located on cluster nodes with a specific role. If the role is not specified all nodes in the cluster are used.

typeName

the name of the entity type

Returns:

the actor ref of the ShardRegion that is to be responsible for the shard