This project provides implementations of some common enterprise integration patterns and other more general patterns for Akka. Many of these patterns are straightforward to implement and certainly not rocket science, but are not provided out of the box in akka. Therefore it's useful to have a single library that is well tested and saves each project re-inventing the wheel. Contributions welcome.

The EnvelopingActor will wrap any incoming messages in an Envelope object, together with attributes describing that message. This pattern is used when you need to associate metadata with the message. The typical example would be when a correlation id is needed for a message exchange.

The CountdownLatch will buffer incoming messages until a predefined limit has been reached. Once the limit is reached it will then dispatch the buffered messages and any further messages will be sent as normal. This can be thought of as the actor equivalent of the Java CountdownLatch concurrency primitive.

The GroupingActor will buffer incoming messages into lists of a predefined size. Once the required number of messages has been received then those messages will be sent to the target actor as an array of messages. This is useful when you want to process messages in batches.

The TimeoutFlowControlActor is an actor that will send messages to a target actor while ensuring that the number of outstanding (yet to be acknowledged messages) does not exceed a set threshold. Each time an ack is received the next buffered message is sent. If no ack is received within a set period of time then that message is considered lost and the next message is sent. This actor is similar to how TCP flow control works except without the reliability side.

The ReliableFlowControlActor will ensure delivery of messages to a target actor while ensuring that the number of outstanding (yet to be acknowledged messages) does not exceed a set threshold. Each time an ack is received the next buffered message is sent. If no ack is received within a user defined duration then the message is resent. This actor is similar to how TCP flow control works.

The AcknowledgingActor is an actor that will send an ack to the sender as soon as a message is received. This actor is most often used as the other end to the flow control actors.

The Aggregator will combine messages with the same correlation id and then dispatch as an array to the target. The aggregating actor is created with the types of messages that are required before a "complete" message is ready.

The PeriodicActor broadcasts tick messages at a user defined interval interleaved with the normal messages it receives. These tick messages can be used by an implementing actor to perform logic based on durations.

The TimeoutActor will terminate itself if a message is not received within a user defined duration. This actor is useful for implementing session time out patterns.

The KeepAliveActor will send a heartbeat after a user defined duration has passed without another message being received. Each time a message is received then the heartbeat countdown is reset. This actor is analogous to the keep-alive pings you would see in a TCP connection.

The PausableActor is a finite state machine with two states - paused or running. If paused then any messages are buffered until the actor is resumed. If the actor is running then all messages are forwarded as normal to the target actor.

The Splitter accepts collections of messages and dispatches them singularly to a target actor. The actor understands messages of type Iterable, Iterator, Array, Java Iterables and Java Iterators.

The Resequencer receives out of sequence messages and publishes them in order. The actor uses a Sequence Id on the message envelope to order the messages. If a message is received out of order it is buffered until the expected message arrives.

The DiscardingThrottlingActor is a rate limiting actor that will send messages with a minimum defined interval. Any messages received during this minimum interval will be discarded, with the exception of the most recent, which will be sent once the interval has expired. This pattern is useful for cases such as FX quotes where only the most recent is required and the receiver can be overloaded (hence the need for throttling).

The BufferingThrottlingActor is a rate limiting actor that will send messages with a minimum defined interval. Any messages received during this minimum interval will be buffered and replayed at the defined interval. This pattern is useful when an erratic incoming stream is required to be converted to a consistent stream.

The DiscardingBarrier accepts a collection of message types and waits until at least one message of each specified type has been received. While blocked any messages received are discarded. Once all message types have been received, then the barrier is unlocked and then it will forward all future messages to the target actor.

The BufferingBarrier accepts a collection of message types and waits until at least one message of each specified type has been received. While blocked any messages received are blocked. Once all message types have been received, then the barrier is unlocked and then it will forward all buffered and future messages to the target actor.

The WorkpileMaster and WorkpileWorker specify a way of using worker-pull semantics. When a worker starts it requests work from the master. If work is available it is sent a packet of work and once complete will request another. If no work is currently available the master will queue all workers until work arrives. If when work arrives there are no free workers then the master will queue the work until the next worker is available.

The LifoMailbox processes messages last in first out.

The PriorityMailbox processes messages in a priority queue. The messages must be of type Envelope with an attached attribute for the priority. If the priority is not specified then it is assumed to be of least importance and will be processed after all pending messages that have a defined priority.

The ExpiringMailbox processes messages first in first out but with an additional timeout per message. If the message is not processed before the timeout for that message then it is discarded.

The OneTimeRouter routes messages to routees that are created for the processing of that single message. After processing that message they are then terminated via a poison pill message.

To use in an SBT project add the dependency:

libraryDependencies += "com.sksamuel.akka" % "akka-patterns_2.11" % "VERSION"

And Maven users should add:

<dependency>
    <groupId>com.sksamuel.akka</groupId>
    <artifactId>akka-patterns_2.11</artifactId>
    <version>VERISON</version>
</dependency>

You can always find the latest version using the links at the top.

This software is licensed under the Apache 2 license, quoted below.

Copyright 2013 Stephen Samuel

Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.