diff --git a/akka-docs/src/main/paradox/scala/cluster-sharding.md b/akka-docs/src/main/paradox/scala/cluster-sharding.md index 9b8ca9ffed..e36ec5bf67 100644 --- a/akka-docs/src/main/paradox/scala/cluster-sharding.md +++ b/akka-docs/src/main/paradox/scala/cluster-sharding.md @@ -39,7 +39,7 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #counter-actor } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #counter-actor } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #counter-actor } The above actor uses event sourcing and the support provided in @scala[`PersistentActor`] @java[`AbstractPersistentActor`] to store its state. It does not have to be a persistent actor, but in case of failure or migration of entities between nodes it must be able to recover @@ -56,7 +56,7 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #counter-start } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #counter-start } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #counter-start } The @scala[`extractEntityId` and `extractShardId` are two] @java[`messageExtractor` defines] application specific @scala[functions] @java[methods] to extract the entity identifier and the shard identifier from incoming messages. @@ -65,7 +65,7 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #counter-extractor } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #counter-extractor } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #counter-extractor } This example illustrates two different ways to define the entity identifier in the messages: @@ -103,14 +103,14 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #counter-usage } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #counter-usage } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #counter-usage } @@@ div { .group-scala } A more comprehensive sample is available in the tutorial named [Akka Cluster Sharding with Scala!](https://github.com/typesafehub/activator-akka-cluster-sharding-scala). -@@@ +@@@ ## How it works @@ -188,7 +188,7 @@ must be to begin the rebalancing. This strategy can be replaced by an applicatio implementation. The state of shard locations in the `ShardCoordinator` is persistent (durable) with -@ref:[Distributed Data](distributed-data.md) or @ref:[Persistence](persistence.md) to survive failures. When a crashed or +@ref:[Distributed Data](distributed-data.md) or @ref:[Persistence](persistence.md) to survive failures. When a crashed or unreachable coordinator node has been removed (via down) from the cluster a new `ShardCoordinator` singleton actor will take over and the state is recovered. During such a failure period shards with known location are still available, while messages for new (unknown) shards @@ -298,7 +298,7 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #extractShardId-StartEntity } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #extractShardId-StartEntity } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #extractShardId-StartEntity } When configured to remember entities, whenever a `Shard` is rebalanced onto another node or recovers after a crash it will recreate all the entities which were previously @@ -307,8 +307,8 @@ sent to the parent of the entity actor, otherwise the entity will be automatical restarted after the entity restart backoff specified in the configuration. When [Distributed Data mode](#cluster-sharding-mode) is used the identifiers of the entities are -stored in @ref:[Durable Storage](distributed-data.md#ddata-durable) of Distributed Data. You may want to change the -configuration of the akka.cluster.sharding.distributed-data.durable.lmdb.dir`, since +stored in @ref[Durable Storage](distributed-data.md#ddata-durable) of Distributed Data. You may want to change the +configuration of the `akka.cluster.sharding.distributed-data.durable.lmdb.dir`, since the default directory contains the remote port of the actor system. If using a dynamically assigned port (0) it will be different each time and the previously stored data will not be loaded. @@ -319,7 +319,7 @@ for that entity has been received in the `Shard`. Entities will not be restarted using a `Passivate`. Note that the state of the entities themselves will not be restored unless they have been made persistent, -e.g. with @ref:[Persistence](persistence.md). +e.g. with @ref[Persistence](persistence.md). The performance cost of `rememberEntities` is rather high when starting/stopping entities and when shards are rebalanced. This cost increases with number of entities per shard and we currently don't @@ -335,7 +335,7 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #supervisor } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #supervisor } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #supervisor } You start such a supervisor in the same way as if it was the entity actor. @@ -343,13 +343,13 @@ Scala : @@snip [ClusterShardingSpec.scala]($akka$/akka-cluster-sharding/src/multi-jvm/scala/akka/cluster/sharding/ClusterShardingSpec.scala) { #counter-supervisor-start } Java -: @@snip [ClusterShardingTest.java]($akka$/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java) { #counter-supervisor-start } +: @@snip [ClusterShardingTest.java]($code$/java/jdocs/sharding/ClusterShardingTest.java) { #counter-supervisor-start } Note that stopped entities will be started again when a new message is targeted to the entity. ## Graceful Shutdown -You can send the @scala[`ShardRegion.GracefulShutdown`] @java[`ShardRegion.gracefulShutdownInstance`] message +You can send the @scala[`ShardRegion.GracefulShutdown`] @java[`ShardRegion.gracefulShutdownInstance`] message to the `ShardRegion` actor to handoff all shards that are hosted by that `ShardRegion` and then the `ShardRegion` actor will be stopped. You can `watch` the `ShardRegion` actor to know when it is completed. During this period other regions will buffer messages for those shards in the same way as when a rebalance is @@ -442,7 +442,7 @@ if needed. @@snip [reference.conf]($akka$/akka-cluster-sharding/src/main/resources/reference.conf) { #sharding-ext-config } Custom shard allocation strategy can be defined in an optional parameter to -`ClusterSharding.start`. See the API documentation of @scala[`ShardAllocationStrategy`] @java[`AbstractShardAllocationStrategy`] for details +`ClusterSharding.start`. See the API documentation of @scala[`ShardAllocationStrategy`] @java[`AbstractShardAllocationStrategy`] for details of how to implement a custom shard allocation strategy. ## Inspecting cluster sharding state @@ -467,5 +467,5 @@ When doing rolling upgrades special care must be taken to not change any of the * the `extractShardId` function * the role that the shard regions run on * the persistence mode - + If any one of these needs a change it will require a full cluster restart. \ No newline at end of file diff --git a/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java b/akka-docs/src/test/java/jdocs/sharding/ClusterShardingTest.java similarity index 96% rename from akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java rename to akka-docs/src/test/java/jdocs/sharding/ClusterShardingTest.java index 2206a8fa65..bedfc5b120 100644 --- a/akka-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java +++ b/akka-docs/src/test/java/jdocs/sharding/ClusterShardingTest.java @@ -2,7 +2,7 @@ * Copyright (C) 2009-2017 Lightbend Inc. */ -package akka.cluster.sharding; +package jdocs.sharding; import static java.util.concurrent.TimeUnit.SECONDS; @@ -18,7 +18,17 @@ import akka.actor.Props; import akka.actor.SupervisorStrategy; import akka.actor.Terminated; import akka.actor.ReceiveTimeout; +//#counter-extractor +import akka.cluster.sharding.ShardRegion; + +//#counter-extractor + +//#counter-start import akka.japi.Option; +import akka.cluster.sharding.ClusterSharding; +import akka.cluster.sharding.ClusterShardingSettings; + +//#counter-start import akka.persistence.AbstractPersistentActor; import akka.cluster.Cluster; import akka.japi.pf.DeciderBuilder; diff --git a/build.sbt b/build.sbt index b42b60d047..189521ed83 100644 --- a/build.sbt +++ b/build.sbt @@ -103,6 +103,7 @@ lazy val docs = akkaModule("akka-docs") .dependsOn( actor, cluster, clusterMetrics, slf4j, agent, camel, osgi, persistenceTck, persistenceQuery, distributedData, stream, clusterTools % "compile->compile;test->test", + clusterSharding % "compile->compile;test->test", testkit % "compile->compile;test->test", remote % "compile->compile;test->test", persistence % "compile->compile;provided->provided;test->test",