raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

Use sbt-paradox-apidoc plugin (#26660)

Browse source 
Instead of using custom code here. Checked with 'meld' that the result
is the same, except for problems that were already there (filed #26659).
This commit is contained in:
Arnout Engelen 2019-04-03 13:14:27 +02:00 • committed by GitHub
parent 76479b8770
commit abbbfb5b54
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 78 additions and 135 deletions
Download patch file Download diff file Expand all files Collapse all files

54
akka-docs/src/main/paradox/cluster-client.md
View file

@ -13,15 +13,15 @@ To use Cluster Client, you must add the following dependency in your project:
## Introduction
An actor system that is not part of the cluster can communicate with actors
somewhere in the cluster via the @unidoc[ClusterClient], the client can run in an `ActorSystem` that is part of
somewhere in the cluster via the @apidoc[ClusterClient], the client can run in an `ActorSystem` that is part of
another cluster. It only needs to know the location of one (or more) nodes to use as initial
contact points. It will establish a connection to a @unidoc[akka.cluster.client.ClusterReceptionist] somewhere in
contact points. It will establish a connection to a @apidoc[akka.cluster.client.ClusterReceptionist] somewhere in
the cluster. It will monitor the connection to the receptionist and establish a new
connection if the link goes down. When looking for a new receptionist it uses fresh
contact points retrieved from previous establishment, or periodically refreshed contacts,
i.e. not necessarily the initial contact points.
Using the @unidoc[ClusterClient] for communicating with a cluster from the outside requires that the system with the client
Using the @apidoc[ClusterClient] for communicating with a cluster from the outside requires that the system with the client
can both connect and be connected to with Akka Remoting from all the nodes in the cluster with a receptionist.
This creates a tight coupling in that the client and cluster systems may need to have the same version of
both Akka, libraries, message classes, serializers and potentially even the JVM. In many cases it is a better solution
@ -29,11 +29,11 @@ to use a more explicit and decoupling protocol such as [HTTP](https://doc.akka.i
[gRPC](https://developer.lightbend.com/docs/akka-grpc/current/).
Additionally since Akka Remoting is primarily designed as a protocol for Akka Cluster there is no explicit resource
management, when a @unidoc[ClusterClient] has been used it will cause connections with the cluster until the ActorSystem is
management, when a @apidoc[ClusterClient] has been used it will cause connections with the cluster until the ActorSystem is
stopped (unlike other kinds of network clients).
@unidoc[ClusterClient] should not be used when sending messages to actors that run
within the same cluster. Similar functionality as the @unidoc[ClusterClient] is
@apidoc[ClusterClient] should not be used when sending messages to actors that run
within the same cluster. Similar functionality as the @apidoc[ClusterClient] is
provided in a more efficient way by @ref:[Distributed Publish Subscribe in Cluster](distributed-pub-sub.md) for actors that
belong to the same cluster.
@ -41,23 +41,23 @@ It is necessary that the connecting system has its `akka.actor.provider` set to
the cluster client.
The receptionist is supposed to be started on all nodes, or all nodes with specified role,
in the cluster. The receptionist can be started with the @unidoc[akka.cluster.client.ClusterReceptionist] extension
in the cluster. The receptionist can be started with the @apidoc[akka.cluster.client.ClusterReceptionist] extension
or as an ordinary actor.
You can send messages via the @unidoc[ClusterClient] to any actor in the cluster that is registered
in the @unidoc[DistributedPubSubMediator] used by the @unidoc[akka.cluster.client.ClusterReceptionist].
The @unidoc[ClusterClientReceptionist] provides methods for registration of actors that
You can send messages via the @apidoc[ClusterClient] to any actor in the cluster that is registered
in the @apidoc[DistributedPubSubMediator] used by the @apidoc[akka.cluster.client.ClusterReceptionist].
The @apidoc[ClusterClientReceptionist] provides methods for registration of actors that
should be reachable from the client. Messages are wrapped in `ClusterClient.Send`,
@scala[@scaladoc[`ClusterClient.SendToAll`](akka.cluster.client.ClusterClient$)]@java[`ClusterClient.SendToAll`] or @scala[@scaladoc[`ClusterClient.Publish`](akka.cluster.client.ClusterClient$)]@java[`ClusterClient.Publish`].
Both the @unidoc[ClusterClient] and the @unidoc[ClusterClientReceptionist] emit events that can be subscribed to.
The @unidoc[ClusterClient] sends out notifications in relation to having received a list of contact points
from the @unidoc[ClusterClientReceptionist]. One use of this list might be for the client to record its
Both the @apidoc[ClusterClient] and the @apidoc[ClusterClientReceptionist] emit events that can be subscribed to.
The @apidoc[ClusterClient] sends out notifications in relation to having received a list of contact points
from the @apidoc[ClusterClientReceptionist]. One use of this list might be for the client to record its
contact points. A client that is restarted could then use this information to supersede any previously
configured contact points.
The @unidoc[ClusterClientReceptionist] sends out notifications in relation to having received a contact
from a @unidoc[ClusterClient]. This notification enables the server containing the receptionist to become aware of
The @apidoc[ClusterClientReceptionist] sends out notifications in relation to having received a contact
from a @apidoc[ClusterClient]. This notification enables the server containing the receptionist to become aware of
what clients are connected.
1. **ClusterClient.Send**
@ -86,13 +86,13 @@ to avoid inbound connections from other cluster nodes to the client:
* @scala[@scaladoc[`sender()`](akka.actor.Actor)] @java[@javadoc[`getSender()`](akka.actor.Actor)] of the response messages, sent back from the destination and seen by the client,
is `deadLetters`
since the client should normally send subsequent messages via the @unidoc[ClusterClient].
since the client should normally send subsequent messages via the @apidoc[ClusterClient].
It is possible to pass the original sender inside the reply messages if
the client is supposed to communicate directly to the actor in the cluster.
While establishing a connection to a receptionist the @unidoc[ClusterClient] will buffer
While establishing a connection to a receptionist the @apidoc[ClusterClient] will buffer
messages and send them when the connection is established. If the buffer is full
the @unidoc[ClusterClient] will drop old messages when new messages are sent via the client.
the @apidoc[ClusterClient] will drop old messages when new messages are sent via the client.
The size of the buffer is configurable and it can be disabled by using a buffer size of 0.
It's worth noting that messages can always be lost because of the distributed nature
@ -116,7 +116,7 @@ Scala
Java
: @@snip [ClusterClientTest.java](/akka-cluster-tools/src/test/java/akka/cluster/client/ClusterClientTest.java) { #server }
On the client you create the @unidoc[ClusterClient] actor and use it as a gateway for sending
On the client you create the @apidoc[ClusterClient] actor and use it as a gateway for sending
messages to the actors identified by their path (without address information) somewhere
in the cluster.
@ -148,7 +148,7 @@ That is convenient and perfectly fine in most cases, but it can be good to know
start the `akka.cluster.client.ClusterReceptionist` actor as an ordinary actor and you can have several
different receptionists at the same time, serving different types of clients.
Note that the @unidoc[ClusterClientReceptionist] uses the @unidoc[DistributedPubSub] extension, which is described
Note that the @apidoc[ClusterClientReceptionist] uses the @apidoc[DistributedPubSub] extension, which is described
in @ref:[Distributed Publish Subscribe in Cluster](distributed-pub-sub.md).
It is recommended to load the extension when the actor system is started by defining it in the
@ -160,9 +160,9 @@ akka.extensions = ["akka.cluster.client.ClusterClientReceptionist"]
## Events
As mentioned earlier, both the @unidoc[ClusterClient] and @unidoc[ClusterClientReceptionist] emit events that can be subscribed to.
As mentioned earlier, both the @apidoc[ClusterClient] and @apidoc[ClusterClientReceptionist] emit events that can be subscribed to.
The following code snippet declares an actor that will receive notifications on contact points (addresses to the available
receptionists), as they become available. The code illustrates subscribing to the events and receiving the @unidoc[ClusterClient]
receptionists), as they become available. The code illustrates subscribing to the events and receiving the @apidoc[ClusterClient]
initial state.
Scala
@ -171,7 +171,7 @@ Scala
Java
: @@snip [ClusterClientTest.java](/akka-cluster-tools/src/test/java/akka/cluster/client/ClusterClientTest.java) { #clientEventsListener }
Similarly we can have an actor that behaves in a similar fashion for learning what cluster clients are connected to a @unidoc[ClusterClientReceptionist]:
Similarly we can have an actor that behaves in a similar fashion for learning what cluster clients are connected to a @apidoc[ClusterClientReceptionist]:
Scala
: @@snip [ClusterClientSpec.scala](/akka-cluster-tools/src/multi-jvm/scala/akka/cluster/client/ClusterClientSpec.scala) { #receptionistEventsListener }
@ -182,14 +182,14 @@ Java
<a id="cluster-client-config"></a>
## Configuration
The @unidoc[ClusterClientReceptionist] extension (or @unidoc[akka.cluster.client.ClusterReceptionistSettings]) can be configured
The @apidoc[ClusterClientReceptionist] extension (or @apidoc[akka.cluster.client.ClusterReceptionistSettings]) can be configured
with the following properties:
@@snip [reference.conf](/akka-cluster-tools/src/main/resources/reference.conf) { #receptionist-ext-config }
The following configuration properties are read by the @unidoc[ClusterClientSettings]
when created with a @scala[@scaladoc[`ActorSystem`](akka.actor.ActorSystem)]@java[@javadoc[`ActorSystem`](akka.actor.ActorSystem)] parameter. It is also possible to amend the @unidoc[ClusterClientSettings]
or create it from another config section with the same layout as below. @unidoc[ClusterClientSettings] is
The following configuration properties are read by the @apidoc[ClusterClientSettings]
when created with a @scala[@scaladoc[`ActorSystem`](akka.actor.ActorSystem)]@java[@javadoc[`ActorSystem`](akka.actor.ActorSystem)] parameter. It is also possible to amend the @apidoc[ClusterClientSettings]
or create it from another config section with the same layout as below. @apidoc[ClusterClientSettings] is
a parameter to the @scala[@scaladoc[`ClusterClient.props`](akka.cluster.client.ClusterClient$)]@java[@javadoc[`ClusterClient.props`](akka.cluster.client.ClusterClient$)] factory method, i.e. each client can be configured
with different settings if needed.