-
Notifications
You must be signed in to change notification settings - Fork 987
Codecs (3.x)
❗️Documentation page for lettuce 3.x. Find the recent documentation for lettuce 4.x here: Codecs
Codecs are a pluggable mechanism for transcoding keys and values between your application and Redis. The default codec supports UTF-8 encoded String keys and values.
Each connection may have its codec passed to the extended
RedisClient.connect
methods:
RedisConnection<K, V> connect(RedisCodec<K, V> codec)
RedisAsyncConnection<K, V> connectAsync(RedisCodec<K, V> codec)
RedisPubSubConnection<K, V> connectPubSub(RedisCodec<K, V> codec)
lettuce ships with two predefined codecs:
-
com.lambdaworks.redis.codec.ByteArrayCodec
- usebyte[]
for keys and values -
com.lambdaworks.redis.codec.Utf8StringCodec
- use Strings for keys and values and convert Strings using UTF-8 to store them within Redis
Publish/Subscribe connections use channel names and patterns for keys, messages are treated as values.
Keys and values can be encoded independently from each other which means the key can be a java.lang.String
while the value is a byte[]
. Many other constellations are possible like:
- Representing your data as JSON if your data is mapped to a particular Java type. Different types are hard to map since the codec applies to all operations.
- Serialize your data using the Java Serializer (
ObjectInputStream
/ObjectOutputStream
). Allows type-safe conversions but is less interoperable with other languages - Serializing your data using Kryo for improved type-safe serialization.
- Any specialized codecs like the
BitStringCodec
(see below)
Like in every other segment of technology, there is no one-fits-it-all solution when it comes to Codecs. Redis data structures provide a variety of The key and value limitation of codecs is intentionally and a balance amongst convenience and simplicity. The Redis API allows much more variance in encoding and decoding particular data elements. A good example is Redis hashes. A hash is identified by its key but stores another key/value pairs. The keys of the key-value pairs could be encoded using a different approach than the key of the hash. Another different approach might be to use different encodings between lists and sets. Using a base codec (such as UTF-8 or byte array) and performing an own conversion on top of the base codec is often the better idea.
A key point in Codecs is that Codecs are shared resources and can be used by multiple threads. Your Codec needs to be thread-safe (by shared-nothing, pooling or synchronization). Every logical lettuce connection uses its codec instance. Codec instances are shared as soon as multiple threads are issuing commands or if you use Redis Cluster.
BitString codec
public class BitStringCodec extends Utf8StringCodec {
@Override
public String decodeValue(ByteBuffer bytes) {
StringBuilder bits = new StringBuilder(bytes.remaining() * 8);
while (bytes.remaining() > 0) {
byte b = bytes.get();
for (int i = 0; i < 8; i++) {
bits.append(Integer.valueOf(b >>> i & 1));
}
}
return bits.toString();
}
}
RedisConnection<String, String> redis = client.connect(new BitStringCodec());
redis.setbit(key, 0, 1);
redis.setbit(key, 1, 1);
redis.setbit(key, 2, 0);
redis.setbit(key, 3, 0);
redis.setbit(key, 4, 0);
redis.setbit(key, 5, 1);
redis.get(key) == "00100011"
Java serialized object
public class SerializedObjectCodec extends RedisCodec<String, Object> {
private Charset charset = Charset.forName("UTF-8");
@Override
public String decodeKey(ByteBuffer bytes) {
return charset.decode(bytes).toString();
}
@Override
public Object decodeValue(ByteBuffer bytes) {
try {
byte[] array = new byte[bytes.remaining()];
bytes.get(array);
ObjectInputStream is = new ObjectInputStream(new ByteArrayInputStream(array));
return is.readObject();
} catch (Exception e) {
return null;
}
}
@Override
public byte[] encodeKey(String key) {
return charset.encode(key).array();
}
@Override
public byte[] encodeValue(Object value) {
try {
ByteArrayOutputStream bytes = new ByteArrayOutputStream();
ObjectOutputStream os = new ObjectOutputStream(bytes);
os.writeObject(value);
return bytes.toByteArray();
} catch (IOException e) {
return null;
}
}
}
Lettuce documentation was moved to https://redis.github.io/lettuce/overview/
Intro
Getting started
- Getting started
- Redis URI and connection details
- Basic usage
- Asynchronous API
- Reactive API
- Publish/Subscribe
- Transactions/Multi
- Scripting and Functions
- Redis Command Interfaces
- FAQ
HA and Sharding
Advanced usage
- Configuring Client resources
- Client Options
- Dynamic Command Interfaces
- SSL Connections
- Native Transports
- Unix Domain Sockets
- Streaming API
- Events
- Command Latency Metrics
- Tracing
- Stateful Connections
- Pipelining/Flushing
- Connection Pooling
- Graal Native Image
- Custom commands
Integration and Extension
Internals