From 91412a69088a66b3ac18563f61fd8d711d2e0b45 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Fri, 5 Jul 2013 12:46:39 +0200 Subject: [PATCH 1/2] Fix scaladoc warnings in akka-actor, see #3152 * also change wrong visibility of SystemMessage subclasses --- .../src/main/scala/akka/actor/ActorDSL.scala | 2 +- .../src/main/scala/akka/actor/ActorRef.scala | 2 +- .../main/scala/akka/actor/DynamicAccess.scala | 5 +- .../src/main/scala/akka/actor/FSM.scala | 14 ++--- .../main/scala/akka/actor/FaultHandling.scala | 2 +- .../src/main/scala/akka/actor/Props.scala | 6 +- .../akka/dispatch/sysmsg/SystemMessage.scala | 14 ++--- akka-actor/src/main/scala/akka/io/Inet.scala | 24 +++---- .../src/main/scala/akka/io/Pipelines.scala | 20 +++--- .../main/scala/akka/io/SslTlsSupport.scala | 2 +- akka-actor/src/main/scala/akka/io/Tcp.scala | 62 +++++++++---------- .../scala/akka/io/TcpPipelineHandler.scala | 8 +-- akka-actor/src/main/scala/akka/io/Udp.scala | 34 +++++----- .../src/main/scala/akka/io/UdpConnected.scala | 26 ++++---- .../main/scala/akka/pattern/AskSupport.scala | 4 +- .../routing/ConsistentHashingRouter.scala | 9 +-- 16 files changed, 117 insertions(+), 117 deletions(-) diff --git a/akka-actor/src/main/scala/akka/actor/ActorDSL.scala b/akka-actor/src/main/scala/akka/actor/ActorDSL.scala index 182d65a26b..7692f28664 100644 --- a/akka-actor/src/main/scala/akka/actor/ActorDSL.scala +++ b/akka-actor/src/main/scala/akka/actor/ActorDSL.scala @@ -118,7 +118,7 @@ abstract class Inbox { * Receive the next message from this Inbox. This call will return immediately * if the internal actor previously received a message, or it will block for * up to the specified duration to await reception of a message. If no message - * is received a [[TimeoutException]] will be raised. + * is received a [[java.util.concurrent.TimeoutException]] will be raised. */ def receive(max: FiniteDuration): Any diff --git a/akka-actor/src/main/scala/akka/actor/ActorRef.scala b/akka-actor/src/main/scala/akka/actor/ActorRef.scala index 11c762ac7a..d7bcf02b76 100644 --- a/akka-actor/src/main/scala/akka/actor/ActorRef.scala +++ b/akka-actor/src/main/scala/akka/actor/ActorRef.scala @@ -16,7 +16,7 @@ import akka.event.LoggingAdapter object ActorRef { /** - * Use this value as an argument to [[#tell]] if there is not actor to + * Use this value as an argument to [[ActorRef#tell]] if there is not actor to * reply to (e.g. when sending from non-actor code). */ final val noSender: ActorRef = Actor.noSender diff --git a/akka-actor/src/main/scala/akka/actor/DynamicAccess.scala b/akka-actor/src/main/scala/akka/actor/DynamicAccess.scala index 9d865b7da9..91decec249 100644 --- a/akka-actor/src/main/scala/akka/actor/DynamicAccess.scala +++ b/akka-actor/src/main/scala/akka/actor/DynamicAccess.scala @@ -55,11 +55,10 @@ abstract class DynamicAccess { } /** - * This is the default [[akka.actor.DynamicAccess]] implementation used by [[akka.actor.ActorSystemImpl]] + * This is the default [[akka.actor.DynamicAccess]] implementation used by [[akka.actor.ExtendedActorSystem]] * unless overridden. It uses reflection to turn fully-qualified class names into `Class[_]` objects * and creates instances from there using `getDeclaredConstructor()` and invoking that. The class loader - * to be used for all this is determined by the [[akka.actor.ActorSystemImpl]]’s `findClassLoader` method - * by default. + * to be used for all this is determined by the actor system’s class loader by default. */ class ReflectiveDynamicAccess(val classLoader: ClassLoader) extends DynamicAccess { diff --git a/akka-actor/src/main/scala/akka/actor/FSM.scala b/akka-actor/src/main/scala/akka/actor/FSM.scala index f521c77d53..7bb63f00f8 100644 --- a/akka-actor/src/main/scala/akka/actor/FSM.scala +++ b/akka-actor/src/main/scala/akka/actor/FSM.scala @@ -27,27 +27,27 @@ object FSM { /** * Message type which is sent directly to the subscribed actor in - * [[akka.actor.FSM.SubscribeTransitionCallback]] before sending any + * [[akka.actor.FSM.SubscribeTransitionCallBack]] before sending any * [[akka.actor.FSM.Transition]] messages. */ case class CurrentState[S](fsmRef: ActorRef, state: S) /** * Message type which is used to communicate transitions between states to - * all subscribed listeners (use [[akka.actor.FSM.SubscribeTransitionCallback]]). + * all subscribed listeners (use [[akka.actor.FSM.SubscribeTransitionCallBack]]). */ case class Transition[S](fsmRef: ActorRef, from: S, to: S) /** - * Send this to an [[akka.actor.FSM]] to request first the [[akka.actor.CurrentState]] - * and then a series of [[akka.actor.Transition]] updates. Cancel the subscription - * using [[akka.actor.FSM.UnsubscribeTransitionCallback]]. + * Send this to an [[akka.actor.FSM]] to request first the [[FSM.CurrentState]] + * and then a series of [[FSM.Transition]] updates. Cancel the subscription + * using [[FSM.UnsubscribeTransitionCallBack]]. */ case class SubscribeTransitionCallBack(actorRef: ActorRef) /** * Unsubscribe from [[akka.actor.FSM.Transition]] notifications which was - * effected by sending the corresponding [[akka.actor.FSM.SubscribeTransitionCallback]]. + * effected by sending the corresponding [[akka.actor.FSM.SubscribeTransitionCallBack]]. */ case class UnsubscribeTransitionCallBack(actorRef: ActorRef) @@ -658,7 +658,7 @@ trait FSM[S, D] extends Actor with Listeners with ActorLogging { } /** - * By default [[Failure]] is logged at error level and other reason + * By default [[FSM.Failure]] is logged at error level and other reason * types are not logged. It is possible to override this behavior. */ protected def logTermination(reason: Reason): Unit = reason match { diff --git a/akka-actor/src/main/scala/akka/actor/FaultHandling.scala b/akka-actor/src/main/scala/akka/actor/FaultHandling.scala index 99d54af15f..58dd06c5e7 100644 --- a/akka-actor/src/main/scala/akka/actor/FaultHandling.scala +++ b/akka-actor/src/main/scala/akka/actor/FaultHandling.scala @@ -156,7 +156,7 @@ object SupervisorStrategy extends SupervisorStrategyLowPriorityImplicits { * When supervisorStrategy is not specified for an actor this * [[Decider]] is used by default in the supervisor strategy. * The child will be stopped when [[akka.actor.ActorInitializationException]], - * [[akka.ActorKilledException]], or [[akka.actor.DeathPactException]] is + * [[akka.actor.ActorKilledException]], or [[akka.actor.DeathPactException]] is * thrown. It will be restarted for other `Exception` types. * The error is escalated if it's a `Throwable`, i.e. `Error`. */ diff --git a/akka-actor/src/main/scala/akka/actor/Props.scala b/akka-actor/src/main/scala/akka/actor/Props.scala index 3bd6693de8..bf2cd57f77 100644 --- a/akka-actor/src/main/scala/akka/actor/Props.scala +++ b/akka-actor/src/main/scala/akka/actor/Props.scala @@ -120,7 +120,7 @@ object Props { def create(clazz: Class[_], args: AnyRef*): Props = apply(defaultDeploy, clazz, args.toVector) /** - * Create new Props from the given [[Creator]]. + * Create new Props from the given [[akka.japi.Creator]]. */ def create[T <: Actor](creator: Creator[T]): Props = { if ((creator.getClass.getEnclosingClass ne null) && (creator.getClass.getModifiers & Modifier.STATIC) == 0) @@ -216,7 +216,7 @@ final case class Props(deploy: Deploy, clazz: Class[_], args: immutable.Seq[Any] def this(factory: UntypedActorFactory) = this(Props.defaultDeploy, classOf[UntypedActorFactoryConsumer], Vector(factory)) /** - * Java API: create Props from a given [[Class]] + * Java API: create Props from a given [[java.lang.Class]] * * @deprecated use Props.create(clazz) instead; deprecated since it duplicates * another API @@ -303,7 +303,7 @@ final case class Props(deploy: Deploy, clazz: Class[_], args: immutable.Seq[Any] /** * Obtain an upper-bound approximation of the actor class which is going to - * be created by these Props. In other words, the [[#newActor]] method will + * be created by these Props. In other words, the actor factory method will * produce an instance of this class or a subclass thereof. This is used by * the actor system to select special dispatchers or mailboxes in case * dependencies are encoded in the actor type. diff --git a/akka-actor/src/main/scala/akka/dispatch/sysmsg/SystemMessage.scala b/akka-actor/src/main/scala/akka/dispatch/sysmsg/SystemMessage.scala index 69cc1062f5..5e73fcbee0 100644 --- a/akka-actor/src/main/scala/akka/dispatch/sysmsg/SystemMessage.scala +++ b/akka-actor/src/main/scala/akka/dispatch/sysmsg/SystemMessage.scala @@ -12,7 +12,7 @@ import akka.actor.{ ActorInitializationException, InternalActorRef, ActorRef, Po * Helper companion object for [[akka.dispatch.sysmsg.LatestFirstSystemMessageList]] and * [[akka.dispatch.sysmsg.EarliestFirstSystemMessageList]] */ -object SystemMessageList { +private[akka] object SystemMessageList { final val LNil: LatestFirstSystemMessageList = new LatestFirstSystemMessageList(null) final val ENil: EarliestFirstSystemMessageList = new EarliestFirstSystemMessageList(null) @@ -33,7 +33,7 @@ object SystemMessageList { * * INTERNAL API * - * Value class supporting list operations on system messages. The `next` field of [[akka.dispatch.sysmsg.SystemMessage]] + * Value class supporting list operations on system messages. The `next` field of [[SystemMessage]] * is hidden, and can only accessed through the value classes [[akka.dispatch.sysmsg.LatestFirstSystemMessageList]] and * [[akka.dispatch.sysmsg.EarliestFirstSystemMessageList]], abstracting over the fact that system messages are the * list nodes themselves. If used properly, this stays a compile time construct without any allocation overhead. @@ -44,7 +44,7 @@ object SystemMessageList { * latest appended element. * */ -class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { +private[akka] class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { import SystemMessageList._ /** @@ -65,7 +65,7 @@ class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { /** * Gives back the list containing all the elements except the first. This operation has constant cost. * - * *Warning:* as the underlying list nodes (the [[akka.dispatch.sysmsg.SystemMessage]] instances) are mutable, care + * *Warning:* as the underlying list nodes (the [[SystemMessage]] instances) are mutable, care * should be taken when passing the tail to other methods. [[akka.dispatch.sysmsg.SystemMessage#unlink]] should be * called on the head if one wants to detach the tail permanently. */ @@ -94,7 +94,7 @@ class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { * * INTERNAL API * - * Value class supporting list operations on system messages. The `next` field of [[akka.dispatch.sysmsg.SystemMessage]] + * Value class supporting list operations on system messages. The `next` field of [[SystemMessage]] * is hidden, and can only accessed through the value classes [[akka.dispatch.sysmsg.LatestFirstSystemMessageList]] and * [[akka.dispatch.sysmsg.EarliestFirstSystemMessageList]], abstracting over the fact that system messages are the * list nodes themselves. If used properly, this stays a compile time construct without any allocation overhead. @@ -105,7 +105,7 @@ class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { * latest appended element. * */ -class EarliestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { +private[akka] class EarliestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { import SystemMessageList._ /** @@ -126,7 +126,7 @@ class EarliestFirstSystemMessageList(val head: SystemMessage) extends AnyVal { /** * Gives back the list containing all the elements except the first. This operation has constant cost. * - * *Warning:* as the underlying list nodes (the [[akka.dispatch.sysmsg.SystemMessage]] instances) are mutable, care + * *Warning:* as the underlying list nodes (the [[SystemMessage]] instances) are mutable, care * should be taken when passing the tail to other methods. [[akka.dispatch.sysmsg.SystemMessage#unlink]] should be * called on the head if one wants to detach the tail permanently. */ diff --git a/akka-actor/src/main/scala/akka/io/Inet.scala b/akka-actor/src/main/scala/akka/io/Inet.scala index e33b7ee6d1..35a14bbb76 100644 --- a/akka-actor/src/main/scala/akka/io/Inet.scala +++ b/akka-actor/src/main/scala/akka/io/Inet.scala @@ -31,7 +31,7 @@ object Inet { object SO { /** - * [[akka.io.Tcp.SocketOption]] to set the SO_RCVBUF option + * [[akka.io.Inet.SocketOption]] to set the SO_RCVBUF option * * For more information see [[java.net.Socket.setReceiveBufferSize]] */ @@ -45,7 +45,7 @@ object Inet { // server socket options /** - * [[akka.io.Tcp.SocketOption]] to enable or disable SO_REUSEADDR + * [[akka.io.Inet.SocketOption]] to enable or disable SO_REUSEADDR * * For more information see [[java.net.Socket.setReuseAddress]] */ @@ -56,7 +56,7 @@ object Inet { } /** - * [[akka.io.Tcp.SocketOption]] to set the SO_SNDBUF option. + * [[akka.io.Inet.SocketOption]] to set the SO_SNDBUF option. * * For more information see [[java.net.Socket.setSendBufferSize]] */ @@ -66,7 +66,7 @@ object Inet { } /** - * [[akka.io.Tcp.SocketOption]] to set the traffic class or + * [[akka.io.Inet.SocketOption]] to set the traffic class or * type-of-service octet in the IP header for packets sent from this * socket. * @@ -81,28 +81,28 @@ object Inet { trait SoForwarders { /** - * [[akka.io.Tcp.SocketOption]] to set the SO_RCVBUF option + * [[akka.io.Inet.SocketOption]] to set the SO_RCVBUF option * * For more information see [[java.net.Socket.setReceiveBufferSize]] */ val ReceiveBufferSize = SO.ReceiveBufferSize /** - * [[akka.io.Tcp.SocketOption]] to enable or disable SO_REUSEADDR + * [[akka.io.Inet.SocketOption]] to enable or disable SO_REUSEADDR * * For more information see [[java.net.Socket.setReuseAddress]] */ val ReuseAddress = SO.ReuseAddress /** - * [[akka.io.Tcp.SocketOption]] to set the SO_SNDBUF option. + * [[akka.io.Inet.SocketOption]] to set the SO_SNDBUF option. * * For more information see [[java.net.Socket.setSendBufferSize]] */ val SendBufferSize = SO.SendBufferSize /** - * [[akka.io.Tcp.SocketOption]] to set the traffic class or + * [[akka.io.Inet.SocketOption]] to set the traffic class or * type-of-service octet in the IP header for packets sent from this * socket. * @@ -114,28 +114,28 @@ object Inet { trait SoJavaFactories { import SO._ /** - * [[akka.io.Tcp.SocketOption]] to set the SO_RCVBUF option + * [[akka.io.Inet.SocketOption]] to set the SO_RCVBUF option * * For more information see [[java.net.Socket.setReceiveBufferSize]] */ def receiveBufferSize(size: Int) = ReceiveBufferSize(size) /** - * [[akka.io.Tcp.SocketOption]] to enable or disable SO_REUSEADDR + * [[akka.io.Inet.SocketOption]] to enable or disable SO_REUSEADDR * * For more information see [[java.net.Socket.setReuseAddress]] */ def reuseAddress(on: Boolean) = ReuseAddress(on) /** - * [[akka.io.Tcp.SocketOption]] to set the SO_SNDBUF option. + * [[akka.io.Inet.SocketOption]] to set the SO_SNDBUF option. * * For more information see [[java.net.Socket.setSendBufferSize]] */ def sendBufferSize(size: Int) = SendBufferSize(size) /** - * [[akka.io.Tcp.SocketOption]] to set the traffic class or + * [[akka.io.Inet.SocketOption]] to set the traffic class or * type-of-service octet in the IP header for packets sent from this * socket. * diff --git a/akka-actor/src/main/scala/akka/io/Pipelines.scala b/akka-actor/src/main/scala/akka/io/Pipelines.scala index 7ec0a72db0..79c785f340 100644 --- a/akka-actor/src/main/scala/akka/io/Pipelines.scala +++ b/akka-actor/src/main/scala/akka/io/Pipelines.scala @@ -148,7 +148,7 @@ abstract class AbstractPipePair[CmdAbove, CmdBelow, EvtAbove, EvtBelow] { /** * Wrap a single command for efficient return to the pipeline’s machinery. - * This method avoids allocating a [[Right]] and an [[java.lang.Iterable]] by reusing + * This method avoids allocating a [[scala.util.Right]] and an [[java.lang.Iterable]] by reusing * one such instance within the AbstractPipePair, hence it can be used ONLY ONCE by * each pipeline stage. Prototypic and safe usage looks like this: * @@ -166,7 +166,7 @@ abstract class AbstractPipePair[CmdAbove, CmdBelow, EvtAbove, EvtBelow] { /** * Wrap a single event for efficient return to the pipeline’s machinery. - * This method avoids allocating a [[Left]] and an [[Iterable]] by reusing + * This method avoids allocating a [[scala.util.Left]] and an [[java.lang.Iterable]] by reusing * one such instance within the AbstractPipePair, hence it can be used ONLY ONCE by * each pipeline stage. Prototypic and safe usage looks like this: * @@ -490,7 +490,7 @@ trait PipelineContext { /** * Scala API: Wrap a single command for efficient return to the pipeline’s machinery. - * This method avoids allocating a [[Right]] and an [[Iterable]] by reusing + * This method avoids allocating a [[scala.util.Right]] and an [[scala.collection.Iterable]] by reusing * one such instance within the PipelineContext, hence it can be used ONLY ONCE by * each pipeline stage. Prototypic and safe usage looks like this: * @@ -510,7 +510,7 @@ trait PipelineContext { /** * Scala API: Wrap a single event for efficient return to the pipeline’s machinery. - * This method avoids allocating a [[Left]] and an [[Iterable]] by reusing + * This method avoids allocating a [[scala.util.Left]] and an [[scala.collection.Iterable]] by reusing * one such instance within the context, hence it can be used ONLY ONCE by * each pipeline stage. Prototypic and safe usage looks like this: * @@ -742,15 +742,15 @@ object BackpressureBuffer { * This pipeline stage implements a configurable buffer for transforming the * per-write ACK/NACK-based backpressure model of a TCP connection actor into * an edge-triggered back-pressure model: the upper stages will receive - * notification when the buffer runs full ([[HighWatermarkReached]]) and when - * it subsequently empties ([[LowWatermarkReached]]). The upper layers should + * notification when the buffer runs full ([[BackpressureBuffer.HighWatermarkReached]]) and when + * it subsequently empties ([[BackpressureBuffer.LowWatermarkReached]]). The upper layers should * respond by not generating more writes when the buffer is full. There is also * a hard limit upon which this buffer will abort the connection. * * All limits are configurable and are given in number of bytes. * The `highWatermark` should be set such that the * amount of data generated before reception of the asynchronous - * [[HighWatermarkReached]] notification does not lead to exceeding the + * [[BackpressureBuffer.HighWatermarkReached]] notification does not lead to exceeding the * `maxCapacity` hard limit; if the writes may arrive in bursts then the * difference between these two should allow for at least one burst to be sent * after the high watermark has been reached. The `lowWatermark` must be less @@ -758,7 +758,7 @@ object BackpressureBuffer { * defines the hysteresis, i.e. how often these notifications are sent out (i.e. * if the difference is rather large then it will take some time for the buffer * to empty below the low watermark, and that room is then available for data - * sent in response to the [[LowWatermarkReached]] notification; if the + * sent in response to the [[BackpressureBuffer.LowWatermarkReached]] notification; if the * difference was small then the buffer would more quickly oscillate between * these two limits). */ @@ -1152,7 +1152,7 @@ class StringByteStringAdapter(charset: String = "utf-8") */ trait HasLogging extends PipelineContext { /** - * Retrieve the [[LoggingAdapter]] for this pipeline’s context. + * Retrieve the [[akka.event.LoggingAdapter]] for this pipeline’s context. */ def getLogger: LoggingAdapter } @@ -1164,7 +1164,7 @@ trait HasLogging extends PipelineContext { */ trait HasActorContext extends PipelineContext { /** - * Retrieve the [[ActorContext]] for this pipeline’s context. + * Retrieve the [[akka.actor.ActorContext]] for this pipeline’s context. */ def getContext: ActorContext } diff --git a/akka-actor/src/main/scala/akka/io/SslTlsSupport.scala b/akka-actor/src/main/scala/akka/io/SslTlsSupport.scala index af7ac2c7cd..43e78bfe5b 100644 --- a/akka-actor/src/main/scala/akka/io/SslTlsSupport.scala +++ b/akka-actor/src/main/scala/akka/io/SslTlsSupport.scala @@ -45,7 +45,7 @@ object SslTlsSupport { /** * This pipeline stage implements SSL / TLS support, using an externally - * configured [[SSLEngine]]. It operates on the level of [[Tcp.Event]] and + * configured [[javax.net.ssl.SSLEngine]]. It operates on the level of [[Tcp.Event]] and * [[Tcp.Command]] messages, which means that it will typically be one of * the lowest stages in a protocol stack. Since SSLEngine relies on contiguous * transmission of a data stream you will need to handle backpressure from diff --git a/akka-actor/src/main/scala/akka/io/Tcp.scala b/akka-actor/src/main/scala/akka/io/Tcp.scala index d2b231392b..30db38168b 100644 --- a/akka-actor/src/main/scala/akka/io/Tcp.scala +++ b/akka-actor/src/main/scala/akka/io/Tcp.scala @@ -526,8 +526,8 @@ object TcpMessage { /** * The Connect message is sent to the TCP manager actor, which is obtained via - * [[TcpExt#getManager]]. Either the manager replies with a [[CommandFailed]] - * or the actor handling the new connection replies with a [[Connected]] + * [[TcpExt#getManager]]. Either the manager replies with a [[Tcp.CommandFailed]] + * or the actor handling the new connection replies with a [[Tcp.Connected]] * message. * * @param remoteAddress is the address to connect to @@ -567,13 +567,13 @@ object TcpMessage { /** * The Bind message is send to the TCP manager actor, which is obtained via * [[TcpExt#getManager]] in order to bind to a listening socket. The manager - * replies either with a [[CommandFailed]] or the actor handling the listen - * socket replies with a [[Bound]] message. If the local port is set to 0 in - * the Bind message, then the [[Bound]] message should be inspected to find + * replies either with a [[Tcp.CommandFailed]] or the actor handling the listen + * socket replies with a [[Tcp.Bound]] message. If the local port is set to 0 in + * the Bind message, then the [[Tcp.Bound]] message should be inspected to find * the actual port which was bound to. * * @param handler The actor which will receive all incoming connection requests - * in the form of [[Connected]] messages. + * in the form of [[Tcp.Connected]] messages. * * @param localAddress The socket address to bind to; use port zero for * automatic assignment (i.e. an ephemeral port, see [[Bound]]) @@ -596,7 +596,7 @@ object TcpMessage { /** * This message must be sent to a TCP connection actor after receiving the - * [[Connected]] message. The connection will not read any data from the + * [[Tcp.Connected]] message. The connection will not read any data from the * socket until this message is received, because this message defines the * actor which will receive all inbound data. * @@ -605,11 +605,11 @@ object TcpMessage { * * @param keepOpenOnPeerClosed If this is set to true then the connection * is not automatically closed when the peer closes its half, - * requiring an explicit [[Closed]] from our side when finished. + * requiring an explicit [[Tcp.Closed]] from our side when finished. * * @param useResumeWriting If this is set to true then the connection actor - * will refuse all further writes after issuing a [[CommandFailed]] - * notification until [[ResumeWriting]] is received. This can + * will refuse all further writes after issuing a [[Tcp.CommandFailed]] + * notification until [[Tcp.ResumeWriting]] is received. This can * be used to implement NACK-based write backpressure. */ def register(handler: ActorRef, keepOpenOnPeerClosed: Boolean, useResumeWriting: Boolean): Command = @@ -621,15 +621,15 @@ object TcpMessage { /** * In order to close down a listening socket, send this message to that socket’s - * actor (that is the actor which previously had sent the [[Bound]] message). The - * listener socket actor will reply with a [[Unbound]] message. + * actor (that is the actor which previously had sent the [[Tcp.Bound]] message). The + * listener socket actor will reply with a [[Tcp.Unbound]] message. */ def unbind: Command = Unbind /** * A normal close operation will first flush pending writes and then close the * socket. The sender of this command and the registered handler for incoming - * data will both be notified once the socket is closed using a [[Closed]] + * data will both be notified once the socket is closed using a [[Tcp.Closed]] * message. */ def close: Command = Close @@ -638,7 +638,7 @@ object TcpMessage { * A confirmed close operation will flush pending writes and half-close the * connection, waiting for the peer to close the other half. The sender of this * command and the registered handler for incoming data will both be notified - * once the socket is closed using a [[ConfirmedClosed]] message. + * once the socket is closed using a [[Tcp.ConfirmedClosed]] message. */ def confirmedClose: Command = ConfirmedClose @@ -647,28 +647,28 @@ object TcpMessage { * command to the O/S kernel which should result in a TCP_RST packet being sent * to the peer. The sender of this command and the registered handler for * incoming data will both be notified once the socket is closed using a - * [[Aborted]] message. + * [[Tcp.Aborted]] message. */ def abort: Command = Abort /** - * Each [[WriteCommand]] can optionally request a positive acknowledgment to be sent - * to the commanding actor. If such notification is not desired the [[WriteCommand#ack]] + * Each [[Tcp.WriteCommand]] can optionally request a positive acknowledgment to be sent + * to the commanding actor. If such notification is not desired the [[Tcp.WriteCommand#ack]] * must be set to an instance of this class. The token contained within can be used - * to recognize which write failed when receiving a [[CommandFailed]] message. + * to recognize which write failed when receiving a [[Tcp.CommandFailed]] message. */ def noAck(token: AnyRef): NoAck = NoAck(token) /** - * Default [[NoAck]] instance which is used when no acknowledgment information is + * Default [[Tcp.NoAck]] instance which is used when no acknowledgment information is * explicitly provided. Its “token” is `null`. */ def noAck: NoAck = NoAck /** * Write data to the TCP connection. If no ack is needed use the special - * `NoAck` object. The connection actor will reply with a [[CommandFailed]] - * message if the write could not be enqueued. If [[WriteCommand#wantsAck]] - * returns true, the connection actor will reply with the supplied [[WriteCommand#ack]] + * `NoAck` object. The connection actor will reply with a [[Tcp.CommandFailed]] + * message if the write could not be enqueued. If [[Tcp.WriteCommand#wantsAck]] + * returns true, the connection actor will reply with the supplied [[Tcp.WriteCommand#ack]] * token once the write has been successfully enqueued to the O/S kernel. * Note that this does not in any way guarantee that the data will be * or have been sent! Unfortunately there is no way to determine whether @@ -682,9 +682,9 @@ object TcpMessage { /** * Write `count` bytes starting at `position` from file at `filePath` to the connection. - * The count must be > 0. The connection actor will reply with a [[CommandFailed]] - * message if the write could not be enqueued. If [[WriteCommand#wantsAck]] - * returns true, the connection actor will reply with the supplied [[WriteCommand#ack]] + * The count must be > 0. The connection actor will reply with a [[Tcp.CommandFailed]] + * message if the write could not be enqueued. If [[Tcp.WriteCommand#wantsAck]] + * returns true, the connection actor will reply with the supplied [[Tcp.WriteCommand#ack]] * token once the write has been successfully enqueued to the O/S kernel. * Note that this does not in any way guarantee that the data will be * or have been sent! Unfortunately there is no way to determine whether @@ -694,23 +694,23 @@ object TcpMessage { WriteFile(filePath, position, count, ack) /** - * When `useResumeWriting` is in effect as was indicated in the [[Register]] message + * When `useResumeWriting` is in effect as was indicated in the [[Tcp.Register]] message * then this command needs to be sent to the connection actor in order to re-enable - * writing after a [[CommandFailed]] event. All [[WriteCommand]] processed by the - * connection actor between the first [[CommandFailed]] and subsequent reception of - * this message will also be rejected with [[CommandFailed]]. + * writing after a [[Tcp.CommandFailed]] event. All [[Tcp.WriteCommand]] processed by the + * connection actor between the first [[Tcp.CommandFailed]] and subsequent reception of + * this message will also be rejected with [[Tcp.CommandFailed]]. */ def resumeWriting: Command = ResumeWriting /** * Sending this command to the connection actor will disable reading from the TCP * socket. TCP flow-control will then propagate backpressure to the sender side - * as buffers fill up on either end. To re-enable reading send [[ResumeReading]]. + * as buffers fill up on either end. To re-enable reading send [[Tcp.ResumeReading]]. */ def suspendReading: Command = SuspendReading /** - * This command needs to be sent to the connection actor after a [[SuspendReading]] + * This command needs to be sent to the connection actor after a [[Tcp.SuspendReading]] * command in order to resume reading from the socket. */ def resumeReading: Command = ResumeReading diff --git a/akka-actor/src/main/scala/akka/io/TcpPipelineHandler.scala b/akka-actor/src/main/scala/akka/io/TcpPipelineHandler.scala index 5c49d92957..3d4d2295bc 100644 --- a/akka-actor/src/main/scala/akka/io/TcpPipelineHandler.scala +++ b/akka-actor/src/main/scala/akka/io/TcpPipelineHandler.scala @@ -94,7 +94,7 @@ object TcpPipelineHandler { case class TcpEvent(@BeanProperty evt: Tcp.Event) extends Tcp.Command /** - * create [[Props]] for a pipeline handler + * create [[akka.actor.Props]] for a pipeline handler */ def props[Ctx <: PipelineContext, Cmd, Evt](init: TcpPipelineHandler.Init[Ctx, Cmd, Evt], connection: ActorRef, handler: ActorRef) = Props(classOf[TcpPipelineHandler[_, _, _]], init, connection, handler) @@ -104,8 +104,8 @@ object TcpPipelineHandler { /** * This actor wraps a pipeline and forwards commands and events between that * one and a [[Tcp]] connection actor. In order to inject commands into the - * pipeline send an [[Init.Command]] message to this actor; events will be sent - * to the designated handler wrapped in [[Init.Event]] messages. + * pipeline send an [[TcpPipelineHandler.Init.Command]] message to this actor; events will be sent + * to the designated handler wrapped in [[TcpPipelineHandler.Init.Event]] messages. * * When the designated handler terminates the TCP connection is aborted. When * the connection actor terminates this actor terminates as well; the designated @@ -164,7 +164,7 @@ class TcpPipelineHandler[Ctx <: PipelineContext, Cmd, Evt]( * * While this adapter communicates to the stage above it via raw ByteStrings, it is possible to inject Tcp Command * by sending them to the management port, and the adapter will simply pass them down to the stage below. Incoming Tcp Events - * that are not Receive events will be passed downwards wrapped in a [[TcpEvent]]; the [[TcpPipelineHandler]] will + * that are not Receive events will be passed downwards wrapped in a [[TcpPipelineHandler.TcpEvent]]; the [[TcpPipelineHandler]] will * send these notifications to the registered event handler actor. */ class TcpReadWriteAdapter extends PipelineStage[PipelineContext, ByteString, Tcp.Command, ByteString, Tcp.Event] { diff --git a/akka-actor/src/main/scala/akka/io/Udp.scala b/akka-actor/src/main/scala/akka/io/Udp.scala index e101aad1aa..6fc4082ff9 100644 --- a/akka-actor/src/main/scala/akka/io/Udp.scala +++ b/akka-actor/src/main/scala/akka/io/Udp.scala @@ -244,33 +244,33 @@ object UdpMessage { import language.implicitConversions /** - * Each [[Send]] can optionally request a positive acknowledgment to be sent - * to the commanding actor. If such notification is not desired the [[Send#ack]] + * Each [[Udp.Send]] can optionally request a positive acknowledgment to be sent + * to the commanding actor. If such notification is not desired the [[Udp.Send#ack]] * must be set to an instance of this class. The token contained within can be used - * to recognize which write failed when receiving a [[CommandFailed]] message. + * to recognize which write failed when receiving a [[Udp.CommandFailed]] message. */ def noAck(token: AnyRef): NoAck = NoAck(token) /** - * Default [[NoAck]] instance which is used when no acknowledgment information is + * Default [[Udp.NoAck]] instance which is used when no acknowledgment information is * explicitly provided. Its “token” is `null`. */ def noAck: NoAck = NoAck /** * This message is understood by the “simple sender” which can be obtained by - * sending the [[SimpleSender]] query to the [[UdpExt#manager]] as well as by - * the listener actors which are created in response to [[Bind]]. It will send + * sending the [[Udp.SimpleSender]] query to the [[UdpExt#manager]] as well as by + * the listener actors which are created in response to [[Udp.Bind]]. It will send * the given payload data as one UDP datagram to the given target address. The - * UDP actor will respond with [[CommandFailed]] if the send could not be + * UDP actor will respond with [[Udp.CommandFailed]] if the send could not be * enqueued to the O/S kernel because the send buffer was full. If the given - * `ack` is not of type [[NoAck]] the UDP actor will reply with the given + * `ack` is not of type [[Udp.NoAck]] the UDP actor will reply with the given * object as soon as the datagram has been successfully enqueued to the O/S * kernel. * * The sending UDP socket’s address belongs to the “simple sender” which does * not handle inbound datagrams and sends from an ephemeral port; therefore * sending using this mechanism is not suitable if replies are expected, use - * [[Bind]] in that case. + * [[Udp.Bind]] in that case. */ def send(payload: ByteString, target: InetSocketAddress, ack: Event): Command = Send(payload, target, ack) /** @@ -281,8 +281,8 @@ object UdpMessage { /** * Send this message to the [[UdpExt#manager]] in order to bind to the given * local port (or an automatically assigned one if the port number is zero). - * The listener actor for the newly bound port will reply with a [[Bound]] - * message, or the manager will reply with a [[CommandFailed]] message. + * The listener actor for the newly bound port will reply with a [[Udp.Bound]] + * message, or the manager will reply with a [[Udp.CommandFailed]] message. */ def bind(handler: ActorRef, endpoint: InetSocketAddress, options: JIterable[SocketOption]): Command = Bind(handler, endpoint, options.asScala.to) @@ -292,15 +292,15 @@ object UdpMessage { def bind(handler: ActorRef, endpoint: InetSocketAddress): Command = Bind(handler, endpoint, Nil) /** - * Send this message to the listener actor that previously sent a [[Bound]] + * Send this message to the listener actor that previously sent a [[Udp.Bound]] * message in order to close the listening socket. The recipient will reply - * with an [[Unbound]] message. + * with an [[Udp.Unbound]] message. */ def unbind: Command = Unbind /** * Retrieve a reference to a “simple sender” actor of the UDP extension. - * The newly created “simple sender” will reply with the [[SimpleSenderReady]] notification. + * The newly created “simple sender” will reply with the [[Udp.SimpleSenderReady]] notification. * * The “simple sender” is a convenient service for being able to send datagrams * when the originating address is meaningless, i.e. when no reply is expected. @@ -315,16 +315,16 @@ object UdpMessage { def simpleSender: Command = SimpleSender /** - * Send this message to a listener actor (which sent a [[Bound]] message) to + * Send this message to a listener actor (which sent a [[Udp.Bound]] message) to * have it stop reading datagrams from the network. If the O/S kernel’s receive * buffer runs full then subsequent datagrams will be silently discarded. - * Re-enable reading from the socket using the [[ResumeReading]] command. + * Re-enable reading from the socket using the [[Udp.ResumeReading]] command. */ def suspendReading: Command = SuspendReading /** * This message must be sent to the listener actor to re-enable reading from - * the socket after a [[SuspendReading]] command. + * the socket after a [[Udp.SuspendReading]] command. */ def resumeReading: Command = ResumeReading } diff --git a/akka-actor/src/main/scala/akka/io/UdpConnected.scala b/akka-actor/src/main/scala/akka/io/UdpConnected.scala index 19105df1c0..c8e91e7067 100644 --- a/akka-actor/src/main/scala/akka/io/UdpConnected.scala +++ b/akka-actor/src/main/scala/akka/io/UdpConnected.scala @@ -103,7 +103,7 @@ object UdpConnected extends ExtensionId[UdpConnectedExt] with ExtensionIdProvide case object Disconnect extends Command /** - * Send this message to a listener actor (which sent a [[Bound]] message) to + * Send this message to a listener actor (which sent a [[Udp.Bound]] message) to * have it stop reading datagrams from the network. If the O/S kernel’s receive * buffer runs full then subsequent datagrams will be silently discarded. * Re-enable reading from the socket using the [[ResumeReading]] command. @@ -123,7 +123,7 @@ object UdpConnected extends ExtensionId[UdpConnectedExt] with ExtensionIdProvide /** * When a connection actor receives a datagram from its socket it will send - * it to the handler designated in the [[Bind]] message using this message type. + * it to the handler designated in the [[Udp.Bind]] message using this message type. */ case class Received(data: ByteString) extends Event @@ -201,8 +201,8 @@ object UdpConnectedMessage { /** * This message is understood by the connection actors to send data to their * designated destination. The connection actor will respond with - * [[CommandFailed]] if the send could not be enqueued to the O/S kernel - * because the send buffer was full. If the given `ack` is not of type [[NoAck]] + * [[UdpConnected.CommandFailed]] if the send could not be enqueued to the O/S kernel + * because the send buffer was full. If the given `ack` is not of type [[UdpConnected.NoAck]] * the connection actor will reply with the given object as soon as the datagram * has been successfully enqueued to the O/S kernel. */ @@ -214,36 +214,36 @@ object UdpConnectedMessage { /** * Send this message to a connection actor (which had previously sent the - * [[Connected]] message) in order to close the socket. The connection actor - * will reply with a [[Disconnected]] message. + * [[UdpConnected.Connected]] message) in order to close the socket. The connection actor + * will reply with a [[UdpConnected.Disconnected]] message. */ def disconnect: Command = Disconnect /** - * Each [[Send]] can optionally request a positive acknowledgment to be sent - * to the commanding actor. If such notification is not desired the [[Send#ack]] + * Each [[UdpConnected.Send]] can optionally request a positive acknowledgment to be sent + * to the commanding actor. If such notification is not desired the [[UdpConnected.Send#ack]] * must be set to an instance of this class. The token contained within can be used - * to recognize which write failed when receiving a [[CommandFailed]] message. + * to recognize which write failed when receiving a [[UdpConnected.CommandFailed]] message. */ def noAck(token: AnyRef): NoAck = NoAck(token) /** - * Default [[NoAck]] instance which is used when no acknowledgment information is + * Default [[UdpConnected.NoAck]] instance which is used when no acknowledgment information is * explicitly provided. Its “token” is `null`. */ def noAck: NoAck = NoAck /** - * Send this message to a listener actor (which sent a [[Bound]] message) to + * Send this message to a listener actor (which sent a [[Udp.Bound]] message) to * have it stop reading datagrams from the network. If the O/S kernel’s receive * buffer runs full then subsequent datagrams will be silently discarded. - * Re-enable reading from the socket using the [[ResumeReading]] command. + * Re-enable reading from the socket using the [[UdpConnected.ResumeReading]] command. */ def suspendReading: Command = SuspendReading /** * This message must be sent to the listener actor to re-enable reading from - * the socket after a [[SuspendReading]] command. + * the socket after a [[UdpConnected.SuspendReading]] command. */ def resumeReading: Command = ResumeReading diff --git a/akka-actor/src/main/scala/akka/pattern/AskSupport.scala b/akka-actor/src/main/scala/akka/pattern/AskSupport.scala index 1905d73533..c741c53803 100644 --- a/akka-actor/src/main/scala/akka/pattern/AskSupport.scala +++ b/akka-actor/src/main/scala/akka/pattern/AskSupport.scala @@ -41,7 +41,7 @@ trait AskSupport { * val future = actor.ask(message)(timeout) // => ask(actor, message)(timeout) * }}} * - * All of the above use an implicit [[akka.actor.Timeout]]. + * All of the above use an implicit [[akka.util.Timeout]]. */ implicit def ask(actorRef: ActorRef): AskableActorRef = new AskableActorRef(actorRef) @@ -88,7 +88,7 @@ trait AskSupport { * val future = selection.ask(message)(timeout) // => ask(selection, message)(timeout) * }}} * - * All of the above use an implicit [[akka.actor.Timeout]]. + * All of the above use an implicit [[akka.util.Timeout]]. */ implicit def ask(actorSelection: ActorSelection): AskableActorSelection = new AskableActorSelection(actorSelection) diff --git a/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala b/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala index 9a6e7a4692..ad2ef4602d 100644 --- a/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala +++ b/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala @@ -35,7 +35,7 @@ object ConsistentHashingRouter { * the hash, but the data to be hashed. * * If returning an `Array[Byte]` or String it will be used as is, - * otherwise the configured [[akka.akka.serialization.Serializer]] + * otherwise the configured [[akka.serialization.Serializer]] * will be applied to the returned data. * * If messages can't implement this interface themselves, @@ -67,7 +67,7 @@ object ConsistentHashingRouter { * the hash that is to be returned, but the data to be hashed. * * If returning an `Array[Byte]` or String it will be used as is, - * otherwise the configured [[akka.akka.serialization.Serializer]] + * otherwise the configured [[akka.serialization.Serializer]] * will be applied to the returned data. */ type ConsistentHashMapping = PartialFunction[Any, Any] @@ -88,13 +88,14 @@ object ConsistentHashingRouter { * this mapping. * * If returning an `Array[Byte]` or String it will be used as is, - * otherwise the configured [[akka.akka.serialization.Serializer]] + * otherwise the configured [[akka.serialization.Serializer]] * will be applied to the returned data. */ trait ConsistentHashMapper { def hashKey(message: Any): Any } } + /** * A Router that uses consistent hashing to select a connection based on the * sent message. @@ -137,7 +138,7 @@ object ConsistentHashingRouter { * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]] - * @param virtualNodesFactor number of virtual nodes per node, used in [[akka.routing.ConsistantHash]] + * @param virtualNodesFactor number of virtual nodes per node, used in [[akka.routing.ConsistentHash]] * @param hashMapping partial function from message to the data to * use for the consistent hash key */ From 0f25106b853b077f027995c804f9748b2cf079ca Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Fri, 5 Jul 2013 16:27:44 +0200 Subject: [PATCH 2/2] Improve scaladoc in akka-actor, see #3152 * also change visibility of Actor.context --- akka-actor/src/main/scala/akka/Main.scala | 8 + .../src/main/scala/akka/actor/Actor.scala | 21 +-- .../src/main/scala/akka/actor/ActorCell.scala | 14 +- .../src/main/scala/akka/actor/ActorRef.scala | 17 +- .../scala/akka/actor/ActorRefProvider.scala | 13 +- .../src/main/scala/akka/actor/Stash.scala | 13 +- .../main/scala/akka/actor/UntypedActor.scala | 24 ++- .../src/main/scala/akka/event/Logging.scala | 6 +- .../scala/akka/event/LoggingReceive.scala | 2 +- akka-actor/src/main/scala/akka/io/Tcp.scala | 2 +- akka-actor/src/main/scala/akka/io/Udp.scala | 2 +- .../src/main/scala/akka/io/UdpConnected.scala | 2 +- .../routing/ConsistentHashingRouter.scala | 19 ++- .../src/main/scala/akka/routing/Routing.scala | 155 +++++------------- 14 files changed, 129 insertions(+), 169 deletions(-) diff --git a/akka-actor/src/main/scala/akka/Main.scala b/akka-actor/src/main/scala/akka/Main.scala index 0a9d56dce2..57dedd6897 100644 --- a/akka-actor/src/main/scala/akka/Main.scala +++ b/akka-actor/src/main/scala/akka/Main.scala @@ -13,8 +13,16 @@ import akka.actor.Props import akka.actor.ActorRef import scala.util.control.NonFatal +/** + * Main class to start an [[akka.actor.ActorSystem]] with one + * top level application supervisor actor. It will shutdown + * the actor system when the top level actor is terminated. + */ object Main { + /** + * @params args one argument: the class of the application supervisor actor + */ def main(args: Array[String]): Unit = { if (args.length != 1) { println("you need to provide exactly one argument: the class of the application supervisor actor") diff --git a/akka-actor/src/main/scala/akka/actor/Actor.scala b/akka-actor/src/main/scala/akka/actor/Actor.scala index f8fb593b07..1741494f6e 100644 --- a/akka-actor/src/main/scala/akka/actor/Actor.scala +++ b/akka-actor/src/main/scala/akka/actor/Actor.scala @@ -185,7 +185,7 @@ private[akka] case class SelectParent(next: Any) extends SelectionPath case class IllegalActorStateException private[akka] (message: String) extends AkkaException(message) /** - * ActorKilledException is thrown when an Actor receives the akka.actor.Kill message + * ActorKilledException is thrown when an Actor receives the [[akka.actor.Kill]] message */ @SerialVersionUID(1L) case class ActorKilledException private[akka] (message: String) extends AkkaException(message) with NoStackTrace @@ -320,7 +320,8 @@ object Status { } /** - * Mix in ActorLogging into your Actor to easily obtain a reference to a logger, which is available under the name "log". + * Scala API: Mix in ActorLogging into your Actor to easily obtain a reference to a logger, + * which is available under the name "log". * * {{{ * class MyActor extends Actor with ActorLogging { @@ -365,7 +366,7 @@ object Actor { * * An actor has a well-defined (non-cyclic) life-cycle. * - ''RUNNING'' (created and started actor) - can receive messages - * - ''SHUTDOWN'' (when 'stop' or 'exit' is invoked) - can't do anything + * - ''SHUTDOWN'' (when 'stop' is invoked) - can't do anything * * The Actor's own [[akka.actor.ActorRef]] is available as `self`, the current * message’s sender as `sender` and the [[akka.actor.ActorContext]] as @@ -379,10 +380,10 @@ object Actor { * class ExampleActor extends Actor { * * override val supervisorStrategy = OneForOneStrategy(maxNrOfRetries = 10, withinTimeRange = 1 minute) { - * case _: ArithmeticException ⇒ Resume - * case _: NullPointerException ⇒ Restart - * case _: IllegalArgumentException ⇒ Stop - * case _: Exception ⇒ Escalate + * case _: ArithmeticException => Resume + * case _: NullPointerException => Restart + * case _: IllegalArgumentException => Stop + * case _: Exception => Escalate * } * * def receive = { @@ -392,7 +393,7 @@ object Actor { * // just to demonstrate how to stop yourself * case Shutdown => context.stop(self) * - * // error kernel with child replying directly to “customer” + * // error kernel with child replying directly to 'sender' * case Dangerous(r) => context.actorOf(Props[ReplyToOriginWorker]).tell(PerformWork(r), sender) * * // error kernel with reply going through us @@ -429,7 +430,7 @@ trait Actor { * [[akka.actor.UntypedActorContext]], which is the Java API of the actor * context. */ - protected[akka] implicit val context: ActorContext = { + implicit val context: ActorContext = { val contextStack = ActorCell.contextStack.get if ((contextStack.isEmpty) || (contextStack.head eq null)) throw ActorInitializationException( @@ -542,7 +543,7 @@ trait Actor { * case of an unhandled [[akka.actor.Terminated]] message) or publishes an [[akka.actor.UnhandledMessage]] * to the actor's system's [[akka.event.EventStream]] */ - def unhandled(message: Any) { + def unhandled(message: Any): Unit = { message match { case Terminated(dead) ⇒ throw new DeathPactException(dead) case _ ⇒ context.system.eventStream.publish(UnhandledMessage(message, sender, self)) diff --git a/akka-actor/src/main/scala/akka/actor/ActorCell.scala b/akka-actor/src/main/scala/akka/actor/ActorCell.scala index b26d8df60b..44a872f071 100644 --- a/akka-actor/src/main/scala/akka/actor/ActorCell.scala +++ b/akka-actor/src/main/scala/akka/actor/ActorCell.scala @@ -52,13 +52,13 @@ trait ActorContext extends ActorRefFactory { /** * Gets the current receive timeout. - * When specified, the receive method should be able to handle a 'ReceiveTimeout' message. + * When specified, the receive method should be able to handle a [[akka.actor.ReceiveTimeout]] message. */ def receiveTimeout: Duration /** - * Defines the inactivity timeout after which the sending of a `ReceiveTimeout` message is triggered. - * When specified, the receive function should be able to handle a 'ReceiveTimeout' message. + * Defines the inactivity timeout after which the sending of a [[akka.actor.ReceiveTimeout]] message is triggered. + * When specified, the receive function should be able to handle a [[akka.actor.ReceiveTimeout]] message. * 1 millisecond is the minimum supported timeout. * * Please note that the receive timeout might fire and enqueue the `ReceiveTimeout` message right after @@ -113,13 +113,13 @@ trait ActorContext extends ActorRefFactory { /** * Returns the dispatcher (MessageDispatcher) that is used for this Actor. - * Importing this member will place a implicit MessageDispatcher in scope. + * Importing this member will place a implicit ExecutionContext in scope. */ implicit def dispatcher: ExecutionContext /** * The system that the actor belongs to. - * Importing this member will place a implicit MessageDispatcher in scope. + * Importing this member will place a implicit ExecutionContext in scope. */ implicit def system: ActorSystem @@ -130,8 +130,8 @@ trait ActorContext extends ActorRefFactory { /** * Registers this actor as a Monitor for the provided ActorRef. - * This actor will receive a Terminated(watched) message when watched - * is terminated. + * This actor will receive a Terminated(subject) message when watched + * actor is terminated. * @return the provided ActorRef */ def watch(subject: ActorRef): ActorRef diff --git a/akka-actor/src/main/scala/akka/actor/ActorRef.scala b/akka-actor/src/main/scala/akka/actor/ActorRef.scala index d7bcf02b76..c93e5b41eb 100644 --- a/akka-actor/src/main/scala/akka/actor/ActorRef.scala +++ b/akka-actor/src/main/scala/akka/actor/ActorRef.scala @@ -45,7 +45,9 @@ object ActorRef { * def receive { * case Request1(msg) => other ! refine(msg) // uses this actor as sender reference, reply goes to us * case Request2(msg) => other.tell(msg, sender) // forward sender reference, enabling direct reply - * case Request3(msg) => sender ! (other ? msg) // will reply with a Future for holding other’s reply (implicit timeout from "akka.actor.timeout") + * case Request3(msg) => + * implicit val timeout = Timeout(5.seconds) + * sender ! (other ? msg) // will reply with a Future for holding other's reply * } * } * }}} @@ -61,16 +63,16 @@ object ActorRef { * @Override * public void onReceive(Object o) { * if (o instanceof Request1) { - * val msg = ((Request1) o).getMsg(); - * other.tell(msg); // uses this actor as sender reference, reply goes to us + * Msg msg = ((Request1) o).getMsg(); + * other.tell(msg, getSelf()); // uses this actor as sender reference, reply goes to us * * } else if (o instanceof Request2) { - * val msg = ((Request2) o).getMsg(); + * Msg msg = ((Request2) o).getMsg(); * other.tell(msg, getSender()); // forward sender reference, enabling direct reply * * } else if (o instanceof Request3) { - * val msg = ((Request3) o).getMsg(); - * getSender().tell(ask(other, msg, 5000)); // reply with Future for holding the other’s reply (timeout 5 seconds) + * Msg msg = ((Request3) o).getMsg(); + * getSender().tell(ask(other, msg, 5000)); // reply with Future for holding the other's reply (timeout 5 seconds) * * } else { * unhandled(o); @@ -80,7 +82,8 @@ object ActorRef { * }}} * * ActorRef does not have a method for terminating the actor it points to, use - * [[akka.actor.ActorRefFactory]]`.stop(child)` for this purpose. + * [[akka.actor.ActorRefFactory]]`.stop(ref)`, or send a [[akka.actor.PoisonPill]], + * for this purpose. * * Two actor references are compared equal when they have the same path and point to * the same actor incarnation. A reference pointing to a terminated actor doesn't compare diff --git a/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala b/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala index 979b9a4402..70ed893dce 100644 --- a/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala +++ b/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala @@ -211,6 +211,9 @@ trait ActorRefFactory { * reversed and with “$” prepended, may change in the future). * * See [[akka.actor.Props]] for details on how to obtain a `Props` object. + * + * @throws akka.ConfigurationException if deployment, dispatcher + * or mailbox configuration is wrong */ def actorOf(props: Props): ActorRef @@ -220,6 +223,10 @@ trait ActorRefFactory { * and `InvalidActorNameException` is thrown. * * See [[akka.actor.Props]] for details on how to obtain a `Props` object. + * @throws akka.actor.InvalidActorNameException if the given name is + * invalid or already in use + * @throws akka.ConfigurationException if deployment, dispatcher + * or mailbox configuration is wrong */ def actorOf(props: Props, name: String): ActorRef @@ -263,7 +270,7 @@ trait ActorRefFactory { * ... * val target = context.actorFor(Seq("..", "myBrother", "myNephew")) * ... - * } + * } * } * }}} * @@ -285,9 +292,9 @@ trait ActorRefFactory { * path.add(".."); * path.add("myBrother"); * path.add("myNephew"); - * final ActorRef target = context().actorFor(path); + * final ActorRef target = getContext().actorFor(path); * ... - * } + * } * } * }}} * diff --git a/akka-actor/src/main/scala/akka/actor/Stash.scala b/akka-actor/src/main/scala/akka/actor/Stash.scala index ca5bf11a5e..fabefdabc5 100644 --- a/akka-actor/src/main/scala/akka/actor/Stash.scala +++ b/akka-actor/src/main/scala/akka/actor/Stash.scala @@ -30,18 +30,7 @@ import akka.AkkaException * * * Note that the `Stash` trait can only be used together with actors that have a deque-based - * mailbox. Actors can be configured to use a deque-based mailbox using a configuration like - * the following (see the documentation on dispatchers on how to configure a custom - * dispatcher): - * 
- *  akka {
- *    actor {
- *      my-custom-dispatcher {
- *        mailbox-type = "akka.dispatch.UnboundedDequeBasedMailbox"
- *      }
- *    }
- *  }
- *
+ * mailbox. * * Note that the `Stash` trait must be mixed into (a subclass of) the `Actor` trait before * any trait/class that overrides the `preRestart` callback. This means it's not possible to write diff --git a/akka-actor/src/main/scala/akka/actor/UntypedActor.scala b/akka-actor/src/main/scala/akka/actor/UntypedActor.scala index 8d9d61fb28..46e3dd0f68 100644 --- a/akka-actor/src/main/scala/akka/actor/UntypedActor.scala +++ b/akka-actor/src/main/scala/akka/actor/UntypedActor.scala @@ -27,7 +27,7 @@ import akka.japi.{ Creator } * {{{ * public class SampleUntypedActor extends UntypedActor { * - * public class Reply { + * public static class Reply implements java.io.Serializable { * final public ActorRef sender; * final public Result result; * Reply(ActorRef sender, Result result) { @@ -59,7 +59,7 @@ import akka.japi.{ Creator } * * public void onReceive(Object message) throws Exception { * if (message instanceof String) { - * String msg = (String)message; + * String msg = (String) message; * * if (msg.equals("UseSender")) { * // Reply to original sender of message @@ -77,7 +77,9 @@ import akka.japi.{ Creator } * // Send work to one-off child and collect the answer, reply handled further down * getContext().actorOf(Props.create(Worker.class)).tell("DoWorkAndReplyToMe", getSelf()); * - * } else throw new IllegalArgumentException("Unknown message: " + message); + * } else { + * unhandled(message); + * } * * } else if (message instanceof Reply) { * @@ -85,7 +87,9 @@ import akka.japi.{ Creator } * // might want to do some processing/book-keeping here * reply.sender.tell(reply.result, getSelf()); * - * } else throw new IllegalArgumentException("Unknown message: " + message); + * } else { + * unhandled(message); + * } * } * } * }}} @@ -107,7 +111,7 @@ abstract class UntypedActor extends Actor { def getContext(): UntypedActorContext = context.asInstanceOf[UntypedActorContext] /** - * Returns the 'self' reference. + * Returns the ActorRef for this actor. */ def getSelf(): ActorRef = self @@ -161,6 +165,16 @@ abstract class UntypedActor extends Actor { override def postRestart(reason: Throwable): Unit = super.postRestart(reason) final def receive = { case msg ⇒ onReceive(msg) } + + /** + * Recommended convention is to call this method if the message + * isn't handled in [[#onReceive]] (e.g. unknown message type). + * By default it fails with either a [[akka.actor.DeathPactException]] (in + * case of an unhandled [[akka.actor.Terminated]] message) or publishes an [[akka.actor.UnhandledMessage]] + * to the actor's system's [[akka.event.EventStream]]. + */ + override def unhandled(message: Any): Unit = super.unhandled(message) + } /** diff --git a/akka-actor/src/main/scala/akka/event/Logging.scala b/akka-actor/src/main/scala/akka/event/Logging.scala index f3a935797f..fee55f2acb 100644 --- a/akka-actor/src/main/scala/akka/event/Logging.scala +++ b/akka-actor/src/main/scala/akka/event/Logging.scala @@ -366,7 +366,7 @@ object LogSource { * your own, make sure to handle these four event types plus the InitializeLogger * message which is sent before actually attaching it to the logging bus. * - * Logging is configured in akka.conf by setting (some of) the following: + * Logging is configured by setting (some of) the following: * * 

  * akka {
@@ -737,8 +737,8 @@ object Logging {
    * Actor-less logging implementation for synchronous logging to standard
    * output. This logger is always attached first in order to be able to log
    * failures during application start-up, even before normal logging is
-   * started. Its log level can be configured by setting
-   * akka.stdout-loglevel in akka.conf.
+   * started. Its log level can be defined by configuration setting
+   * akka.stdout-loglevel.
    */
   class StandardOutLogger extends MinimalActorRef with StdOutLogger {
     val path: ActorPath = new RootActorPath(Address("akka", "all-systems"), "/StandardOutLogger")
diff --git a/akka-actor/src/main/scala/akka/event/LoggingReceive.scala b/akka-actor/src/main/scala/akka/event/LoggingReceive.scala
index 07546e30cc..d9bf90d608 100644
--- a/akka-actor/src/main/scala/akka/event/LoggingReceive.scala
+++ b/akka-actor/src/main/scala/akka/event/LoggingReceive.scala
@@ -24,7 +24,7 @@ object LoggingReceive {
    *
* * This method does NOT modify the given Receive unless - * akka.actor.debug.receive is set within akka.conf. + * `akka.actor.debug.receive` is set in configuration. */ def apply(r: Receive)(implicit context: ActorContext): Receive = r match { case _: LoggingReceive ⇒ r diff --git a/akka-actor/src/main/scala/akka/io/Tcp.scala b/akka-actor/src/main/scala/akka/io/Tcp.scala index 30db38168b..f97c4a2f43 100644 --- a/akka-actor/src/main/scala/akka/io/Tcp.scala +++ b/akka-actor/src/main/scala/akka/io/Tcp.scala @@ -25,7 +25,7 @@ import java.lang.{ Iterable ⇒ JIterable } * stable and ready for production use. * * For a full description of the design and philosophy behind this IO - * implementation please refer to {@see the Akka online documentation}. + * implementation please refer to the Akka online documentation. * * In order to open an outbound connection send a [[Tcp.Connect]] message * to the [[TcpExt#manager]]. diff --git a/akka-actor/src/main/scala/akka/io/Udp.scala b/akka-actor/src/main/scala/akka/io/Udp.scala index 6fc4082ff9..dcdacf7003 100644 --- a/akka-actor/src/main/scala/akka/io/Udp.scala +++ b/akka-actor/src/main/scala/akka/io/Udp.scala @@ -26,7 +26,7 @@ import akka.actor._ * from whom data can be received. For “connected” UDP mode see [[UdpConnected]]. * * For a full description of the design and philosophy behind this IO - * implementation please refer to {@see the Akka online documentation}. + * implementation please refer to the Akka online documentation. * * The Java API for generating UDP commands is available at [[UdpMessage]]. */ diff --git a/akka-actor/src/main/scala/akka/io/UdpConnected.scala b/akka-actor/src/main/scala/akka/io/UdpConnected.scala index c8e91e7067..5813643c38 100644 --- a/akka-actor/src/main/scala/akka/io/UdpConnected.scala +++ b/akka-actor/src/main/scala/akka/io/UdpConnected.scala @@ -25,7 +25,7 @@ import akka.actor._ * from whom data can be received. For “unconnected” UDP mode see [[Udp]]. * * For a full description of the design and philosophy behind this IO - * implementation please refer to {@see the Akka online documentation}. + * implementation please refer to the Akka online documentation. * * The Java API for generating UDP commands is available at [[UdpConnectedMessage]]. */ diff --git a/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala b/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala index ad2ef4602d..b61337ee9c 100644 --- a/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala +++ b/akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala @@ -127,14 +127,17 @@ object ConsistentHashingRouter { * *

Supervision Setup

* - * The router creates a “head” actor which supervises and/or monitors the - * routees. Instances are created as children of this actor, hence the - * children are not supervised by the parent of the router. Common choices are - * to always escalate (meaning that fault handling is always applied to all - * children simultaneously; this is the default) or use the parent’s strategy, - * which will result in routed children being treated individually, but it is - * possible as well to use Routers to give different supervisor strategies to - * different groups of children. + * Any routees that are created by a router will be created as the router's children. + * The router is therefore also the children's supervisor. + * + * The supervision strategy of the router actor can be configured with + * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to + * a strategy of “always escalate”. This means that errors are passed up to the + * router's supervisor for handling. + * + * The router's supervisor will treat the error as an error with the router itself. + * Therefore a directive to stop or restart will cause the router itself to stop or + * restart. The router, in turn, will cause its children to stop and restart. * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]] diff --git a/akka-actor/src/main/scala/akka/routing/Routing.scala b/akka-actor/src/main/scala/akka/routing/Routing.scala index 20bceb7f10..bb947b266f 100644 --- a/akka-actor/src/main/scala/akka/routing/Routing.scala +++ b/akka-actor/src/main/scala/akka/routing/Routing.scala @@ -588,30 +588,17 @@ object RoundRobinRouter { * *

Supervision Setup

* - * The router creates a “head” actor which supervises and/or monitors the - * routees. Instances are created as children of this actor, hence the - * children are not supervised by the parent of the router. Common choices are - * to always escalate (meaning that fault handling is always applied to all - * children simultaneously; this is the default) or use the parent’s strategy, - * which will result in routed children being treated individually, but it is - * possible as well to use Routers to give different supervisor strategies to - * different groups of children. + * Any routees that are created by a router will be created as the router's children. + * The router is therefore also the children's supervisor. * - * {{{ - * class MyActor extends Actor { - * override val supervisorStrategy = ... + * The supervision strategy of the router actor can be configured with + * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to + * a strategy of “always escalate”. This means that errors are passed up to the + * router's supervisor for handling. * - * val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(RoundRobinRouter(5))) - * - * val poolIndividuals = context.actorOf(Props[SomeActor].withRouter( - * RoundRobinRouter(5, supervisorStrategy = this.supervisorStrategy))) - * - * val specialChild = context.actorOf(Props[SomeActor].withRouter( - * RoundRobinRouter(5, supervisorStrategy = OneForOneStrategy() { - * ... - * }))) - * } - * }}} + * The router's supervisor will treat the error as an error with the router itself. + * Therefore a directive to stop or restart will cause the router itself to stop or + * restart. The router, in turn, will cause its children to stop and restart. * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]] @@ -723,30 +710,17 @@ object RandomRouter { * *

Supervision Setup

* - * The router creates a “head” actor which supervises and/or monitors the - * routees. Instances are created as children of this actor, hence the - * children are not supervised by the parent of the router. Common choices are - * to always escalate (meaning that fault handling is always applied to all - * children simultaneously; this is the default) or use the parent’s strategy, - * which will result in routed children being treated individually, but it is - * possible as well to use Routers to give different supervisor strategies to - * different groups of children. + * Any routees that are created by a router will be created as the router's children. + * The router is therefore also the children's supervisor. * - * {{{ - * class MyActor extends Actor { - * override val supervisorStrategy = ... + * The supervision strategy of the router actor can be configured with + * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to + * a strategy of “always escalate”. This means that errors are passed up to the + * router's supervisor for handling. * - * val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(RandomRouter(5))) - * - * val poolIndividuals = context.actorOf(Props[SomeActor].withRouter( - * RandomRouter(5, supervisorStrategy = this.supervisorStrategy))) - * - * val specialChild = context.actorOf(Props[SomeActor].withRouter( - * RandomRouter(5, supervisorStrategy = OneForOneStrategy() { - * ... - * }))) - * } - * }}} + * The router's supervisor will treat the error as an error with the router itself. + * Therefore a directive to stop or restart will cause the router itself to stop or + * restart. The router, in turn, will cause its children to stop and restart. * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]] @@ -865,30 +839,17 @@ object SmallestMailboxRouter { * *

Supervision Setup

* - * The router creates a “head” actor which supervises and/or monitors the - * routees. Instances are created as children of this actor, hence the - * children are not supervised by the parent of the router. Common choices are - * to always escalate (meaning that fault handling is always applied to all - * children simultaneously; this is the default) or use the parent’s strategy, - * which will result in routed children being treated individually, but it is - * possible as well to use Routers to give different supervisor strategies to - * different groups of children. + * Any routees that are created by a router will be created as the router's children. + * The router is therefore also the children's supervisor. * - * {{{ - * class MyActor extends Actor { - * override val supervisorStrategy = ... + * The supervision strategy of the router actor can be configured with + * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to + * a strategy of “always escalate”. This means that errors are passed up to the + * router's supervisor for handling. * - * val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(SmallestMailboxRouter(5))) - * - * val poolIndividuals = context.actorOf(Props[SomeActor].withRouter( - * SmallestMailboxRouter(5, supervisorStrategy = this.supervisorStrategy))) - * - * val specialChild = context.actorOf(Props[SomeActor].withRouter( - * SmallestMailboxRouter(5, supervisorStrategy = OneForOneStrategy() { - * ... - * }))) - * } - * }}} + * The router's supervisor will treat the error as an error with the router itself. + * Therefore a directive to stop or restart will cause the router itself to stop or + * restart. The router, in turn, will cause its children to stop and restart. * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]] @@ -1082,30 +1043,17 @@ object BroadcastRouter { * *

Supervision Setup

* - * The router creates a “head” actor which supervises and/or monitors the - * routees. Instances are created as children of this actor, hence the - * children are not supervised by the parent of the router. Common choices are - * to always escalate (meaning that fault handling is always applied to all - * children simultaneously; this is the default) or use the parent’s strategy, - * which will result in routed children being treated individually, but it is - * possible as well to use Routers to give different supervisor strategies to - * different groups of children. + * Any routees that are created by a router will be created as the router's children. + * The router is therefore also the children's supervisor. * - * {{{ - * class MyActor extends Actor { - * override val supervisorStrategy = ... + * The supervision strategy of the router actor can be configured with + * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to + * a strategy of “always escalate”. This means that errors are passed up to the + * router's supervisor for handling. * - * val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(BroadcastRouter(5))) - * - * val poolIndividuals = context.actorOf(Props[SomeActor].withRouter( - * BroadcastRouter(5, supervisorStrategy = this.supervisorStrategy))) - * - * val specialChild = context.actorOf(Props[SomeActor].withRouter( - * BroadcastRouter(5, supervisorStrategy = OneForOneStrategy() { - * ... - * }))) - * } - * }}} + * The router's supervisor will treat the error as an error with the router itself. + * Therefore a directive to stop or restart will cause the router itself to stop or + * restart. The router, in turn, will cause its children to stop and restart. * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]] @@ -1208,30 +1156,17 @@ object ScatterGatherFirstCompletedRouter { * *

Supervision Setup

* - * The router creates a “head” actor which supervises and/or monitors the - * routees. Instances are created as children of this actor, hence the - * children are not supervised by the parent of the router. Common choices are - * to always escalate (meaning that fault handling is always applied to all - * children simultaneously; this is the default) or use the parent’s strategy, - * which will result in routed children being treated individually, but it is - * possible as well to use Routers to give different supervisor strategies to - * different groups of children. + * Any routees that are created by a router will be created as the router's children. + * The router is therefore also the children's supervisor. * - * {{{ - * class MyActor extends Actor { - * override val supervisorStrategy = ... + * The supervision strategy of the router actor can be configured with + * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to + * a strategy of “always escalate”. This means that errors are passed up to the + * router's supervisor for handling. * - * val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(ScatterGatherFirstCompletedRouter(5))) - * - * val poolIndividuals = context.actorOf(Props[SomeActor].withRouter( - * ScatterGatherFirstCompletedRouter(5, supervisorStrategy = this.supervisorStrategy))) - * - * val specialChild = context.actorOf(Props[SomeActor].withRouter( - * ScatterGatherFirstCompletedRouter(5, supervisorStrategy = OneForOneStrategy() { - * ... - * }))) - * } - * }}} + * The router's supervisor will treat the error as an error with the router itself. + * Therefore a directive to stop or restart will cause the router itself to stop or + * restart. The router, in turn, will cause its children to stop and restart. * * @param routees string representation of the actor paths of the routees that will be looked up * using `actorFor` in [[akka.actor.ActorRefProvider]]