- message queue system
- runs stand-alone (download) or embedded
- Amazon SQS-compatible interface
- fully asynchronous implementation, no blocking calls
ElasticMQ is a message queue system, offering an actor-based Scala and an SQS-compatible REST (query) interface.
ElasticMQ follows the semantics of SQS. Messages are received by polling the queue. When a message is received, it is blocked for a specified amount of time (the visibility timeout). If the message isn't deleted during that time, it will be again available for delivery. Moreover, queues and messages can be configured to always deliver messages with a delay.
The focus in SQS (and ElasticMQ) is to make sure that the messages are delivered. It may happen, however, that a message is delivered twice (if, for example, a client dies after receiving a message and processing it, but before deleting). That's why clients of ElasticMQ (and Amazon SQS) should be idempotent.
As ElasticMQ implements a subset of the SQS query (REST) interface, it is a great SQS alternative both for testing purposes (ElasticMQ is easily embeddable) and for creating systems which work both within and outside of the Amazon infrastructure.
The future will most probably bring even more exciting features :).
- Blog
- Forum (discussions, help): Google group.
You can download the stand-alone distribution here: https://s3/.../elasticmq-server-0.8.2.jar
Java 6 or above is required for running the server.
Simply run the jar and you should get a working server, which binds to localhost:9324:
java -jar elasticmq-server-0.8.2.jar
ElasticMQ uses Typesafe Config for configuration. To specify custom
configuration values, create a file (e.g. custom.conf), fill it in with the desired values, and pass it to the server:
java -Dconfig.file=custom.conf -jar elasticmq-server-0.8.2.jar
The config file may contain any configuration for Akka, Spray and ElasticMQ. Current ElasticMQ configuration values are:
include classpath("application.conf")
// What is the outside visible address of this ElasticMQ node (used by rest-sqs)
node-address {
protocol = http
host = localhost
port = 9324
context-path = ""
}
rest-sqs {
enabled = true
bind-port = 9324
bind-hostname = "0.0.0.0"
// Possible values: relaxed, strict
sqs-limits = relaxed
}
By default the maximum SQS message wait time is 20 seconds, and the maximum duration of a request is set to 21 seconds.
To change that (e.g. if you want longer message wait times), adjust the spray.can.server.request-timeout configuration
property.
You can also provide an alternative Logback configuration file (the default is configured to log INFO logs and above to the console):
java -Dlogback.configurationFile=my_logback.xml -jar elasticmq-server-0.8.2.jar
val server = SQSRestServerBuilder.start()
// ... use ...
server.stopAndWait()
If you need to bind to a different host/port, there are configuration methods on the builder:
val server = SQSRestServerBuilder.withPort(9325).withInterface("localhost").start()
// ... use ...
server.stopAndWait()
You can also provide a custom ActorSystem; for details see the javadocs.
Embedded ElasticMQ can be used from any JVM-based language (Java, Scala, etc.).
To use Amazon Java SDK as an interface to an ElasticMQ server you just need to change the endpoint:
client = new AmazonSQSClient(new BasicAWSCredentials("x", "x"))
client.setEndpoint("http://localhost:9324", "sqs", "")
The endpoint value should be the same address as the NodeAddress provided as an argument to
SQSRestServerBuilder or in the configuration file.
The rest-sqs-testing-amazon-java-sdk module contains some more usage examples.
// Scala 2.11
val elasticmqSqs = "org.elasticmq" %% "elasticmq-rest-sqs" % "0.8.2"
// Scala 2.10
val elasticmqSqs = "org.elasticmq" %% "elasticmq-rest-sqs" % "0.7.1"
If you don't want the SQS interface, but just use the actors directly, you can add a dependency only to the core
module:
val elasticmqCore = "org.elasticmq" %% "elasticmq-core" % "0.8.2"
Repository:
resolvers += "SoftwareMill Releases" at "https://nexus.softwaremill.com/content/repositories/releases"
(ElasticMQ 0.8.2 cannot be deployed to Maven Central as its dependency - Spray - isn't deployed there yet.)
If you want to use a snapshot version, you will need to add the https://oss.sonatype.org/content/repositories/snapshots/ repository to your configuration.
Dependencies:
<dependency>
<groupId>org.elasticmq</groupId>
<artifactId>elasticmq-rest-sqs_2.11</artifactId>
<version>0.8.2</version>
</dependency>
Repository:
<repository>
<id>softwaremill-releases</id>
<url>https://nexus.softwaremill.com/content/repositories/releases</url>
</repository>
If you want to use a snapshot version, you will need to add the https://oss.sonatype.org/content/repositories/snapshots/ repository to your configuration.
Until version 0.7.0, ElasticMQ included optional replication, journaling and an SQL message storage. These modules have not yet been reimplemented using the new Akka core.
Stable: 0.8.2
Development: 0.8.3-SNAPSHOT
ElasticMQ uses Slf4j for logging. By default no logger backend is included as a dependency, however Logback is recommended.
Tests done on a 2012 MBP, 2.6GHz, 16GB RAM, no replication. Throughput is in messages per second (messages are small).
Directly accessing the client:
Running test for [in-memory], iterations: 10, msgs in iteration: 100000, thread count: 1.
Overall in-memory throughput: 21326.054040
Running test for [in-memory], iterations: 10, msgs in iteration: 100000, thread count: 2.
Overall in-memory throughput: 26292.956117
Running test for [in-memory], iterations: 10, msgs in iteration: 100000, thread count: 10.
Overall in-memory throughput: 25591.155697
Through the SQS REST interface:
Running test for [rest-sqs + in-memory], iterations: 10, msgs in iteration: 1000, thread count: 20.
Overall rest-sqs + in-memory throughput: 2540.553587
Running test for [rest-sqs + in-memory], iterations: 10, msgs in iteration: 1000, thread count: 40.
Overall rest-sqs + in-memory throughput: 2600.002600
Note that both the client and the server were on the same machine.
Test class: org.elasticmq.performance.LocalPerformanceTest.
- Core: Scala and Akka.
- Rest server: Spray, a high-performance, asynchronous, REST/HTTP toolkit.
- Testing the SQS interface: Amazon Java SDK;
see the
rest-sqs-testing-amazon-java-sdkmodule for the testsuite.
- increasing the bind timeout
- initial support for
String-valued message attributes (thx @hayesgm)
- fixing Node.JS compatibility
- fixing a bug when calculating queue attributes
- updating to Scala 2.11.1, Akka 2.3.3
- updating to Scala 2.11, Akka 2.3.2
- updating libraries to latest versions
- bug fixes
- reimplemented using Akka and Spray (actor-based, no blocking)
- long polling support
- bug fixes
- Scala 2.10 support
- Changing the way the stand-alone server is configured
- bug fixes
- properly handling SQS receipt handles - message can be deleted only when passing the most recent receipt handle
- using Sonatype's OSS repositories for releases
- library upgrades
- batch operations in SQS (send, receive, delete, change visibility)
- changed
SQSRestServerFactorytoSQSRestServerBuilder - "strict" and "relaxed" modes when creating an SQS server: the limits enforced by SQS are optionally checked, e.g. for batch operations (max 10 messages), maximum message size (64KB). Strict by default.
- stand-alone distribution (download)
- file log for message storage (journal)
- factoring out
storage-databasemodule, to decrease the dependencies of the core modules
- replication
- in-memory storage
- new native API
- bug fixes
- new SQS functions support
- testing with Amazon Java SDK
- bug fixes
- initial release
- DB storage
- SQS interface support
