Folsom is an attempt at a small and stable memcache client. Folsom is fully asynchronous, based on Netty and uses Java 8's CompletionStage through-out the API.
Folsom is meant to be used as a library embedded in other software.
To import it with maven, use this:
<!-- In dependencyManagement section -->
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom-bom</artifactId>
<version>1.14.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- In dependencies section -->
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom</artifactId>
</dependency>
<!-- optional if you want to expose folsom metrics with spotify-semantic-metrics -->
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom-semantic-metrics</artifactId>
</dependency>
<!-- optional if you want to expose folsom metrics with yammer -->
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom-yammer-metrics</artifactId>
</dependency>
<!-- optional if you want to expose folsom tracing with OpenCensus -->
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom-opencensus</artifactId>
</dependency>
<!-- optional if you want to use AWS ElastiCache auto-discovery -->
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom-elasticache</artifactId>
</dependency>
If you want to use one of the metrics or tracing libraries, make sure you use the same version as the main artifact.
We are using semantic versioning
The main entry point to the folsom API is the MemcacheClientBuilder class. It has chainable setter methods to configure various aspects of the client. The methods connectBinary() and connectAscii() constructs MemcacheClient instances utilising the binary protocol and ascii protocol respectively. For details on their differences see Protocol below.
All calls to the folsom API that interacts with a memcache server is asynchronous and the result is typically accessible from CompletionStage instances. An exception to this rule are the methods that connects clients to their remote endpoints, MemcacheClientBuilder.connectBinary() and MemcacheClientBuilder.connectAscii() which will return a MemcacheClient immediately while asynchronously attempting to connect to the configured remote endpoint(s).
As code using the folsom API should be written so that it handles failing intermittently with MemcacheClosedException anyway, waiting for the initial connect to complete is not something folsom concerns itself with. For single server connections, ConnectFuture provides functionality to wait for the initial connection to succeed, as can be seen in the example below.
final MemcacheClient<String> client = MemcacheClientBuilder.newStringClient()
.withAddress(hostname)
.connectAscii();
// make it wait until the client has connected to the server
ConnectFuture.connectFuture(client).toCompletableFuture().get();
client.set("key", "value", 10000).toCompletableFuture().get();
client.get("key").toCompletableFuture().get();
client.shutdown();
Clients are single use, after shutdown
has been invoked the client can no
longer be used.
Serializable
typesOne can simply use MemcacheClientBuilder.<T>newSerializableObjectClient()
method to create a client that works for a specific Java type that implements Serializable
.
public record Student(String name, int age) implements Serializable { }
public static void main(String[] args) throws Exception {
MemcacheClient<Student> client =
MemcacheClientBuilder.<Student>newSerializableObjectClient()
.withAddress("localhost")
.connectAscii();
// make it wait until the client has connected to the server
ConnectFuture.connectFuture(client).toCompletableFuture().get();
client.set("s1", new Student("Elon", 28), 10000).toCompletableFuture().get();
Student value = client.get("s1").toCompletableFuture().get();
}
If you are still on Java 7, you can depend on the older version:
<dependency>
<groupId>com.spotify</groupId>
<artifactId>folsom</artifactId>
<version>0.8.1</version>
</dependency>
Do not use withConnectionTimeoutMillis()
or the deprecated withRequestTimeoutMillis()
to set timeouts per request.
This is intended to detect broken TCP connections to close it and recreate it. Once this happens, all open
requests will be completed with a failure and Folsom will try to recreate the connection. If this timeout is set too low,
this will create connection flapping which will result in an increase of failed requests and/or increased
request latencies.
A better way of setting timeouts on individual requests (in Java 9+) is something like this:
CompletableFuture<T> future = client.get(...)
.toCompletableFuture()
.orTimeout(...)
.whenCompleteAsync((v, e) -> {}, executor);
Note that in case of timeouts, the futures from orTimeout
would all be completed on a singleton thread, which may cause contention.
To avoid problems with that, we add whenCompleteAsync
to ensure that
the work is moved to an executor that has sufficient threads.
Folsom implements both the binary protocol and ascii protocol. They share a common interface but also extend it with their own specializations.
Which protocol to use depends on your use case. With a regular memcached backend, the ascii protocol is much more efficient. The binary protocol is a bit chattier but also makes error detection easier.
interface MemcacheClient<T> {}
interface AsciiMemcacheClient<T> extends MemcacheClient<T> {}
interface BinaryMemcacheClient<T> extends MemcacheClient<T> {}
See changelog.
Folsom support Ketama for sharing across a set of memcache servers. Note that the caching algorithm (currently) doesn't attempt to provide compatibility with other memcache clients, and thus when switching client implementation you will get a period of low cache hit ratio.
You can optionally choose to track performance using
Micrometer metrics.
You will need to include the folsom-micrometer-metrics
dependency and initialize
using MemcacheClientBuilder. (Optionally add additional tags):
builder.withMetrics(new MicrometerMetrics(metricsRegistry));
You can optionally choose to track performance using
Yammer metrics.
You will need to include the folsom-yammer-metrics
dependency and initialize
using MemcacheClientBuilder:
builder.withMetrics(new YammerMetrics(metricsRegistry));
You can optionally choose to track performance using
OpenTelemetry metrics.
You will need to include the folsom-opentelemetry-metrics
dependency and initialize
using MemcacheClientBuilder:
builder.withMetrics(new OpenTelemetryMetrics(metricsRegistry));
You can optionally use OpenCensus to trace Folsom operations.
You will need to include the folsom-opencensus
dependency and initialize tracing
using MemcacheClientBuilder:
builder.withTracer(OpenCensus.tracer());
Nodes in a memcache clusters can be auto-discovered. Folsom supports discovery through
DNS SRV records using the com.spotify.folsom.SrvResolver
or AWS ElastiCache using the
com.spotify.folsom.elasticache.ElastiCacheResolver
.
SrvResolver:
builder.withResolver(SrvResolver.newBuilder("foo._tcp.example.org").build());
ElastiCacheResolver:
builder.withResolver(ElastiCacheResolver.newBuilder("cluster-configuration-endpoint-hostname").build());
mvn package
This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.
Folsom was initially built at Spotify by Kristofer Karlsson, Niklas Gustavsson and Daniel Norberg. Many thanks also go out to Noa Resare.