diff --git a/docs/src/main/paradox/actors.md b/docs/src/main/paradox/actors.md index 07db055775..aa2d8f523f 100644 --- a/docs/src/main/paradox/actors.md +++ b/docs/src/main/paradox/actors.md @@ -1171,7 +1171,7 @@ then you should use the @scala[@scaladoc[UnboundedStash](pekko.actor.UnboundedSt ## Extending Actors using PartialFunction chaining -Sometimes it can be useful to share common behavior among a few actors, or compose one actor's behavior from multiple smaller functions. +Sometimes, it can be useful to share common behavior among a few actors, or compose one actor's behavior from multiple smaller functions. This is possible because an actor's @scala[@scaladoc[receive](pekko.actor.Actor#receive:org.apache.pekko.actor.Actor.Receive)]@java[@javadoc[createReceive](pekko.actor.AbstractActor#createReceive())] method returns an `Actor.Receive`, which is a type alias for `PartialFunction[Any,Unit]`, and partial functions can be chained together using the `PartialFunction#orElse` method. You can chain as many functions as you need, however you should keep in mind that "first match" wins - which may be important when combining functions that both can handle the same type of message. diff --git a/docs/src/main/paradox/coordination.md b/docs/src/main/paradox/coordination.md index 38594715b4..1a3b4c88b3 100644 --- a/docs/src/main/paradox/coordination.md +++ b/docs/src/main/paradox/coordination.md @@ -1,5 +1,5 @@ --- -project.description: A distributed lock with Pekko Coordination using a pluggable lease API. +project.description: A distributed lock with Apache Pekko Coordination using a pluggable lease API. --- # Coordination diff --git a/docs/src/main/paradox/discovery/index.md b/docs/src/main/paradox/discovery/index.md index a11558aee4..9665314174 100644 --- a/docs/src/main/paradox/discovery/index.md +++ b/docs/src/main/paradox/discovery/index.md @@ -1,5 +1,5 @@ --- -project.description: Service discovery with Pekko using DNS, Kubernetes, AWS, Consul or Marathon. +project.description: Service discovery with Apache Pekko using DNS, Kubernetes, AWS, Consul or Marathon. --- # Discovery diff --git a/docs/src/main/paradox/durable-state/persistence-query.md b/docs/src/main/paradox/durable-state/persistence-query.md index 9d2cee1611..8a68ae6337 100644 --- a/docs/src/main/paradox/durable-state/persistence-query.md +++ b/docs/src/main/paradox/durable-state/persistence-query.md @@ -1,11 +1,11 @@ --- -project.description: Query side to Pekko Persistence allowing for building CQRS applications using durable state. +project.description: Query side to Apache Pekko Persistence allowing for building CQRS applications using durable state. --- # Persistence Query ## Dependency -To use Persistence Query, you must add the following dependency in your project: +To use Apache Persistence Query, you must add the following dependency in your project: @@dependency[sbt,Maven,Gradle] { bomGroup=org.apache.pekko bomArtifact=pekko-bom_$scala.binary.version$ bomVersionSymbols=PekkoVersion diff --git a/docs/src/main/paradox/extending-pekko.md b/docs/src/main/paradox/extending-pekko.md index 8270d029f0..5022191727 100644 --- a/docs/src/main/paradox/extending-pekko.md +++ b/docs/src/main/paradox/extending-pekko.md @@ -1,10 +1,10 @@ --- -project.description: How to extend Pekko with Pekko Extensions. +project.description: How to extend Apache Pekko with Apache Pekko Extensions. --- -# Classic Pekko Extensions +# Classic Apache Pekko Extensions -If you want to add features to Pekko, there is a very elegant, but powerful mechanism for doing so. -It's called Pekko Extensions and comprises 2 basic components: an @apidoc[Extension](actor.Extension) and an @apidoc[ExtensionId](actor.ExtensionId). +If you want to add features to Apache Pekko, there is a very elegant, but powerful mechanism for doing so. +It's called Apache Pekko Extensions and comprises 2 basic components: an @apidoc[Extension](actor.Extension) and an @apidoc[ExtensionId](actor.ExtensionId). Extensions will only be loaded once per @apidoc[ActorSystem](actor.ActorSystem), which will be managed by Pekko. You can choose to have your Extension loaded on-demand or at @apidoc[ActorSystem](actor.ActorSystem) creation time through the Pekko configuration. diff --git a/docs/src/main/paradox/general/actor-systems.md b/docs/src/main/paradox/general/actor-systems.md index 96e6ee8fd5..303197559f 100644 --- a/docs/src/main/paradox/general/actor-systems.md +++ b/docs/src/main/paradox/general/actor-systems.md @@ -1,5 +1,5 @@ --- -project.description: The Pekko ActorSystem. +project.description: The Apache Pekko ActorSystem. --- # Actor Systems diff --git a/docs/src/main/paradox/general/actors.md b/docs/src/main/paradox/general/actors.md index 28db2e4051..75a14ef4e8 100644 --- a/docs/src/main/paradox/general/actors.md +++ b/docs/src/main/paradox/general/actors.md @@ -1,5 +1,5 @@ --- -project.description: What is an Actor and sending messages between independent units of computation in Pekko. +project.description: What is an Actor and sending messages between independent units of computation in Apache Pekko. --- # What is an Actor? @@ -7,7 +7,7 @@ The previous section about @ref:[Actor Systems](actor-systems.md) explained how hierarchies and are the smallest unit when building an application. This section looks at one such actor in isolation, explaining the concepts you encounter while implementing it. For a more in depth reference with all the -details please refer to @ref:[Introduction to Actors](../typed/actors.md). +details, please refer to @ref:[Introduction to Actors](../typed/actors.md). The [Actor Model](https://en.wikipedia.org/wiki/Actor_model) as defined by Hewitt, Bishop and Steiger in 1973 is a computational model that expresses diff --git a/docs/src/main/paradox/general/addressing.md b/docs/src/main/paradox/general/addressing.md index 2f9ec55a29..0de7eae409 100644 --- a/docs/src/main/paradox/general/addressing.md +++ b/docs/src/main/paradox/general/addressing.md @@ -1,5 +1,5 @@ --- -project.description: Local and remote Pekko Actor references, locating Actors, Actor paths and addresses. +project.description: Local and remote Apache Pekko Actor references, locating Actors, Actor paths and addresses. --- # Actor References, Paths and Addresses diff --git a/docs/src/main/paradox/general/configuration.md b/docs/src/main/paradox/general/configuration.md index 4e7e358d98..f80514ec18 100644 --- a/docs/src/main/paradox/general/configuration.md +++ b/docs/src/main/paradox/general/configuration.md @@ -116,7 +116,7 @@ pekko { ## Including files -Sometimes it can be useful to include another configuration file, for example if you have one `application.conf` with all +Sometimes, it can be useful to include another configuration file, for example if you have one `application.conf` with all environment independent settings and then override some settings for specific environments. Specifying system property with `-Dconfig.resource=/dev.conf` will load the `dev.conf` file, which includes the `application.conf` diff --git a/docs/src/main/paradox/general/jmm.md b/docs/src/main/paradox/general/jmm.md index ee436fc424..35ddcc7fa6 100644 --- a/docs/src/main/paradox/general/jmm.md +++ b/docs/src/main/paradox/general/jmm.md @@ -1,7 +1,7 @@ --- -project.description: Pekko, Actors, Futures and the Java Memory Model. +project.description: Apache Pekko, Actors, Futures and the Java Memory Model. --- -# Pekko and the Java Memory Model +# Apache Pekko and the Java Memory Model A major benefit of using Pekko is that it simplifies the process of writing concurrent software. This article discusses how the Pekko Platform approaches shared memory diff --git a/docs/src/main/paradox/general/message-delivery-reliability.md b/docs/src/main/paradox/general/message-delivery-reliability.md index eed0d41b9f..9766d41338 100644 --- a/docs/src/main/paradox/general/message-delivery-reliability.md +++ b/docs/src/main/paradox/general/message-delivery-reliability.md @@ -1,5 +1,5 @@ --- -project.description: Pekko message delivery semantics, at-most-once delivery and message ordering. +project.description: Apache Pekko message delivery semantics, at-most-once delivery and message ordering. --- # Message Delivery Reliability diff --git a/docs/src/main/paradox/general/stream/stream-design.md b/docs/src/main/paradox/general/stream/stream-design.md index 18bf9cd5f7..f35785b5f9 100644 --- a/docs/src/main/paradox/general/stream/stream-design.md +++ b/docs/src/main/paradox/general/stream/stream-design.md @@ -1,10 +1,10 @@ -# Design Principles behind Pekko Streams +# Design Principles behind Apache Pekko Streams It took quite a while until we were reasonably happy with the look and feel of the API and the architecture of the implementation, and while being guided by intuition the design phase was very much exploratory research. This section details the findings and codifies them into a set of principles that have emerged during the process. @@@ note -As detailed in the introduction keep in mind that the Pekko Streams API is completely decoupled from the Reactive Streams interfaces which are an implementation detail for how to pass stream data between individual operators. +As detailed in the introduction, keep in mind that the Pekko Streams API is completely decoupled from the Reactive Streams interfaces which are an implementation detail for how to pass stream data between individual operators. @@@ @@ -63,7 +63,7 @@ which then is materialized and executed in accordance to Reactive Streams rules. Another not obvious gain from hiding the Reactive Streams interfaces comes from the fact that `org.reactivestreams.Subscriber` (et al) have now been included in Java 9+, and thus become part of Java itself, so libraries should migrate to using the @javadoc[java.util.concurrent.Flow.Subscriber](java.util.concurrent.Flow.Subscriber) instead of `org.reactivestreams.Subscriber`. Libraries which selected to expose and directly extend the Reactive Streams types will now have a tougher time to adapt the JDK9+ types -- all their classes that extend Subscriber and friends will need to be copied or changed to extend the exact same interface, -but from a different package. In Pekko we simply expose the new type when asked to -- already supporting JDK9 types, from the day JDK9 was released. +but from a different package. In Pekko, we simply expose the new type when asked to -- already supporting JDK9 types, from the day JDK9 was released. The other, and perhaps more important reason for hiding the Reactive Streams interfaces comes back to the first points of this explanation: the fact of Reactive Streams being an SPI, and as such is hard to "get right" in ad-hoc implementations. Thus Pekko Streams discourages the use of the hard to implement pieces of the underlying infrastructure, and offers simpler, more type-safe, yet more powerful abstractions for users to work with: @apidoc[GraphStage]s and operators. It is of course still (and easily) possible to accept or obtain Reactive Streams (or JDK+ Flow) representations of the stream operators by using methods like @apidoc[Sink.asPublisher](Sink$) {scala="#asPublisher[T](fanout:Boolean):org.apache.pekko.stream.scaladsl.Sink[T,org.reactivestreams.Publisher[T]]" java="#asPublisher(org.apache.pekko.stream.javadsl.AsPublisher)"} or @apidoc[fromSubscriber](Sink$) {scala="#fromSubscriber[T](subscriber:org.reactivestreams.Subscriber[T]):org.apache.pekko.stream.scaladsl.Sink[T,org.apache.pekko.NotUsed]" java="#fromSubscriber(org.reactivestreams.Subscriber)"}. diff --git a/docs/src/main/paradox/general/supervision.md b/docs/src/main/paradox/general/supervision.md index 73ae00e2ff..e037834660 100644 --- a/docs/src/main/paradox/general/supervision.md +++ b/docs/src/main/paradox/general/supervision.md @@ -1,5 +1,5 @@ --- -project.description: Hierarchical supervision, lifecycle monitoring and error or failure handling in Pekko. +project.description: Hierarchical supervision, lifecycle monitoring and error or failure handling in Apache Pekko. --- # Supervision and Monitoring diff --git a/docs/src/main/paradox/io-tcp.md b/docs/src/main/paradox/io-tcp.md index f5492241f8..de5104a777 100644 --- a/docs/src/main/paradox/io-tcp.md +++ b/docs/src/main/paradox/io-tcp.md @@ -170,7 +170,7 @@ an "ack" event if required. Tcp.CompoundWrite : -Sometimes you might want to group (or interleave) several `Tcp.Write` and/or `Tcp.WriteFile` commands into +Sometimes, you might want to group (or interleave) several `Tcp.Write` and/or `Tcp.WriteFile` commands into one atomic write command which gets written to the connection in one go. The `Tcp.CompoundWrite` allows you to do just that and offers three benefits: 1. As explained in the following section the TCP connection actor can only handle one single write command at a time. diff --git a/docs/src/main/paradox/multi-jvm-testing.md b/docs/src/main/paradox/multi-jvm-testing.md index 8671cfbedd..b6f82d79cb 100644 --- a/docs/src/main/paradox/multi-jvm-testing.md +++ b/docs/src/main/paradox/multi-jvm-testing.md @@ -1,5 +1,5 @@ --- -project.description: Multi JVM testing of distributed systems built with Pekko. +project.description: Multi JVM testing of distributed systems built with Apache Pekko. --- # Multi JVM Testing diff --git a/docs/src/main/paradox/multi-node-testing.md b/docs/src/main/paradox/multi-node-testing.md index b1b9dcebb5..1be32725b3 100644 --- a/docs/src/main/paradox/multi-node-testing.md +++ b/docs/src/main/paradox/multi-node-testing.md @@ -1,5 +1,5 @@ --- -project.description: Multi node testing of distributed systems built with Pekko. +project.description: Multi node testing of distributed systems built with Apache Pekko. --- # Multi Node Testing diff --git a/docs/src/main/paradox/persistence-query.md b/docs/src/main/paradox/persistence-query.md index e0bdc093cc..f3d65a552f 100644 --- a/docs/src/main/paradox/persistence-query.md +++ b/docs/src/main/paradox/persistence-query.md @@ -1,7 +1,7 @@ --- -project.description: Query side to Pekko Persistence allowing for building CQRS applications. +project.description: Query side to Apache Pekko Persistence allowing for building CQRS applications. --- -# Persistence Query +# Apache Persistence Query ## Dependency @@ -264,7 +264,7 @@ Java ### Resumable projections -Sometimes you may need to use "resumable" projections, which will not start from the beginning of time each time +Sometimes, you may need to use "resumable" projections, which will not start from the beginning of time each time when run. In such case, the sequence number (or `offset`) of the processed event will be stored and used the next time this projection is started. This pattern is implemented in the [Pekko Projections]($pekko.doc.dns$/docs/pekko-projection/current/) module. diff --git a/docs/src/main/paradox/persistence.md b/docs/src/main/paradox/persistence.md index b816210e12..d501a5ac24 100644 --- a/docs/src/main/paradox/persistence.md +++ b/docs/src/main/paradox/persistence.md @@ -1,5 +1,5 @@ --- -project.description: Pekko Persistence Classic, Event Sourcing with Pekko, At-Least-Once delivery, snapshots, recovery and replay with Pekko actors. +project.description: Apache Pekko Persistence Classic, Event Sourcing with Apache Pekko, At-Least-Once delivery, snapshots, recovery and replay with Apache Pekko actors. --- # Classic Persistence @@ -190,7 +190,7 @@ Scala Java : @@snip [LambdaPersistenceDocTest.java](/docs/src/test/java/jdocs/persistence/LambdaPersistenceDocTest.java) { #recovery-status } -Sometimes there is a need for performing additional initialization when the +Sometimes, there is a need for performing additional initialization when the recovery has completed before processing any other message sent to the persistent actor. The persistent actor will receive a special @apidoc[persistence.RecoveryCompleted$] message right after recovery and before any other received messages. @@ -303,7 +303,7 @@ The callback will not be invoked if the actor is restarted (or stopped) in betwe ### Deferring actions until preceding persist handlers have executed -Sometimes when working with @scala[@scaladoc[persistAsync](pekko.persistence.PersistentActor#persistAsync[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[persistAsync](pekko.persistence.AbstractPersistentActorLike#persistAsync(A,org.apache.pekko.japi.Procedure))] or @scala[@scaladoc[persist](pekko.persistence.PersistentActor#persist[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[persist](pekko.persistence.AbstractPersistentActorLike#persist(A,org.apache.pekko.japi.Procedure))] you may find that it would be nice to define some actions in terms of +Sometimes, when working with @scala[@scaladoc[persistAsync](pekko.persistence.PersistentActor#persistAsync[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[persistAsync](pekko.persistence.AbstractPersistentActorLike#persistAsync(A,org.apache.pekko.japi.Procedure))] or @scala[@scaladoc[persist](pekko.persistence.PersistentActor#persist[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[persist](pekko.persistence.AbstractPersistentActorLike#persist(A,org.apache.pekko.japi.Procedure))] you may find that it would be nice to define some actions in terms of ''happens-after the previous `persistAsync`/`persist` handlers have been invoked''. @scala[`PersistentActor`]@java[`AbstractPersistentActor`] provides utility methods called @scala[@scaladoc[defer](pekko.persistence.PersistentActor#defer[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[defer](pekko.persistence.AbstractPersistentActorLike#defer(A,org.apache.pekko.japi.Procedure))] and @scala[@scaladoc[deferAsync](pekko.persistence.PersistentActor#deferAsync[A](event:A)(handler:A=%3EUnit):Unit)]@java[@javadoc[deferAsync](pekko.persistence.AbstractPersistentActorLike#deferAsync(A,org.apache.pekko.japi.Procedure))], which work similarly to `persist` and `persistAsync` respectively yet do not persist the passed in event. It is recommended to use them for *read* operations, and actions which do not have corresponding events in your diff --git a/docs/src/main/paradox/project/immutable.md b/docs/src/main/paradox/project/immutable.md index 510a862e69..80c7ebe972 100644 --- a/docs/src/main/paradox/project/immutable.md +++ b/docs/src/main/paradox/project/immutable.md @@ -3,7 +3,7 @@ project.description: Data immutability using Project Lombok --- # Immutability using Lombok -A preferred best practice in Pekko is to have immutable messages. Scala provides case class which makes it extremely easy +A preferred best practice in Apache Pekko is to have immutable messages. Scala provides case class which makes it extremely easy to have short and clean classes for creating immutable objects, but no such facility is easily available in Java. We can make use of several third party libraries which help is achieving this. One good example is Lombok. diff --git a/docs/src/main/paradox/project/migration-guides.md b/docs/src/main/paradox/project/migration-guides.md index a40c60431e..2dfee1570f 100644 --- a/docs/src/main/paradox/project/migration-guides.md +++ b/docs/src/main/paradox/project/migration-guides.md @@ -1,5 +1,5 @@ --- -project.description: Pekko version migration guides. +project.description: Apache Pekko version migration guides. --- # Migration Guides diff --git a/docs/src/main/paradox/remoting-artery.md b/docs/src/main/paradox/remoting-artery.md index 47ebf7310c..49047909b7 100644 --- a/docs/src/main/paradox/remoting-artery.md +++ b/docs/src/main/paradox/remoting-artery.md @@ -1,5 +1,5 @@ --- -project.description: Details about the underlying remoting module for Pekko Cluster. +project.description: Details about the underlying remoting module for Apache Pekko Cluster. --- # Artery Remoting diff --git a/docs/src/main/paradox/scheduler.md b/docs/src/main/paradox/scheduler.md index 1680432d67..87d60f8426 100644 --- a/docs/src/main/paradox/scheduler.md +++ b/docs/src/main/paradox/scheduler.md @@ -1,5 +1,5 @@ --- -project.description: How to schedule processes in Pekko with the Scheduler. +project.description: How to schedule processes in Apache Pekko with the Scheduler. --- # Classic Scheduler @@ -21,7 +21,7 @@ To use Scheduler, you must add the following dependency in your project: ## Introduction -Sometimes the need for making things happen in the future arises, and where do +Sometimes, the need for making things happen in the future arises, and where do you go look then? Look no further than @apidoc[actor.ActorSystem]! There you find the @scala[@scaladoc[scheduler](pekko.actor.ActorSystem#scheduler:org.apache.pekko.actor.Scheduler)]@java[@javadoc[getScheduler()](pekko.actor.ActorSystem#getScheduler())] method that returns an instance of @apidoc[actor.Scheduler], this instance is unique per ActorSystem and is @@ -31,7 +31,7 @@ You can schedule sending of messages to actors and execution of tasks (functions or Runnable). You will get a @apidoc[Cancellable] back that you can call @scala[@scaladoc[cancel](pekko.actor.Cancellable#cancel():Boolean)]@java[@javadoc[cancel()](pekko.actor.Cancellable#cancel())] on to cancel the execution of the scheduled operation. -When scheduling periodic or single messages in an actor to itself it is recommended to +When scheduling periodic or single messages in an actor to itself, it is recommended to use the @ref:[Actor Timers](actors.md#actors-timers) instead of using the @apidoc[actor.Scheduler] directly. diff --git a/docs/src/main/paradox/serialization-jackson.md b/docs/src/main/paradox/serialization-jackson.md index f072da15b6..52f7ee38be 100644 --- a/docs/src/main/paradox/serialization-jackson.md +++ b/docs/src/main/paradox/serialization-jackson.md @@ -1,5 +1,5 @@ --- -project.description: Serialization with Jackson for Pekko. +project.description: Serialization with Jackson for Apache Pekko. --- # Serialization with Jackson diff --git a/docs/src/main/paradox/serialization.md b/docs/src/main/paradox/serialization.md index 326107523c..14a6248d5f 100644 --- a/docs/src/main/paradox/serialization.md +++ b/docs/src/main/paradox/serialization.md @@ -1,5 +1,5 @@ --- -project.description: Serialization APIs built into Pekko. +project.description: Serialization APIs built into Apache Pekko. --- # Serialization diff --git a/docs/src/main/paradox/stream/stream-cookbook.md b/docs/src/main/paradox/stream/stream-cookbook.md index ce1ea4f1a4..56fa5b1e82 100644 --- a/docs/src/main/paradox/stream/stream-cookbook.md +++ b/docs/src/main/paradox/stream/stream-cookbook.md @@ -181,7 +181,7 @@ Java **Situation:** Given a message, we want to split the message and aggregate its sub-messages into a new message -Sometimes it's very useful to split a message and aggregate its sub-messages into a new message. This involves a +Sometimes, it's very useful to split a message and aggregate its sub-messages into a new message. This involves a combination of [Splitter](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Sequencer.html) and [Aggregator](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Aggregator.html) @@ -258,7 +258,7 @@ parallelization pattern like MapReduce and similar frameworks. ### Sorting elements to multiple groups with groupBy **Situation:** The `groupBy` operation strictly partitions incoming elements, each element belongs to exactly one group. -Sometimes we want to map elements into multiple groups simultaneously. +Sometimes, we want to map elements into multiple groups simultaneously. To achieve the desired result, we attack the problem in two steps: diff --git a/docs/src/main/paradox/stream/stream-customize.md b/docs/src/main/paradox/stream/stream-customize.md index f743803fac..f8795b2d12 100644 --- a/docs/src/main/paradox/stream/stream-customize.md +++ b/docs/src/main/paradox/stream/stream-customize.md @@ -439,7 +439,7 @@ See @ref:[Modularity, Composition and Hierarchy](stream-composition.md) for an e ### Rate decoupled operators -Sometimes it is desirable to *decouple* the rate of the upstream and downstream of an operator, synchronizing only +Sometimes, it is desirable to *decouple* the rate of the upstream and downstream of an operator, synchronizing only when needed. This is achieved in the model by representing a `GraphStage` as a *boundary* between two regions where the diff --git a/docs/src/main/paradox/stream/stream-flows-and-basics.md b/docs/src/main/paradox/stream/stream-flows-and-basics.md index eda4e83b66..48d044450b 100644 --- a/docs/src/main/paradox/stream/stream-flows-and-basics.md +++ b/docs/src/main/paradox/stream/stream-flows-and-basics.md @@ -360,7 +360,7 @@ Java ## Stream ordering -In Pekko Streams almost all computation operators *preserve input order* of elements. This means that if inputs `{IA1,IA2,...,IAn}` +In Pekko Streams, almost all computation operators *preserve input order* of elements. This means that if inputs `{IA1,IA2,...,IAn}` "cause" outputs `{OA1,OA2,...,OAk}` and inputs `{IB1,IB2,...,IBm}` "cause" outputs `{OB1,OB2,...,OBl}` and all of `IAi` happened before all `IBi` then `OAi` happens before `OBi`. diff --git a/docs/src/main/paradox/stream/stream-graphs.md b/docs/src/main/paradox/stream/stream-graphs.md index be7459d0a8..6e1067e635 100644 --- a/docs/src/main/paradox/stream/stream-graphs.md +++ b/docs/src/main/paradox/stream/stream-graphs.md @@ -15,7 +15,7 @@ To use Pekko Streams, add the module to your project: ## Introduction -In Pekko Streams computation graphs are not expressed using a fluent DSL like linear computations are, instead they are +In Pekko Streams, computation graphs are not expressed using a fluent DSL like linear computations are, instead they are written in a more graph-resembling DSL which aims to make translating graph drawings (e.g. from notes taken from design discussions, or illustrations in protocol specifications) to and from code simpler. In this section we'll dive into the multiple ways of constructing and re-using graphs, as well as explain common pitfalls and how to avoid them. @@ -59,7 +59,7 @@ the below hand drawn graph into Pekko Streams: ![simple-graph-example.png](../images/simple-graph-example.png) -Such graph is simple to translate to the Graph DSL since each linear element corresponds to a `Flow`, +Such a graph is simple to translate to the Graph DSL since each linear element corresponds to a `Flow`, and each circle corresponds to either a `Junction` or a `Source` or `Sink` if it is beginning or ending a `Flow`. @scala[Junctions must always be created with defined type parameters, as otherwise the `Nothing` type will be inferred.] @@ -95,7 +95,7 @@ new graph. The difference between these approaches is that importing using `buil materialized value of the imported graph while importing via the factory method allows its inclusion; for more details see @ref[Stream Materialization](stream-flows-and-basics.md#stream-materialization). -In the example below we prepare a graph that consists of two parallel streams, +In the example below, we prepare a graph that consists of two parallel streams, in which we re-use the same instance of `Flow`, yet it will properly be materialized as two connections between the corresponding Sources and Sinks: @@ -105,7 +105,7 @@ Scala Java : @@snip [GraphDSLTest.java](/stream-tests/src/test/java/org/apache/pekko/stream/javadsl/GraphDslTest.java) { #graph-dsl-reusing-a-flow } -In some cases we may have a list of graph elements, for example if they are dynamically created. +In some cases we may have a list of graph elements, for example, if they are dynamically created. If these graphs have similar signatures, we can construct a graph collecting all their materialized values as a collection: Scala @@ -118,7 +118,7 @@ Java ## Constructing and combining Partial Graphs -Sometimes it is not possible (or needed) to construct the entire computation graph in one place, but instead construct +Sometimes, it is not possible (or needed) to construct the entire computation graph in one place, but instead construct all of its different phases in different places and in the end connect them all into a complete graph and run it. This can be achieved by @scala[returning a different `Shape` than `ClosedShape`, for example `FlowShape(in, out)`, from the diff --git a/docs/src/main/paradox/stream/stream-quickstart.md b/docs/src/main/paradox/stream/stream-quickstart.md index b7333578b8..999b23ed86 100644 --- a/docs/src/main/paradox/stream/stream-quickstart.md +++ b/docs/src/main/paradox/stream/stream-quickstart.md @@ -131,7 +131,7 @@ the processing steps necessary to get the @apidoc[util.ByteString] elements from incoming strings and package that up as a reusable piece as well. Since the language for writing these streams always flows from left to right (just like plain English), we need a starting point that is like a source but with an -“open” input. In Pekko Streams this is called a @apidoc[stream.*.Flow]: +“open” input. In Pekko Streams, this is called a @apidoc[stream.*.Flow]: Scala : @@snip [QuickStartDocSpec.scala](/docs/src/test/scala/docs/stream/QuickStartDocSpec.scala) { #transform-sink } @@ -238,7 +238,7 @@ Scala Java : @@snip [TwitterStreamQuickstartDocTest.java](/docs/src/test/java/jdocs/stream/TwitterStreamQuickstartDocTest.java) { #system-setup } -Let's assume we have a stream of tweets readily available. In Pekko this is expressed as a @scala[`Source[Out, M]`]@java[`Source`]: +Let's assume we have a stream of tweets readily available. In Pekko, this is expressed as a @scala[`Source[Out, M]`]@java[`Source`]: Scala : @@snip [TwitterStreamQuickstartDocSpec.scala](/docs/src/test/scala/docs/stream/TwitterStreamQuickstartDocSpec.scala) { #tweet-source } diff --git a/docs/src/main/paradox/testing.md b/docs/src/main/paradox/testing.md index 387027cc61..92897d02fe 100644 --- a/docs/src/main/paradox/testing.md +++ b/docs/src/main/paradox/testing.md @@ -251,7 +251,7 @@ pekko.loggers = [org.apache.pekko.testkit.TestEventListener] ### Overriding behavior -Sometimes you want to 'hook into' your actor to be able to test some internals. +Sometimes, you want to 'hook into' your actor to be able to test some internals. Usually, it is better to test an actors' external interface, but for example if you want to test timing-sensitive behavior this can come in handy. Say for instance you want to test an actor that schedules a task: diff --git a/docs/src/main/paradox/typed/actor-discovery.md b/docs/src/main/paradox/typed/actor-discovery.md index 43f62b94ff..555b2b5b6b 100644 --- a/docs/src/main/paradox/typed/actor-discovery.md +++ b/docs/src/main/paradox/typed/actor-discovery.md @@ -22,7 +22,7 @@ There are two general ways to obtain @ref:[Actor references](../general/addressi You can pass actor references between actors as constructor parameters or part of messages. -Sometimes you need something to bootstrap the interaction, for example when actors are running on +Sometimes, you need something to bootstrap the interaction, for example when actors are running on different nodes in the Cluster or when "dependency injection" with constructor parameters is not applicable. diff --git a/docs/src/main/paradox/typed/actor-lifecycle.md b/docs/src/main/paradox/typed/actor-lifecycle.md index 25ca60cd25..c5837f4da6 100644 --- a/docs/src/main/paradox/typed/actor-lifecycle.md +++ b/docs/src/main/paradox/typed/actor-lifecycle.md @@ -1,5 +1,5 @@ --- -project.description: The Pekko Actor lifecycle. +project.description: The Apache Pekko Actor lifecycle. --- # Actor lifecycle diff --git a/docs/src/main/paradox/typed/actors.md b/docs/src/main/paradox/typed/actors.md index 74d1071d49..a2d2ce522a 100644 --- a/docs/src/main/paradox/typed/actors.md +++ b/docs/src/main/paradox/typed/actors.md @@ -1,5 +1,5 @@ --- -project.description: The Actor model, managing internal state and changing behavior in Pekko Actors. +project.description: The Actor model, managing internal state and changing behavior in Apache Pekko Actors. --- # Introduction to Actors diff --git a/docs/src/main/paradox/typed/cluster-membership.md b/docs/src/main/paradox/typed/cluster-membership.md index 2f44c1f2ac..6cd82b2a83 100644 --- a/docs/src/main/paradox/typed/cluster-membership.md +++ b/docs/src/main/paradox/typed/cluster-membership.md @@ -1,9 +1,9 @@ --- -project.description: The Pekko Cluster node membership service, manages dynamic member states and lifecycle with no external infrastructure needed. +project.description: The Apache Pekko Cluster node membership service, manages dynamic member states and lifecycle with no external infrastructure needed. --- # Cluster Membership Service -The core of Pekko Cluster is the cluster membership, to keep track of what nodes are part of the cluster and +The core of Apache Pekko Cluster is the cluster membership, to keep track of what nodes are part of the cluster and their health. Cluster membership is communicated using @ref:[gossip](cluster-concepts.md#gossip) and @ref:[failure detection](cluster-concepts.md#failure-detector). diff --git a/docs/src/main/paradox/typed/cluster-sharding.md b/docs/src/main/paradox/typed/cluster-sharding.md index 1bf501ab0b..4b9fe75938 100644 --- a/docs/src/main/paradox/typed/cluster-sharding.md +++ b/docs/src/main/paradox/typed/cluster-sharding.md @@ -1,5 +1,5 @@ --- -project.description: Shard a clustered compute process across the network with locationally transparent message routing using Pekko Cluster Sharding. +project.description: Shard a clustered compute process across the network with locationally transparent message routing using Apache Pekko Cluster Sharding. --- # Cluster Sharding diff --git a/docs/src/main/paradox/typed/cluster.md b/docs/src/main/paradox/typed/cluster.md index d64dec151d..1f8bab64bb 100644 --- a/docs/src/main/paradox/typed/cluster.md +++ b/docs/src/main/paradox/typed/cluster.md @@ -1,9 +1,9 @@ --- -project.description: Build distributed applications that scale across the network with Pekko Cluster, a fault-tolerant decentralized peer-to-peer based cluster node membership service with no single point of failure. +project.description: Build distributed applications that scale across the network with Apache Pekko Cluster, a fault-tolerant decentralized peer-to-peer based cluster node membership service with no single point of failure. --- # Cluster Usage -This document describes how to use Pekko Cluster and the Cluster APIs. +This document describes how to use Apache Pekko Cluster and the Cluster APIs. For specific documentation topics see: diff --git a/docs/src/main/paradox/typed/dispatchers.md b/docs/src/main/paradox/typed/dispatchers.md index 39c963a568..1349cedb66 100644 --- a/docs/src/main/paradox/typed/dispatchers.md +++ b/docs/src/main/paradox/typed/dispatchers.md @@ -1,5 +1,5 @@ --- -project.description: Pekko dispatchers and how to choose the right ones. +project.description: Apache Pekko dispatchers and how to choose the right ones. --- # Dispatchers diff --git a/docs/src/main/paradox/typed/distributed-data.md b/docs/src/main/paradox/typed/distributed-data.md index 60891c58a6..cfd9db42a6 100644 --- a/docs/src/main/paradox/typed/distributed-data.md +++ b/docs/src/main/paradox/typed/distributed-data.md @@ -1,5 +1,5 @@ --- -project.description: Share data between nodes and perform updates without coordination in a Pekko Cluster using Conflict Free Replicated Data Types CRDT. +project.description: Share data between nodes and perform updates without coordination in a Apache Pekko Cluster using Conflict Free Replicated Data Types CRDT. --- # Distributed Data @@ -737,7 +737,7 @@ duration its data should first be manually removed (from the lmdb directory). There are some limitations that you should be aware of. CRDTs cannot be used for all types of problems, and eventual consistency does not fit -all domains. Sometimes you need strong consistency. +all domains. Sometimes, you need strong consistency. It is not intended for *Big Data*. The number of top level entries should not exceed 100000. When a new node is added to the cluster all these entries are transferred (gossiped) to the diff --git a/docs/src/main/paradox/typed/durable-state/persistence-style.md b/docs/src/main/paradox/typed/durable-state/persistence-style.md index f9d8a89dd5..144db6dce4 100644 --- a/docs/src/main/paradox/typed/durable-state/persistence-style.md +++ b/docs/src/main/paradox/typed/durable-state/persistence-style.md @@ -15,7 +15,7 @@ in the concrete `EmptyAccount`, `OpenedAccount`, and `ClosedAccount`. ## Optional initial state -Sometimes it's not desirable to use a separate state class for the empty initial state, but rather act as if +Sometimes, it's not desirable to use a separate state class for the empty initial state, but rather act as if there is no state yet. @java[You can use `null` as the `emptyState`, but be aware of that the `state` parameter will be `null` until the first non-null state has been persisted diff --git a/docs/src/main/paradox/typed/durable-state/persistence.md b/docs/src/main/paradox/typed/durable-state/persistence.md index c62d521cba..d36bc42209 100644 --- a/docs/src/main/paradox/typed/durable-state/persistence.md +++ b/docs/src/main/paradox/typed/durable-state/persistence.md @@ -1,5 +1,5 @@ --- -project.description: Durable State with Pekko Persistence enables actors to persist its state for recovery on failure or when migrated within a cluster. +project.description: Durable State with Apache Pekko Persistence enables actors to persist its state for recovery on failure or when migrated within a cluster. --- # Durable State @@ -51,7 +51,7 @@ Java : @@snip [DurableStatePersistentBehaviorTest.java](/persistence-typed/src/test/java/jdocs/org/apache/pekko/persistence/typed/DurableStatePersistentBehaviorTest.java) { #structure } The first important thing to notice is the `Behavior` of a persistent actor is typed to the type of the `Command` -because this is the type of message a persistent actor should receive. In Pekko this is now enforced by the type system. +because this is the type of message a persistent actor should receive. In Pekko, this is now enforced by the type system. The components that make up a `DurableStateBehavior` are: diff --git a/docs/src/main/paradox/typed/fault-tolerance.md b/docs/src/main/paradox/typed/fault-tolerance.md index 3108498314..939382507d 100644 --- a/docs/src/main/paradox/typed/fault-tolerance.md +++ b/docs/src/main/paradox/typed/fault-tolerance.md @@ -28,7 +28,7 @@ with a fresh state that we know is valid. ## Supervision -In Pekko this "somewhere else" is called supervision. Supervision allows you to declaratively describe what should happen when certain types of exceptions are thrown inside an actor. +In Pekko, this "somewhere else" is called supervision. Supervision allows you to declaratively describe what should happen when certain types of exceptions are thrown inside an actor. The default @ref:[supervision](../general/supervision.md) strategy is to stop the actor if an exception is thrown. In many cases you will want to further customize this behavior. To use supervision the actual Actor behavior is wrapped using @apidoc[Behaviors.supervise](typed.*.Behaviors$) {scala="#supervise[T](wrapped:org.apache.pekko.actor.typed.Behavior[T]):org.apache.pekko.actor.typed.scaladsl.Behaviors.Supervise[T]" java="#supervise(org.apache.pekko.actor.typed.Behavior)"}. diff --git a/docs/src/main/paradox/typed/from-classic.md b/docs/src/main/paradox/typed/from-classic.md index 0fd2f9bc79..21ab456fe5 100644 --- a/docs/src/main/paradox/typed/from-classic.md +++ b/docs/src/main/paradox/typed/from-classic.md @@ -342,7 +342,7 @@ Starting an actor on a remote node—so called remote deployment—isn't support This feature would be discouraged because it often results in tight coupling between nodes and undesirable failure handling. For example if the node of the parent actor crashes, all remote deployed child actors are -brought down with it. Sometimes that can be desired but many times it is used without realizing. This can be +brought down with it. Sometimes, that can be desired but many times it is used without realizing. This can be achieved by other means, such as using `watch`. ## Routers diff --git a/docs/src/main/paradox/typed/fsm.md b/docs/src/main/paradox/typed/fsm.md index 8a2950f0c3..0a34ea8f29 100644 --- a/docs/src/main/paradox/typed/fsm.md +++ b/docs/src/main/paradox/typed/fsm.md @@ -1,5 +1,5 @@ --- -project.description: Finite State Machines (FSM) with Pekko Actors. +project.description: Finite State Machines (FSM) with Apache Pekko Actors. --- # Behaviors as finite state machines diff --git a/docs/src/main/paradox/typed/index-cluster.md b/docs/src/main/paradox/typed/index-cluster.md index ed47a804c8..5b16cdb615 100644 --- a/docs/src/main/paradox/typed/index-cluster.md +++ b/docs/src/main/paradox/typed/index-cluster.md @@ -1,5 +1,5 @@ --- -project.description: Pekko Cluster concepts, node membership service, CRDT Distributed Data, Cluster Singleton, Cluster Sharding, and Pekko Cluster across multiple datacenters. +project.description: Apache Pekko Cluster concepts, node membership service, CRDT Distributed Data, Cluster Singleton, Cluster Sharding, and Pekko Cluster across multiple datacenters. --- # Cluster diff --git a/docs/src/main/paradox/typed/index-persistence-durable-state.md b/docs/src/main/paradox/typed/index-persistence-durable-state.md index c9754a9062..f96fe1eb92 100644 --- a/docs/src/main/paradox/typed/index-persistence-durable-state.md +++ b/docs/src/main/paradox/typed/index-persistence-durable-state.md @@ -1,5 +1,5 @@ --- -project.description: Durable state with Pekko Persistence enables actors to persist the latest version of the state. This persistence is used for recovery on failure, or when migrating within a cluster. +project.description: Durable state with Apache Pekko Persistence enables actors to persist the latest version of the state. This persistence is used for recovery on failure, or when migrating within a cluster. --- # Persistence (Durable State) diff --git a/docs/src/main/paradox/typed/index-persistence.md b/docs/src/main/paradox/typed/index-persistence.md index b2d09035fa..659711da44 100644 --- a/docs/src/main/paradox/typed/index-persistence.md +++ b/docs/src/main/paradox/typed/index-persistence.md @@ -1,5 +1,5 @@ --- -project.description: Use of Pekko Persistence with Event Sourcing enables actors to persist your events for recovery on failure or when migrated within a cluster. +project.description: Use of Apache Pekko Persistence with Event Sourcing enables actors to persist your events for recovery on failure or when migrated within a cluster. --- # Persistence (Event Sourcing) diff --git a/docs/src/main/paradox/typed/index.md b/docs/src/main/paradox/typed/index.md index 0069e859e3..e0b096faa8 100644 --- a/docs/src/main/paradox/typed/index.md +++ b/docs/src/main/paradox/typed/index.md @@ -1,5 +1,5 @@ --- -project.description: Using Pekko to build reliable multi-core applications distributed across a network that scale up and scale out. +project.description: Using Apache Pekko to build reliable multi-core applications distributed across a network that scale up and scale out. --- # Actors diff --git a/docs/src/main/paradox/typed/interaction-patterns.md b/docs/src/main/paradox/typed/interaction-patterns.md index acb733ee5c..4a351bc507 100644 --- a/docs/src/main/paradox/typed/interaction-patterns.md +++ b/docs/src/main/paradox/typed/interaction-patterns.md @@ -64,7 +64,7 @@ Java Many interactions between actors require one or more response message being sent back from the receiving actor. A response message can be a result of a query, some form of acknowledgment that the message was received and processed or events that the request subscribed to. -In Pekko the recipient of responses has to be encoded as a field in the message itself, which the recipient can then use to send (tell) a response back. +In Pekko, the recipient of responses has to be encoded as a field in the message itself, which the recipient can then use to send (tell) a response back. **Example:** @@ -195,7 +195,7 @@ The response adapting function is running in the receiving actor and can safely ## Request-Response with ask from outside an Actor -Sometimes you need to interact with actors from the outside of the actor system, this can be done with fire-and-forget as described above or through another version of `ask` that returns a @scala[@scaladoc[Future[Response]](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.CompletionStage)] that is either completed with a successful response or failed with a @javadoc[TimeoutException](java.util.concurrent.TimeoutException) if there was no response within the specified timeout. +Sometimes, you need to interact with actors from the outside of the actor system, this can be done with fire-and-forget as described above or through another version of `ask` that returns a @scala[@scaladoc[Future[Response]](scala.concurrent.Future)]@java[@javadoc[CompletionStage](java.util.concurrent.CompletionStage)] that is either completed with a successful response or failed with a @javadoc[TimeoutException](java.util.concurrent.TimeoutException) if there was no response within the specified timeout. @scala[To do this we use `ask` (or the symbolic `?`) implicitly added to @scaladoc[ActorRef](pekko.actor.typed.ActorRef) by `org.apache.pekko.actor.typed.scaladsl.AskPattern._` to send a message to an actor and get a `Future[Response]` back. `ask` takes implicit @scaladoc[Timeout](pekko.util.Timeout) and @scaladoc[ActorSystem](org.apache.pekko.actor.typed.ActorSystem) parameters.] @@ -373,7 +373,7 @@ In an actual session child you would likely want to include some form of timeout ## General purpose response aggregator -This is similar to above @ref:[Per session child Actor](#per-session-child-actor) pattern. Sometimes you might +This is similar to above @ref:[Per session child Actor](#per-session-child-actor) pattern. Sometimes, you might end up repeating the same way of aggregating replies and want to extract that to a reusable actor. There are many variations of this pattern and that is the reason this is provided as a documentation diff --git a/docs/src/main/paradox/typed/logging.md b/docs/src/main/paradox/typed/logging.md index da6a9288ff..67aa5486fb 100644 --- a/docs/src/main/paradox/typed/logging.md +++ b/docs/src/main/paradox/typed/logging.md @@ -1,5 +1,5 @@ --- -project.description: Logging options with Pekko. +project.description: Logging options with Apache Pekko. --- # Logging diff --git a/docs/src/main/paradox/typed/persistence-snapshot.md b/docs/src/main/paradox/typed/persistence-snapshot.md index 0b57b82371..e20a5cecfa 100644 --- a/docs/src/main/paradox/typed/persistence-snapshot.md +++ b/docs/src/main/paradox/typed/persistence-snapshot.md @@ -1,5 +1,5 @@ --- -project.description: Append only event logs, snapshots and recovery with Pekko event sourced actors. +project.description: Append only event logs, snapshots and recovery with Apache Pekko event sourced actors. --- # Snapshotting diff --git a/docs/src/main/paradox/typed/persistence-style.md b/docs/src/main/paradox/typed/persistence-style.md index c08f802643..1ec1bb4ce3 100644 --- a/docs/src/main/paradox/typed/persistence-style.md +++ b/docs/src/main/paradox/typed/persistence-style.md @@ -39,7 +39,7 @@ in the concrete `EmptyAccount`, `OpenedAccount`, and `ClosedAccount`. ## Optional initial state -Sometimes it's not desirable to use a separate state class for the empty initial state, but rather treat that as +Sometimes, it's not desirable to use a separate state class for the empty initial state, but rather treat that as there is no state yet. @java[`null` can then be used as the `emptyState`, but be aware of that the `state` parameter will then be `null` for the first commands and events until the first event has be persisted to create the diff --git a/docs/src/main/paradox/typed/persistence.md b/docs/src/main/paradox/typed/persistence.md index 4921e888c2..16052690d0 100644 --- a/docs/src/main/paradox/typed/persistence.md +++ b/docs/src/main/paradox/typed/persistence.md @@ -1,5 +1,5 @@ --- -project.description: Event Sourcing with Pekko Persistence enables actors to persist your events for recovery on failure or when migrated within a cluster. +project.description: Event Sourcing with Apache Pekko Persistence enables actors to persist your events for recovery on failure or when migrated within a cluster. --- # Event Sourcing @@ -81,7 +81,7 @@ Java : @@snip [BasicPersistentBehaviorTest.java](/persistence-typed/src/test/java/jdocs/org/apache/pekko/persistence/typed/BasicPersistentBehaviorTest.java) { #structure } The first important thing to notice is the @apidoc[typed.Behavior] of a persistent actor is typed to the type of the `Command` -because this is the type of message a persistent actor should receive. In Pekko this is now enforced by the type system. +because this is the type of message a persistent actor should receive. In Pekko, this is now enforced by the type system. The components that make up an @apidoc[typed.*.EventSourcedBehavior] are: diff --git a/docs/src/main/paradox/typed/replicated-eventsourcing.md b/docs/src/main/paradox/typed/replicated-eventsourcing.md index 99b2d3b3da..2d24616cb8 100644 --- a/docs/src/main/paradox/typed/replicated-eventsourcing.md +++ b/docs/src/main/paradox/typed/replicated-eventsourcing.md @@ -165,7 +165,7 @@ rules can be used to implement an entity with CRDT semantics. ### Last writer wins -Sometimes it is enough to use timestamps to decide which update should win. Such approach relies on synchronized clocks, and clocks of different machines will always be slightly out of sync. Timestamps should therefore only be used when the choice of value is not important for concurrent updates occurring within the clock skew. +Sometimes, it is enough to use timestamps to decide which update should win. Such approach relies on synchronized clocks, and clocks of different machines will always be slightly out of sync. Timestamps should therefore only be used when the choice of value is not important for concurrent updates occurring within the clock skew. In general, last writer wins means that the event is used if the timestamp of the event is later (higher) than the timestamp of previous local update, otherwise the event is discarded. There is no built-in support for last writer wins, because it must often be combined with more application specific aspects. diff --git a/docs/src/main/paradox/typed/style-guide.md b/docs/src/main/paradox/typed/style-guide.md index 41a70f5f3b..b7eb499456 100644 --- a/docs/src/main/paradox/typed/style-guide.md +++ b/docs/src/main/paradox/typed/style-guide.md @@ -391,7 +391,7 @@ Scala : @@snip [StyleGuideDocExamples.scala](/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/StyleGuideDocExamples.scala) { #pattern-match-unhandled } It's recommended to use the `sealed` trait and total functions with exhaustiveness check to detect mistakes -of forgetting to handle some messages. Sometimes that can be inconvenient and then you can use a `PartialFunction` +of forgetting to handle some messages. Sometimes, that can be inconvenient and then you can use a `PartialFunction` with `Behaviors.receivePartial` or `Behaviors.receiveMessagePartial` Scala