Package io.lettuce.core

Class RedisClient

java.lang.Object

io.lettuce.core.AbstractRedisClient

io.lettuce.core.RedisClient

All Implemented Interfaces:

AutoCloseable

public class RedisClient
extends AbstractRedisClient

A scalable and thread-safe Redis client supporting synchronous, asynchronous and reactive execution models. Multiple threads may share one connection if they avoid blocking and transactional operations such as BLPOP and MULTI/EXEC.

RedisClient can be used with:

• Redis Standalone
• Redis Pub/Sub
• Redis Sentinel, Sentinel connections
• Redis Sentinel, Upstream connections

Redis Cluster is used through RedisClusterClient. Upstream/Replica connections through MasterReplica provide connections to Redis Upstream/Replica ("Master/Slave") setups which run either in a static Upstream/Replica setup or are managed by Redis Sentinel.

RedisClient is an expensive resource. It holds a set of netty's EventLoopGroup's that use multiple threads. Reuse this instance as much as possible or share a ClientResources instance amongst multiple client instances.

Author:

Will Glozer, Mark Paluch

See Also:

RedisURI, StatefulRedisConnection, RedisFuture, Mono, Flux, RedisCodec, ClientOptions, ClientResources, MasterReplica, RedisClusterClient

Field Summary

Fields inherited from class io.lettuce.core.AbstractRedisClient

channels, closeableResources, connectionEvents

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	RedisClient()	Creates a uri-less RedisClient.
protected	RedisClient(ClientResources clientResources, RedisURI redisURI)

Method Summary

Modifier and Type	Method	Description
StatefulRedisConnection<String,String>	connect()	Open a new connection to a Redis server that treats keys and values as UTF-8 strings.
<K,V> StatefulRedisConnection<K,V>	connect(RedisCodec<K,V> codec)	Open a new connection to a Redis server.
<K,V> StatefulRedisConnection<K,V>	connect(RedisCodec<K,V> codec, RedisURI redisURI)	Open a new connection to a Redis server using the supplied RedisURI and the supplied codec to encode/decode keys.
StatefulRedisConnection<String,String>	connect(RedisURI redisURI)	Open a new connection to a Redis server using the supplied RedisURI that treats keys and values as UTF-8 strings.
<K,V> ConnectionFuture<StatefulRedisConnection<K,V>>	connectAsync(RedisCodec<K,V> codec, RedisURI redisURI)	Open asynchronously a new connection to a Redis server using the supplied RedisURI and the supplied codec to encode/decode keys.
StatefulRedisPubSubConnection<String,String>	connectPubSub()	Open a new pub/sub connection to a Redis server that treats keys and values as UTF-8 strings.
<K,V> StatefulRedisPubSubConnection<K,V>	connectPubSub(RedisCodec<K,V> codec)	Open a new pub/sub connection to the Redis server using the supplied RedisURI and use the supplied codec to encode/decode keys and values.
<K,V> StatefulRedisPubSubConnection<K,V>	connectPubSub(RedisCodec<K,V> codec, RedisURI redisURI)	Open a new pub/sub connection to the Redis server using the supplied RedisURI and use the supplied codec to encode/decode keys and values.
StatefulRedisPubSubConnection<String,String>	connectPubSub(RedisURI redisURI)	Open a new pub/sub connection to a Redis server using the supplied RedisURI that treats keys and values as UTF-8 strings.
<K,V> ConnectionFuture<StatefulRedisPubSubConnection<K,V>>	connectPubSubAsync(RedisCodec<K,V> codec, RedisURI redisURI)	Open asynchronously a new pub/sub connection to the Redis server using the supplied RedisURI and use the supplied codec to encode/decode keys and values.
StatefulRedisSentinelConnection<String,String>	connectSentinel()	Open a connection to a Redis Sentinel that treats keys and values as UTF-8 strings.
<K,V> StatefulRedisSentinelConnection<K,V>	connectSentinel(RedisCodec<K,V> codec)	Open a connection to a Redis Sentinel that treats keys and use the supplied codec to encode/decode keys and values.
<K,V> StatefulRedisSentinelConnection<K,V>	connectSentinel(RedisCodec<K,V> codec, RedisURI redisURI)	Open a connection to a Redis Sentinel using the supplied RedisURI and use the supplied codec to encode/decode keys and values.
StatefulRedisSentinelConnection<String,String>	connectSentinel(RedisURI redisURI)	Open a connection to a Redis Sentinel using the supplied RedisURI that treats keys and values as UTF-8 strings.
<K,V> CompletableFuture<StatefulRedisSentinelConnection<K,V>>	connectSentinelAsync(RedisCodec<K,V> codec, RedisURI redisURI)	Open asynchronously a connection to a Redis Sentinel using the supplied RedisURI and use the supplied codec to encode/decode keys and values.
static RedisClient	create()	Creates a uri-less RedisClient with default ClientResources.
static RedisClient	create(RedisURI redisURI)	Create a new client that connects to the supplied uri with default ClientResources.
static RedisClient	create(ClientResources clientResources)	Creates a uri-less RedisClient with shared ClientResources.
static RedisClient	create(ClientResources clientResources, RedisURI redisURI)	Create a new client that connects to the supplied uri with shared ClientResources.
static RedisClient	create(ClientResources clientResources, String uri)	Create a new client that connects to the supplied uri with shared ClientResources.You need to shut down the ClientResources upon shutting down your application.
static RedisClient	create(String uri)	Create a new client that connects to the supplied uri with default ClientResources.
protected Mono<SocketAddress>	getSocketAddress(RedisURI redisURI)	Get a Mono that resolves RedisURI to a SocketAddress.
protected <K,V> StatefulRedisConnectionImpl<K,V>	newStatefulRedisConnection(RedisChannelWriter channelWriter, PushHandler pushHandler, RedisCodec<K,V> codec, Duration timeout)	Create a new instance of StatefulRedisConnectionImpl or a subclass.
protected <K,V> StatefulRedisPubSubConnectionImpl<K,V>	newStatefulRedisPubSubConnection(PubSubEndpoint<K,V> endpoint, RedisChannelWriter channelWriter, RedisCodec<K,V> codec, Duration timeout)	Create a new instance of StatefulRedisPubSubConnectionImpl or a subclass.
protected <K,V> StatefulRedisSentinelConnectionImpl<K,V>	newStatefulRedisSentinelConnection(RedisChannelWriter channelWriter, RedisCodec<K,V> codec, Duration timeout)	Create a new instance of StatefulRedisSentinelConnectionImpl or a subclass.
protected RedisCodec<String,String>	newStringStringCodec()	Returns a String codec.
void	setOptions(ClientOptions clientOptions)	Set the ClientOptions for the client.

Methods inherited from class io.lettuce.core.AbstractRedisClient

addListener, addListener, channelType, close, connectionBuilder, connectionBuilder, createHandshake, getChannelCount, getCommandListeners, getConnection, getConnection, getDefaultTimeout, getOptions, getResourceCount, getResources, initializeChannelAsync, removeListener, removeListener, setDefaultTimeout, setDefaultTimeout, shutdown, shutdown, shutdown, shutdownAsync, shutdownAsync

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RedisClient

protected RedisClient(ClientResources clientResources,
                      RedisURI redisURI)

RedisClient

protected RedisClient()

Creates a uri-less RedisClient. You can connect to different Redis servers but you must supply a RedisURI on connecting. Methods without having a RedisURI will fail with a IllegalStateException. Non-private constructor to make RedisClient proxyable.

Method Detail

create

public static RedisClient create()

Creates a uri-less RedisClient with default ClientResources. You can connect to different Redis servers but you must supply a RedisURI on connecting. Methods without having a RedisURI will fail with a IllegalStateException.

Returns:

a new instance of RedisClient

create

public static RedisClient create(RedisURI redisURI)

Create a new client that connects to the supplied uri with default ClientResources. You can connect to different Redis servers but you must supply a RedisURI on connecting.

Parameters:

redisURI - the Redis URI, must not be null

Returns:

a new instance of RedisClient

create

public static RedisClient create(String uri)

Create a new client that connects to the supplied uri with default ClientResources. You can connect to different Redis servers but you must supply a RedisURI on connecting.

Parameters:

uri - the Redis URI, must not be null

Returns:

a new instance of RedisClient

create

public static RedisClient create(ClientResources clientResources)

Creates a uri-less RedisClient with shared ClientResources. You need to shut down the ClientResources upon shutting down your application. You can connect to different Redis servers but you must supply a RedisURI on connecting. Methods without having a RedisURI will fail with a IllegalStateException.

Parameters:

clientResources - the client resources, must not be null

Returns:

a new instance of RedisClient

create

public static RedisClient create(ClientResources clientResources,
                                 String uri)

Create a new client that connects to the supplied uri with shared ClientResources.You need to shut down the ClientResources upon shutting down your application. You can connect to different Redis servers but you must supply a RedisURI on connecting.

Parameters:

clientResources - the client resources, must not be null

uri - the Redis URI, must not be null

Returns:

a new instance of RedisClient

create

public static RedisClient create(ClientResources clientResources,
                                 RedisURI redisURI)

Create a new client that connects to the supplied uri with shared ClientResources. You need to shut down the ClientResources upon shutting down your application.You can connect to different Redis servers but you must supply a RedisURI on connecting.

Parameters:

clientResources - the client resources, must not be null

redisURI - the Redis URI, must not be null

Returns:

a new instance of RedisClient

connect

public StatefulRedisConnection<String,String> connect()

Open a new connection to a Redis server that treats keys and values as UTF-8 strings.

Returns:

A new stateful Redis connection

connect

public <K,V> StatefulRedisConnection<K,V> connect(RedisCodec<K,V> codec)

Open a new connection to a Redis server. Use the supplied codec to encode/decode keys and values.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

Returns:

A new stateful Redis connection

connect

public StatefulRedisConnection<String,String> connect(RedisURI redisURI)

Open a new connection to a Redis server using the supplied RedisURI that treats keys and values as UTF-8 strings.

Parameters:

redisURI - the Redis server to connect to, must not be null

Returns:

A new connection

connect

public <K,V> StatefulRedisConnection<K,V> connect(RedisCodec<K,V> codec,
                                                              RedisURI redisURI)

Open a new connection to a Redis server using the supplied RedisURI and the supplied codec to encode/decode keys.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

redisURI - the Redis server to connect to, must not be null

Returns:

A new connection

connectAsync

public <K,V> ConnectionFuture<StatefulRedisConnection<K,V>> connectAsync(RedisCodec<K,V> codec,
                                                                                     RedisURI redisURI)

Open asynchronously a new connection to a Redis server using the supplied RedisURI and the supplied codec to encode/decode keys.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

redisURI - the Redis server to connect to, must not be null

Returns:

ConnectionFuture to indicate success or failure to connect.

Since:

5.0

connectPubSub

public StatefulRedisPubSubConnection<String,String> connectPubSub()

Open a new pub/sub connection to a Redis server that treats keys and values as UTF-8 strings.

Returns:

A new stateful pub/sub connection

connectPubSub

public StatefulRedisPubSubConnection<String,String> connectPubSub(RedisURI redisURI)

Open a new pub/sub connection to a Redis server using the supplied RedisURI that treats keys and values as UTF-8 strings.

Parameters:

redisURI - the Redis server to connect to, must not be null

Returns:

A new stateful pub/sub connection

connectPubSub

public <K,V> StatefulRedisPubSubConnection<K,V> connectPubSub(RedisCodec<K,V> codec)

Open a new pub/sub connection to the Redis server using the supplied RedisURI and use the supplied codec to encode/decode keys and values.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

Returns:

A new stateful pub/sub connection

connectPubSub

public <K,V> StatefulRedisPubSubConnection<K,V> connectPubSub(RedisCodec<K,V> codec,
                                                                          RedisURI redisURI)

Open a new pub/sub connection to the Redis server using the supplied RedisURI and use the supplied codec to encode/decode keys and values.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

redisURI - the Redis server to connect to, must not be null

Returns:

A new connection

connectPubSubAsync

public <K,V> ConnectionFuture<StatefulRedisPubSubConnection<K,V>> connectPubSubAsync(RedisCodec<K,V> codec,
                                                                                                 RedisURI redisURI)

Open asynchronously a new pub/sub connection to the Redis server using the supplied RedisURI and use the supplied codec to encode/decode keys and values.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

redisURI - the redis server to connect to, must not be null

Returns:

ConnectionFuture to indicate success or failure to connect.

Since:

5.0

connectSentinel

public StatefulRedisSentinelConnection<String,String> connectSentinel()

Open a connection to a Redis Sentinel that treats keys and values as UTF-8 strings.

Returns:

A new stateful Redis Sentinel connection

connectSentinel

public <K,V> StatefulRedisSentinelConnection<K,V> connectSentinel(RedisCodec<K,V> codec)

Open a connection to a Redis Sentinel that treats keys and use the supplied codec to encode/decode keys and values. The client RedisURI must contain one or more sentinels.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - Use this codec to encode/decode keys and values, must not be null

Returns:

A new stateful Redis Sentinel connection

connectSentinel

public StatefulRedisSentinelConnection<String,String> connectSentinel(RedisURI redisURI)

Open a connection to a Redis Sentinel using the supplied RedisURI that treats keys and values as UTF-8 strings. The client RedisURI must contain one or more sentinels.

Parameters:

redisURI - the Redis server to connect to, must not be null

Returns:

A new connection

connectSentinel

public <K,V> StatefulRedisSentinelConnection<K,V> connectSentinel(RedisCodec<K,V> codec,
                                                                              RedisURI redisURI)

Open a connection to a Redis Sentinel using the supplied RedisURI and use the supplied codec to encode/decode keys and values. The client RedisURI must contain one or more sentinels.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - the Redis server to connect to, must not be null

redisURI - the Redis server to connect to, must not be null

Returns:

A new connection

connectSentinelAsync

public <K,V> CompletableFuture<StatefulRedisSentinelConnection<K,V>> connectSentinelAsync(RedisCodec<K,V> codec,
                                                                                                      RedisURI redisURI)

Open asynchronously a connection to a Redis Sentinel using the supplied RedisURI and use the supplied codec to encode/decode keys and values. The client RedisURI must contain one or more sentinels.

Type Parameters:

K - Key type

V - Value type

Parameters:

codec - the Redis server to connect to, must not be null

redisURI - the Redis server to connect to, must not be null

Returns:

A new connection

Since:

5.1

setOptions

public void setOptions(ClientOptions clientOptions)

Set the ClientOptions for the client.

Overrides:

setOptions in class AbstractRedisClient

Parameters:

clientOptions - the new client options

Throws:

IllegalArgumentException - if clientOptions is null

newStatefulRedisPubSubConnection

protected <K,V> StatefulRedisPubSubConnectionImpl<K,V> newStatefulRedisPubSubConnection(PubSubEndpoint<K,V> endpoint,
                                                                                                    RedisChannelWriter channelWriter,
                                                                                                    RedisCodec<K,V> codec,
                                                                                                    Duration timeout)

Create a new instance of StatefulRedisPubSubConnectionImpl or a subclass.

Subclasses of RedisClient may override that method.

Type Parameters:

K - Key-Type

V - Value Type

Parameters:

endpoint - the endpoint

channelWriter - the channel writer

codec - codec

timeout - default timeout

Returns:

new instance of StatefulRedisPubSubConnectionImpl

newStatefulRedisSentinelConnection

protected <K,V> StatefulRedisSentinelConnectionImpl<K,V> newStatefulRedisSentinelConnection(RedisChannelWriter channelWriter,
                                                                                                        RedisCodec<K,V> codec,
                                                                                                        Duration timeout)

Create a new instance of StatefulRedisSentinelConnectionImpl or a subclass.

Subclasses of RedisClient may override that method.

Type Parameters:

K - Key-Type

V - Value Type

Parameters:

channelWriter - the channel writer

codec - codec

timeout - default timeout

Returns:

new instance of StatefulRedisSentinelConnectionImpl

newStatefulRedisConnection

protected <K,V> StatefulRedisConnectionImpl<K,V> newStatefulRedisConnection(RedisChannelWriter channelWriter,
                                                                                        PushHandler pushHandler,
                                                                                        RedisCodec<K,V> codec,
                                                                                        Duration timeout)

Create a new instance of StatefulRedisConnectionImpl or a subclass.

Subclasses of RedisClient may override that method.

Type Parameters:

K - Key-Type

V - Value Type

Parameters:

channelWriter - the channel writer

pushHandler - the handler for push notifications

codec - codec

timeout - default timeout

Returns:

new instance of StatefulRedisConnectionImpl

getSocketAddress

protected Mono<SocketAddress> getSocketAddress(RedisURI redisURI)

Get a Mono that resolves RedisURI to a SocketAddress. Resolution is performed either using Redis Sentinel (if the RedisURI is configured with Sentinels) or via DNS resolution.

Subclasses of RedisClient may override that method.

Parameters:

redisURI - must not be null.

Returns:

the resolved SocketAddress.

See Also:

ClientResources.dnsResolver(), RedisURI.getSentinels(), RedisURI.getSentinelMasterId()

newStringStringCodec

protected RedisCodec<String,String> newStringStringCodec()

Returns a String codec.

Returns:

a String codec.

See Also:

StringCodec.UTF8