=doc cluster client: Introduce javadoc and scaladoc directives (#24524)
This commit is contained in:
Richard Imaoka
Konrad `ktoso` Malawski
parent
7630939b18
commit
caabfdecfc
1 changed files with 29 additions and 29 deletions
|
|
@ -1,9 +1,9 @@
|
|||
# Cluster Client
|
||||
|
||||
An actor system that is not part of the cluster can communicate with actors
|
||||
somewhere in the cluster via this `ClusterClient`. The client can of course be part of
|
||||
somewhere in the cluster via this @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)]. The client can of course be 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 `ClusterReceptionist` somewhere in
|
||||
contact points. It will establish a connection to a @scala[@scaladoc[`ClusterReceptionist`](akka.cluster.client.ClusterReceptionist)]@java[@javadoc[`ClusterReceptionist`](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,
|
||||
|
|
@ -11,8 +11,8 @@ i.e. not necessarily the initial contact points.
|
|||
|
||||
@@@ note
|
||||
|
||||
`ClusterClient` should not be used when sending messages to actors that run
|
||||
within the same cluster. Similar functionality as the `ClusterClient` is
|
||||
@scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)] should not be used when sending messages to actors that run
|
||||
within the same cluster. Similar functionality as the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.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.
|
||||
|
||||
|
|
@ -23,23 +23,23 @@ to `remote` or `cluster` when using
|
|||
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 `ClusterClientReceptionist` extension
|
||||
in the cluster. The receptionist can be started with the @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)] extension
|
||||
or as an ordinary actor.
|
||||
|
||||
You can send messages via the `ClusterClient` to any actor in the cluster that is registered
|
||||
in the `DistributedPubSubMediator` used by the `ClusterReceptionist`.
|
||||
The `ClusterClientReceptionist` provides methods for registration of actors that
|
||||
You can send messages via the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)] to any actor in the cluster that is registered
|
||||
in the @scala[@scaladoc[`DistributedPubSubMediator`](akka.cluster.pubsub.DistributedPubSubMediator)]@java[@javadoc[`DistributedPubSubMediator`](akka.cluster.pubsub.DistributedPubSubMediator)] used by the @scala[@scaladoc[`ClusterReceptionist`](akka.cluster.client.ClusterReceptionist)]@java[@javadoc[`ClusterReceptionist`](akka.cluster.client.ClusterReceptionist)].
|
||||
The @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)] provides methods for registration of actors that
|
||||
should be reachable from the client. Messages are wrapped in `ClusterClient.Send`,
|
||||
`ClusterClient.SendToAll` or `ClusterClient.Publish`.
|
||||
@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 `ClusterClient` and the `ClusterClientReceptionist` emit events that can be subscribed to.
|
||||
The `ClusterClient` sends out notifications in relation to having received a list of contact points
|
||||
from the `ClusterClientReceptionist`. One use of this list might be for the client to record its
|
||||
Both the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)] and the @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClient)] emit events that can be subscribed to.
|
||||
The @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)] sends out notifications in relation to having received a list of contact points
|
||||
from the @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.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 `ClusterClientReceptionist` sends out notifications in relation to having received a contact
|
||||
from a `ClusterClient`. This notification enables the server containing the receptionist to become aware of
|
||||
The @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)] sends out notifications in relation to having received a contact
|
||||
from a @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)]. This notification enables the server containing the receptionist to become aware of
|
||||
what clients are connected.
|
||||
|
||||
1. **ClusterClient.Send**
|
||||
|
|
@ -63,18 +63,18 @@ what clients are connected.
|
|||
Response messages from the destination actor are tunneled via the receptionist
|
||||
to avoid inbound connections from other cluster nodes to the client:
|
||||
|
||||
* @scala[`sender()`,] @java[`getSender()`,] as seen by the destination actor, is not the client itself,
|
||||
* @scala[@scaladoc[`sender()`](akka.actor.Actor)]@java[@javadoc[`getSender()`](akka.actor.Actor)], as seen by the destination actor, is not the client itself,
|
||||
but the receptionist
|
||||
* @scala[`sender()`] @java[`getSender()`] of the response messages, sent back from the destination and seen by 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 `ClusterClient`.
|
||||
since the client should normally send subsequent messages via the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.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 `ClusterClient` will buffer
|
||||
While establishing a connection to a receptionist the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)] will buffer
|
||||
messages and send them when the connection is established. If the buffer is full
|
||||
the `ClusterClient` will drop old messages when new messages are sent via the client.
|
||||
the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.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
|
||||
|
|
@ -98,7 +98,7 @@ Scala
|
|||
Java
|
||||
: @@snip [ClusterClientTest.java]($akka$/akka-cluster-tools/src/test/java/akka/cluster/client/ClusterClientTest.java) { #server }
|
||||
|
||||
On the client you create the `ClusterClient` actor and use it as a gateway for sending
|
||||
On the client you create the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.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.
|
||||
|
||||
|
|
@ -130,7 +130,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 `ClusterClientReceptionist` uses the `DistributedPubSub` extension, which is described
|
||||
Note that the @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)] uses the @scala[@scaladoc[`DistributedPubSub`](akka.cluster.pubsub.DistributedPubSub)]@java[@javadoc[`DistributedPubSub`](akka.cluster.pubsub.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
|
||||
|
|
@ -142,9 +142,9 @@ akka.extensions = ["akka.cluster.client.ClusterClientReceptionist"]
|
|||
|
||||
## Events
|
||||
|
||||
As mentioned earlier, both the `ClusterClient` and `ClusterClientReceptionist` emit events that can be subscribed to.
|
||||
As mentioned earlier, both the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)] and @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.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 `ClusterClient`
|
||||
receptionists), as they become available. The code illustrates subscribing to the events and receiving the @scala[@scaladoc[`ClusterClient`](akka.cluster.client.ClusterClient)]@java[@javadoc[`ClusterClient`](akka.cluster.client.ClusterClient)]
|
||||
initial state.
|
||||
|
||||
Scala
|
||||
|
|
@ -153,7 +153,7 @@ Scala
|
|||
Java
|
||||
: @@snip [ClusterClientTest.java]($akka$/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 `ClusterClientReceptionist`:
|
||||
Similarly we can have an actor that behaves in a similar fashion for learning what cluster clients are connected to a @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]:
|
||||
|
||||
Scala
|
||||
: @@snip [ClusterClientSpec.scala]($akka$/akka-cluster-tools/src/multi-jvm/scala/akka/cluster/client/ClusterClientSpec.scala) { #receptionistEventsListener }
|
||||
|
|
@ -186,15 +186,15 @@ Maven
|
|||
<a id="cluster-client-config"></a>
|
||||
## Configuration
|
||||
|
||||
The `ClusterClientReceptionist` extension (or `ClusterReceptionistSettings`) can be configured
|
||||
The @scala[@scaladoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)]@java[@javadoc[`ClusterClientReceptionist`](akka.cluster.client.ClusterClientReceptionist)] extension (or @scala[@scaladoc[`ClusterReceptionistSettings`](akka.cluster.client.ClusterReceptionistSettings)]@java[@javadoc[`ClusterReceptionistSettings`](akka.cluster.client.ClusterReceptionistSettings)]) can be configured
|
||||
with the following properties:
|
||||
|
||||
@@snip [reference.conf]($akka$/akka-cluster-tools/src/main/resources/reference.conf) { #receptionist-ext-config }
|
||||
|
||||
The following configuration properties are read by the `ClusterClientSettings`
|
||||
when created with a `ActorSystem` parameter. It is also possible to amend the `ClusterClientSettings`
|
||||
or create it from another config section with the same layout as below. `ClusterClientSettings` is
|
||||
a parameter to the `ClusterClient.props` factory method, i.e. each client can be configured
|
||||
The following configuration properties are read by the @scala[@scaladoc[`ClusterClientSettings`](akka.cluster.client.ClusterClientSettings)]@java[@javadoc[`ClusterClientSettings`](akka.cluster.client.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 @scala[@scaladoc[`ClusterClientSettings`](akka.cluster.client.ClusterClientSettings)]@java[@javadoc[`ClusterClientSettings`](akka.cluster.client.ClusterClientSettings)]
|
||||
or create it from another config section with the same layout as below. @scala[@scaladoc[`ClusterClientSettings`](akka.cluster.client.ClusterClientSettings)]@java[@javadoc[`ClusterClientSettings`](akka.cluster.client.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.
|
||||
|
||||
@@snip [reference.conf]($akka$/akka-cluster-tools/src/main/resources/reference.conf) { #cluster-client-config }
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue