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

=dur #3664 Deprecate durable mailboxes

Browse source
This commit is contained in:
Patrik Nordwall 2013-12-11 13:38:13 +01:00
parent a5b52e9bea
commit 4bd1586b1e
33 changed files with 41 additions and 561 deletions
Download patch file Download diff file Expand all files Collapse all files

44
akka-docs/rst/java/code/docs/actor/mailbox/DurableMailboxDocTest.java
View file

@ -1,44 +0,0 @@
/**
* Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
*/
package docs.actor.mailbox;
//#imports
import akka.actor.Props;
import akka.actor.ActorRef;
//#imports
import akka.testkit.AkkaJUnitActorSystemResource;
import org.junit.ClassRule;
import org.junit.Test;
import akka.testkit.AkkaSpec;
import com.typesafe.config.ConfigFactory;
import akka.actor.ActorSystem;
import akka.actor.UntypedActor;
public class DurableMailboxDocTest {
@ClassRule
public static AkkaJUnitActorSystemResource actorSystemResource =
new AkkaJUnitActorSystemResource("DurableMailboxDocTest",
ConfigFactory.parseString(DurableMailboxDocSpec.config()).withFallback(AkkaSpec.testConf()));
private final ActorSystem system = actorSystemResource.getSystem();
@Test
public void configDefinedDispatcher() {
//#dispatcher-config-use
ActorRef myActor = system.actorOf(Props.create(MyUntypedActor.class).
withDispatcher("my-dispatcher"), "myactor");
//#dispatcher-config-use
myActor.tell("test", ActorRef.noSender());
}
public static class MyUntypedActor extends UntypedActor {
public void onReceive(Object message) {
}
}
}

31
akka-docs/rst/java/code/docs/actor/mailbox/MyDurableMailboxDocSpec.scala
View file

@ -1,31 +0,0 @@
/**
* Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
*/
package docs.actor.mailbox
import akka.actor.mailbox.DurableMailboxSpec
object MyDurableMailboxDocSpec {
val config = """
MyStorage-dispatcher {
mailbox-type = docs.actor.mailbox.MyDurableMailboxType
}
"""
}
class MyDurableMailboxDocSpec extends DurableMailboxSpec("MyStorage", MyDurableMailboxDocSpec.config) {
override def atStartup() {
}
override def afterTermination() {
}
"MyDurableMailbox (Java)" must {
"deliver a message" in {
val actor = createMailboxTestActor()
implicit val sender = testActor
actor ! "hello"
expectMsg("hello")
}
}
}

30
akka-docs/rst/java/code/docs/actor/mailbox/MyDurableMailboxType.java
View file

@ -1,30 +0,0 @@
/**
* Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
*/
package docs.actor.mailbox;
//#custom-mailbox-type
import scala.Option;
import com.typesafe.config.Config;
import akka.actor.ActorRef;
import akka.actor.ActorSystem;
import akka.actor.ExtendedActorSystem;
import akka.dispatch.MailboxType;
import akka.dispatch.MessageQueue;
public class MyDurableMailboxType implements MailboxType {
public MyDurableMailboxType(ActorSystem.Settings settings, Config config) {
}
@Override
public MessageQueue create(Option<ActorRef> owner,
Option<ActorSystem> system) {
if (owner.isEmpty())
throw new IllegalArgumentException("requires an owner " +
"(i.e. does not work with BalancingDispatcher)");
return new MyDurableMessageQueue(owner.get(),
(ExtendedActorSystem) system.get());
}
}
//#custom-mailbox-type

96
akka-docs/rst/java/code/docs/actor/mailbox/MyDurableMessageQueue.java
View file

@ -1,96 +0,0 @@
/**
* Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
*/
package docs.actor.mailbox;
//#durable-message-queue
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.Callable;
import scala.concurrent.duration.Duration;
import akka.actor.ActorRef;
import akka.actor.ExtendedActorSystem;
import akka.actor.mailbox.DurableMessageQueueWithSerialization;
import akka.dispatch.Envelope;
import akka.dispatch.MessageQueue;
import akka.pattern.CircuitBreaker;
public class MyDurableMessageQueue extends DurableMessageQueueWithSerialization {
public MyDurableMessageQueue(ActorRef owner, ExtendedActorSystem system) {
super(owner, system);
}
private final QueueStorage storage = new QueueStorage();
// A real-world implementation would use configuration to set the last
// three parameters below
private final CircuitBreaker breaker = CircuitBreaker.create(system().scheduler(),
5, Duration.create(30, "seconds"), Duration.create(1, "minute"));
@Override
public void enqueue(ActorRef receiver, final Envelope envelope) {
breaker.callWithSyncCircuitBreaker(new Callable<Object>() {
@Override
public Object call() {
byte[] data = serialize(envelope);
storage.push(data);
return null;
}
});
}
@Override
public Envelope dequeue() {
return breaker.callWithSyncCircuitBreaker(new Callable<Envelope>() {
@Override
public Envelope call() {
byte[] data = storage.pull();
if (data == null)
return null;
else
return deserialize(data);
}
});
}
@Override
public boolean hasMessages() {
return breaker.callWithSyncCircuitBreaker(new Callable<Boolean>() {
@Override
public Boolean call() {
return !storage.isEmpty();
}
});
}
@Override
public int numberOfMessages() {
return breaker.callWithSyncCircuitBreaker(new Callable<Integer>() {
@Override
public Integer call() {
return storage.size();
}
});
}
/**
* Called when the mailbox is disposed.
* An ordinary mailbox would send remaining messages to deadLetters,
* but the purpose of a durable mailbox is to continue
* with the same message queue when the actor is started again.
*/
@Override
public void cleanUp(ActorRef owner, MessageQueue deadLetters) {}
//#dummy-queue-storage
// dummy
private static class QueueStorage {
private final ConcurrentLinkedQueue<byte[]> queue =
new ConcurrentLinkedQueue<byte[]>();
public void push(byte[] data) { queue.offer(data); }
public byte[] pull() { return queue.poll(); }
public boolean isEmpty() { return queue.isEmpty(); }
public int size() { return queue.size(); }
}
//#dummy-queue-storage
}
//#durable-message-queue

1
akka-docs/rst/java/code/docs/testkit/TestKitDocTest.java
View file

@ -6,7 +6,6 @@ package docs.testkit;
import static org.junit.Assert.*;
import akka.testkit.*;
import docs.actor.mailbox.DurableMailboxDocSpec;
import org.junit.ClassRule;
import org.junit.Test;

91
akka-docs/rst/java/durable-mailbox.rst
View file

@ -1,91 +0,0 @@
.. _durable-mailboxes-java:
##########################
Durable Mailboxes
##########################
Overview
========
A durable mailbox is a mailbox which stores the messages on durable storage.
What this means in practice is that if there are pending messages in the actor's
mailbox when the node of the actor resides on crashes, then when you restart the
node, the actor will be able to continue processing as if nothing had happened;
with all pending messages still in its mailbox.
You configure durable mailboxes through the dispatcher or the actor deployment (see
:ref:`mailboxes-java`). The actor is oblivious to which type of mailbox it is using.
This gives you an excellent way of creating bulkheads in your application, where
groups of actors sharing the same dispatcher also share the same backing
storage. Read more about that in the :ref:`dispatchers-scala` documentation.
One basic file based durable mailbox is provided by Akka out-of-the-box.
Other implementations can easily be added. Some are available as separate community
Open Source projects, such as:
* `AMQP Durable Mailbox <https://github.com/drexin/akka-amqp-mailbox>`_
A durable mailbox is like any other mailbox not likely to be transactional. It's possible
if the actor crashes after receiving a message, but before completing processing of
it, that the message could be lost.
.. warning::
A durable mailbox typically doesn't work with blocking message send, i.e. the message
send operations that are relying on futures; ``ask``. If the node
has crashed and then restarted, the thread that was blocked waiting for the
reply is gone and there is no way we can deliver the message.
File-based durable mailbox
==========================
This mailbox is backed by a journaling transaction log on the local file
system. It is the simplest to use since it does not require an extra
infrastructure piece to administer, but it is usually sufficient and just what
you need.
In the configuration of the dispatcher you specify the fully qualified class name
of the mailbox:
.. includecode:: ../scala/code/docs/actor/mailbox/DurableMailboxDocSpec.scala
:include: dispatcher-config
Here is an example of how to create an actor with a durable dispatcher:
.. includecode:: code/docs/actor/mailbox/DurableMailboxDocTest.java
:include: imports,dispatcher-config-use
You can also configure and tune the file-based durable mailbox. This is done in
the ``akka.actor.mailbox.file-based`` section in the :ref:`configuration`.
.. literalinclude:: ../../../akka-durable-mailboxes/akka-file-mailbox/src/main/resources/reference.conf
:language: none
How to implement a durable mailbox
==================================
Here is an example of how to implement a custom durable mailbox. Essentially it consists of
a configurator (MailboxType) and a queue implementation (DurableMessageQueue).
The envelope contains the message sent to the actor, and information about sender. It is the
envelope that needs to be stored. As a help utility you can extend DurableMessageQueueWithSerialization
to serialize and deserialize the envelope using the ordinary :ref:`serialization-scala`
mechanism. This optional and you may store the envelope data in any way you like. Durable
mailboxes are an excellent fit for usage of circuit breakers. These are described in the
:ref:`circuit-breaker` documentation.
.. includecode:: code/docs/actor/mailbox/MyDurableMailboxType.java
:include: custom-mailbox-type
.. includecode:: code/docs/actor/mailbox/MyDurableMessageQueue.java
:include: durable-message-queue
:exclude: dummy-queue-storage
For more inspiration you can look at the old implementations based on Redis, MongoDB, Beanstalk,
and ZooKeeper, which can be found in Akka git repository tag
`v2.0.1 <https://github.com/akka/akka/tree/v2.0.1/akka-durable-mailboxes>`_.

1
akka-docs/rst/java/index-utilities.rst
View file

@ -10,5 +10,4 @@ Utilities
../common/duration
../common/circuitbreaker
extending-akka
durable-mailbox
microkernel

2
akka-docs/rst/java/mailboxes.rst
View file

@ -161,8 +161,6 @@ Akka comes shipped with a number of mailbox implementations:
- Configuration name: "akka.dispatch.BoundedPriorityMailbox"
* Durable mailboxes, see :ref:`durable-mailboxes-java`.
Mailbox configuration examples
==============================

4
akka-docs/rst/java/serialization.rst
View file

@ -123,8 +123,8 @@ address which shall be the recipient of the serialized information. Use
This assumes that serialization happens in the context of sending a message
through the remote transport. There are other uses of serialization, though,
e.g. storing actor references outside of an actor application (database,
durable mailbox, etc.). In this case, it is important to keep in mind that the
e.g. storing actor references outside of an actor application (database, etc.).
In this case, it is important to keep in mind that the
address part of an actor’s path determines how that actor is communicated with.
Storing a local actor path might be the right choice if the retrieval happens
in the same logical context, but it is not enough when deserializing it on a