Migration from 3.x to 4.x

lettuce 4.0 introduces a few breaking changes. If you want to upgrade to 4.x you need to adopt these changes.

Mandatory Changes

Dropped Java 6 and 7 support

You need at least Java 8 to use lettuce 4.0

readOnly and readWrite in the async API

The result type of readOnly and readWrite were changed from String to RedisFuture<String>. The state within the connection updates as soon as the commands complete. You are now able to subscribe to the futures to listen for completion.

Stateful connections

lettuce introduces Stateful Connections to separate connections from API’s. With 4.0 all Redis…​Connection interfaces are deprecated and will be removed in future versions. Stateful connections provide access to sync, async and reactive API’s by providing sync(), async() and reactive() methods. The following connect() methods changed in order to provide access to stateful connections:

• RedisClient.connect provides a StatefulRedisConnection

• RedisClient.connectPubSub provides a StatefulRedisPubSubConnection

You can find more about all new API including the advanced Redis Cluster API in the release notes.

---

Changes if you use the synchronous API for Redis standalone

---

lettuce 3.x Code for obtaining a sync API

RedisClient client = new RedisClient("host");

RedisConnection<String, String> syncConnection = client.connect();

lettuce 4.0 Code for obtaining a sync API

RedisClient client = new RedisClient("host");
StatefulRedisConnection<String, String> connection = client.connect();

// deprecated API
RedisConnection<String, String> syncConnection = connection.sync();

// commands API
RedisCommands<String, String> syncApi = connection.sync();

---

Changes if you use the asynchronous API for Redis Pub/Sub

---

lettuce 3.x Code for obtaining an async pub/sub API

RedisClient client = new RedisClient("host");

RedisPubSubConnection<String, String> syncConnection = client.connectPubSub();

lettuce 4.0 Code for obtaining an async pub/sub API

RedisClient client = new RedisClient("host");
StatefulRedisPubSubConnection<String, String> connection = client.connectPubSub();

// deprecated API
RedisPubSubConnection<String, String> asyncConnection = connection.async();

// commands API
RedisPubSubAsyncCommands<String, String> asyncApi = connection.sync();

---

Changes if you use custom codecs

RedisCodec was in 3.x, an abstract class. This changed with 4.0 to an interface and a consistent return type. The RedisCodec interface accepts and returns ByteBuffer`s instead of `byte[]. A ByteBuffer is not opinionated about the source of the underlying bytes. The byte[] interface required the user to provide an array with the exact data for interchange. So if you have an array where you want to use only a subset, you’re required to create a new instance of a byte array and copy the data. The same applies if you have a different byte source (e.g. netty’s ByteBuf or an NIO ByteBuffer). The `ByteBuffer`s for decoding are pointers to the underlying data. `ByteBuffer`s for encoding data can be either pure pointers or allocated memory. lettuce does not free any memory (such as pooled buffers).

Code example for a byte[] codec with lettuce 3.x:

public byte[] encodeKey(byte[] key) {
    return key;
}

Code example for a byte[] codec with lettuce 4.x:

public ByteBuffer encodeKey(byte[] key) {
    return ByteBuffer.wrap(value);
}

---

Usage of CommandOutput

CommandOutput is relocated from com.lambdaworks.redis.protocol to com.lambdaworks.redis.output. Update your imports.

Usage of SetArgs

SetArgs is relocated from com.lambdaworks.redis.protocol to com.lambdaworks.redis Update your imports.

RedisFuture throws now Exceptions on get()

RedisFuture`s are based on `CompleteableFuture and throw exceptions when accessing the value using get() if any exceptions occurred. The future is now compatible, and Exceptions walk down the `CompletionStage`s.

Optional Changes

These changes are optional and can help to improve your code.

AutoCloseable

All connections are AutoCloseable so you can handle connections using try-with-resources.

Migration Matrix sync API:

• All Redis…Connection interfaces are deprecated and will be removed in future versions. The RedisCommands interface extends RedisConnection until the connection interfaces will be removed.

• 3.x package: com.lambdaworks.redis

• 4.x package: com.lambdaworks.redis.api.sync

New command interfaces:

• RedisCommands

• RedisClusterCommands

• BaseRedisComands

• RedisHashCommands

• RedisHLLCommands

• RedisKeyCommands

• RedisListCommands

• RedisScriptingCommands

• RedisServerCommands

• RedisSetCommands

• RedisSortedSetCommands

• RedisStringsCommands

• RedisTransactionalCommands

• RedisPubSubCommands

Migration Matrix async API:

• All Redis…AsyncConnection interfaces are deprecated and will be removed in future versions. The RedisAsyncCommands interface extends RedisAsyncConnection until the connection interfaces will be removed.

• 3.x package: com.lambdaworks.redis

• 4.x package: com.lambdaworks.redis.api.async

New command interfaces:

• RedisAsyncCommands

• RedisClusterAsyncCommands

• BaseRedisAsyncCommands

• RedisHashAsyncCommands

• RedisHLLAsyncCommands

• RedisKeyAsyncCommands

• RedisListAsyncCommands

• RedisScriptingAsyncCommands

• RedisSentinelAsyncCommands

• RedisServerAsyncCommands

• RedisSetAsyncCommands

• RedisSortedSetAsyncCommands

• RedisStringAsyncCommands

• RedisTransactionalAsyncCommands

• RedisPubSubAsyncCommands