Package org.apache.pekko.cluster.sharding

Class ClusterSharding

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static T apply​(ActorSystem system)  
      static T apply​(ClassicActorSystemProvider system)  
      static ClusterSharding createExtension​(ExtendedActorSystem system)  
      ShardCoordinator.ShardAllocationStrategy defaultShardAllocationStrategy​(ClusterShardingSettings settings)
      The default ShardAllocationStrategy is configured by least-shard-allocation-strategy properties.
      static boolean equals​(java.lang.Object other)  
      static ClusterSharding get​(ActorSystem system)  
      static ClusterSharding get​(ClassicActorSystemProvider system)  
      java.util.Set<java.lang.String> getShardTypeNames()
      Java API: get all currently defined sharding type names.
      static int hashCode()  
      static ClusterSharding$ lookup()  
      ActorRef shardRegion​(java.lang.String typeName)
      Retrieve the actor reference of the ShardRegion actor responsible for the named entity type.
      ActorRef shardRegionProxy​(java.lang.String typeName, java.lang.String dataCenter)
      Retrieve the actor reference of the ShardRegion actor that will act as a proxy to the named entity type running in another data center.
      scala.collection.immutable.Set<java.lang.String> shardTypeNames()
      Scala API: get all currently defined sharding type names.
      ActorRef start​(java.lang.String typeName, Props entityProps, ClusterShardingSettings settings, org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
      Java/Scala API: Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef start​(java.lang.String typeName, Props entityProps, ClusterShardingSettings settings, org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor, ShardCoordinator.ShardAllocationStrategy allocationStrategy, java.lang.Object handOffStopMessage)
      Java/Scala API: Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef start​(java.lang.String typeName, Props entityProps, ClusterShardingSettings settings, scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId, scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
      Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef start​(java.lang.String typeName, Props entityProps, ClusterShardingSettings settings, scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId, scala.Function1<java.lang.Object,​java.lang.String> extractShardId, ShardCoordinator.ShardAllocationStrategy allocationStrategy, java.lang.Object handOffStopMessage)
      Scala API: Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef start​(java.lang.String typeName, Props entityProps, org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
      Java/Scala API: Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef start​(java.lang.String typeName, Props entityProps, scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId, scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
      Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef start​(java.lang.String typeName, Props entityProps, scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId, scala.Function1<java.lang.Object,​java.lang.String> extractShardId, ShardCoordinator.ShardAllocationStrategy allocationStrategy, java.lang.Object handOffStopMessage)
      Scala API: Register a named entity type by defining the pekko.actor.Props of the entity actor and functions to extract entity and shard identifier from messages.
      ActorRef startProxy​(java.lang.String typeName, java.util.Optional<java.lang.String> role, java.util.Optional<java.lang.String> dataCenter, org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
      Java/Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e.
      ActorRef startProxy​(java.lang.String typeName, java.util.Optional<java.lang.String> role, org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
      Java/Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e.
      ActorRef startProxy​(java.lang.String typeName, scala.Option<java.lang.String> role, scala.Option<java.lang.String> dataCenter, scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId, scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
      Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e.
      ActorRef startProxy​(java.lang.String typeName, scala.Option<java.lang.String> role, scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId, scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
      Scala API: Register a named entity type ShardRegion on this node that will run in proxy only mode, i.e.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • apply

        public static T apply​(ActorSystem system)

      • hashCode

        public static final int hashCode()

      • equals

        public static final boolean equals​(java.lang.Object other)

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      ClusterShardingSettings settings,
                      scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId,
                      scala.Function1<java.lang.Object,​java.lang.String> extractShardId,
                      ShardCoordinator.ShardAllocationStrategy allocationStrategy,
                      java.lang.Object handOffStopMessage)
        Scala API: Register a named entity type by defining the pekko.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(java.lang.String) 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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        entityProps - the Props of the entity actors that will be created by the ShardRegion
        settings - configuration settings, see ClusterShardingSettings
        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
        allocationStrategy - possibility to use a custom shard allocation and rebalancing logic
        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.
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId,
                      scala.Function1<java.lang.Object,​java.lang.String> extractShardId,
                      ShardCoordinator.ShardAllocationStrategy allocationStrategy,
                      java.lang.Object handOffStopMessage)
        Scala API: Register a named entity type by defining the pekko.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(java.lang.String) 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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        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
        allocationStrategy - possibility to use a custom shard allocation and rebalancing logic
        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.
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      ClusterShardingSettings settings,
                      scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId,
                      scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
        Register a named entity type by defining the pekko.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(java.lang.String) method.

        The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. pekko.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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        entityProps - the Props of the entity actors that will be created by the ShardRegion
        settings - configuration settings, see ClusterShardingSettings
        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
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId,
                      scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
        Register a named entity type by defining the pekko.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(java.lang.String) method.

        The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. pekko.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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        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
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      ClusterShardingSettings settings,
                      org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor,
                      ShardCoordinator.ShardAllocationStrategy allocationStrategy,
                      java.lang.Object handOffStopMessage)
        Java/Scala API: Register a named entity type by defining the pekko.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(java.lang.String) 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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        entityProps - the Props of the entity actors that will be created by the ShardRegion
        settings - configuration settings, see ClusterShardingSettings
        messageExtractor - functions to extract the entity id, shard id, and the message to send to the entity from the incoming message, see ShardRegion.MessageExtractor
        allocationStrategy - possibility to use a custom shard allocation and rebalancing logic
        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.
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      ClusterShardingSettings settings,
                      org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
        Java/Scala API: Register a named entity type by defining the pekko.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(java.lang.String) method.

        The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. pekko.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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        entityProps - the Props of the entity actors that will be created by the ShardRegion
        settings - configuration settings, see ClusterShardingSettings
        messageExtractor - functions to extract the entity id, shard id, and the message to send to the entity from the incoming message
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • start

        public ActorRef start​(java.lang.String typeName,
                      Props entityProps,
                      org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
        Java/Scala API: Register a named entity type by defining the pekko.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(java.lang.String) method.

        The default shard allocation strategy ShardCoordinator.LeastShardAllocationStrategy is used. pekko.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 pekko.cluster.sharding section of the reference.conf.

        Parameters:
        typeName - the name of the entity type
        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
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • startProxy

        public ActorRef startProxy​(java.lang.String typeName,
                           scala.Option<java.lang.String> role,
                           scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId,
                           scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
        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(java.lang.String) method.

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

        Parameters:
        typeName - the name of the entity type
        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.
        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
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • startProxy

        public ActorRef startProxy​(java.lang.String typeName,
                           scala.Option<java.lang.String> role,
                           scala.Option<java.lang.String> dataCenter,
                           scala.PartialFunction<java.lang.Object,​scala.Tuple2<java.lang.String,​java.lang.Object>> extractEntityId,
                           scala.Function1<java.lang.Object,​java.lang.String> extractShardId)
        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(java.lang.String) method.

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

        Parameters:
        typeName - the name of the entity type
        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.
        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
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • startProxy

        public ActorRef startProxy​(java.lang.String typeName,
                           java.util.Optional<java.lang.String> role,
                           org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
        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(java.lang.String) method.

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

        Parameters:
        typeName - the name of the entity type
        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.
        messageExtractor - functions to extract the entity id, shard id, and the message to send to the entity from the incoming message
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • startProxy

        public ActorRef startProxy​(java.lang.String typeName,
                           java.util.Optional<java.lang.String> role,
                           java.util.Optional<java.lang.String> dataCenter,
                           org.apache.pekko.cluster.sharding.ShardRegion.MessageExtractor messageExtractor)
        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(java.lang.String) method.

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

        Parameters:
        typeName - the name of the entity type
        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.
        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
        Returns:
        the actor ref of the ShardRegion that is to be responsible for the shard

      • shardTypeNames

        public scala.collection.immutable.Set<java.lang.String> shardTypeNames()
        Scala API: get all currently defined sharding type names.

      • getShardTypeNames

        public java.util.Set<java.lang.String> getShardTypeNames()
        Java API: get all currently defined sharding type names.