Lettuce Java Redis Client

Lettuce is a non-blocking, asynchronous client designed to operate using pipelining by default. This means multiple commands can be sent to the Redis server without waiting for the replies of previous commands.

Key characteristics:

• Thread Safety: Multiple threads can share a single connection. While one thread is waiting for a response, other threads can continue to send new commands.
• Decoupled I/O: Built on Netty, Lettuce decouples reading from writing, allowing commands to be written and read independently but in sequence.
• Async API Behavior: Every invocation on the async API returns a RedisFuture immediately after the command is written to the Netty pipeline, even before it reaches the underlying transport.

Important Constraints for Shared Connections:

• Long-running commands: If a command takes a long time to process, other threads using the same connection will wait longer for their results.
• Transactional commands: Do not use MULTI on a shared connection.
• Blocking commands: Avoid using Redis-blocking commands (e.g., BLPOP) on a shared connection, as they will block all other invocations on that connection. Use dedicated connections for blocking operations.

To use native transports, add the following Maven dependencies based on your platform and requirements:

Linux epoll (x86_64)

Requires Netty version 4.0.26.Final or higher.

Linux io_uring (x86_64)

Requires Netty version 4.1.54.Final or higher. This transport is experimental.

macOS kqueue (x86_64)

Requires Netty version 4.1.11.Final or higher.

<!-- Linux epoll -->
<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <version>${netty-version}</version>
    <classifier>linux-x86_64</classifier>
</dependency>

<!-- Linux io_uring -->
<dependency>
    <groupId>io.netty.incubator</groupId>
    <artifactId>netty-incubator-transport-native-io_uring</artifactId>
    <version>0.0.1.Final</version>
    <classifier>linux-x86_64</classifier>
</dependency>

<!-- macOS kqueue -->
<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-kqueue</artifactId>
    <version>${netty-version}</version>
    <classifier>osx-x86_64</classifier>
</dependency>

Power-user mode is designed for applications that perform little to no processing on the Java layer. In this mode, you work with unprocessed JSON documents that have not undergone deserialization or serialization.

This mode is achieved by using the JsonValue type directly, which can be used in commands like jsonGet and jsonSet without manual parsing.

JsonPath myPath = JsonPath.of("$..mountain_bikes");
RedisURI redisURI = RedisURI.Builder.redis("127.0.0.1").withPort(16379).build();
try (RedisClient client = RedisClient.create(redisURI)) {
    RedisAsyncCommands<String, String> redis = client.connect().async();
    RedisFuture<List<JsonValue>> bikes = redis.jsonGet("bikes:inventory", myPath);

    CompletionStage<RedisFuture<String>> stage = bikes.thenApply(
            fetchedBikes -> redis.jsonSet("service_bikes", JsonPath.ROOT_PATH, fetchedBikes.get(0)));

    String result = stage.toCompletableFuture().get().get();
}

Lettuce supports Brave tracing, creating a span for every Redis command.

Configuration Options

• serviceName: The name of the service (defaults to redis).
• Endpoint customizer: Used with a custom SocketAddressResolver to attach custom endpoint details.
• Span customizer: Allows customization of spans based on the Command object.
• Argument inclusion: You can choose to exclude command arguments from span tags (default is to include all).

Prerequisites

Add brave (at least 5.1) to your Maven pom.xml:

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave</artifactId>
</dependency>

brave.Tracing clientTracing = …;

BraveTracing tracing = BraveTracing.builder().tracing(clientTracing)
    .excludeCommandArgsFromSpanTags()
    .serviceName("custom-service-name-goes-here")
    .spanCustomizer((command, span) -> span.tag("cmd", command.getType().name()))
    .build();

ClientResources resources = ClientResources.builder().tracing(tracing).build();

Provide query corrections for misspelled terms.

• Spell Check: Use ftSpellcheck(index, term) to get corrections. Use SpellCheckArgs to configure distance (Levenshtein distance), terms("include", "dictionary"), and dialect(QueryDialects.DIALECT2).
• Dictionary Management: Manage custom dictionaries for spell checking using ftDictadd(dict, terms...), ftDictdel(dict, term), and ftDictdump(dict) to retrieve all terms.
• Synonym Management: Create synonym groups with ftSynupdate(index, group, terms...). Use SynUpdateArgs.skipInitialScan() to avoid reindexing existing documents.

// Spell check
SpellCheckArgs<String, String> spellArgs = SpellCheckArgs.<String, String>builder()
    .distance(2)
    .terms("include", "dictionary")
    .dialect(QueryDialects.DIALECT2)
    .build();
List<SpellCheckResult<String>> results = search.ftSpellcheck("products-idx", "wireles hedphones", spellArgs);

// Dictionary management
search.ftDictadd("custom_dict", "smartphone", "tablet", "laptop");
List<String> terms = search.ftDictdump("custom_dict");

// Synonym management
search.ftSynupdate("products-idx", "group1", "phone", "smartphone", "mobile");

SynUpdateArgs synArgs = SynUpdateArgs.builder().skipInitialScan().build();
search.ftSynupdate("products-idx", "group1", synArgs, "phone", "smartphone", "mobile", "cellphone");