Въведение в марулята - клиентът на Java Redis

1. Общ преглед

Тази статия е въведение в салата, клиент на Redis Java.

Redis е хранилище ключ-стойност в паметта, което може да се използва като база данни, кеш или посредник за съобщения. Данните се добавят, заявяват, модифицират и изтриват с команди, които работят с клавиши в структурата на данните в паметта на Redis.

Марулята поддържа както синхронна, така и асинхронна комуникационна употреба на пълния API на Redis, включително нейните структури от данни, pub / sub съобщения и сървърни връзки с висока наличност.

2. Защо маруля?

Покрихме джедаите в една от предишните публикации. Какво прави салатата различна?

Най-съществената разлика е неговата асинхронна поддръжка чрез интерфейса CompletionStage на Java 8 и поддръжка за реактивни потоци. Както ще видим по-долу, Lettuce предлага естествен интерфейс за извършване на асинхронни заявки от сървъра на базата данни Redis и за създаване на потоци.

Той също така използва Netty за комуникация със сървъра. Това прави „по-тежък“ API, но също така го прави по-подходящ за споделяне на връзка с повече от една нишка.

3. Настройка

3.1. Зависимост

Нека започнем с деклариране на единствената зависимост, от която се нуждаем, в pom.xml :

 io.lettuce lettuce-core 5.0.1.RELEASE  

Най-новата версия на библиотеката може да бъде проверена в хранилището на Github или в Maven Central.

3.2. Инсталация на Redis

Ще трябва да инсталираме и стартираме поне един екземпляр на Redis, два, ако искаме да тестваме клъстериране или режим sentinel (въпреки че режимът sentinel изисква три сървъра, за да функционира правилно.) За тази статия използваме 4.0.x - най-новата стабилна версия в този момент.

Повече информация за започване на работа с Redis можете да намерите тук, включително изтегляния за Linux и MacOS.

Redis не поддържа официално Windows, но тук има порт на сървъра. Също така можем да стартираме Redis в Docker, което е по-добра алтернатива за Windows 10 и бърз начин за стартиране и работа.

4. Връзки

4.1. Свързване със сървър

Свързването с Redis се състои от четири стъпки:

  1. Създаване на Redis URI
  2. Използване на URI за свързване с RedisClient
  3. Отваряне на Redis Connection
  4. Генериране на набор от RedisCommands

Нека да видим изпълнението:

RedisClient redisClient = RedisClient .create("redis://[email protected]:6379/"); StatefulRedisConnection connection = redisClient.connect();

А StatefulRedisConnection е как звучи; безопасна за нишки връзка към сървър Redis, която ще поддържа връзката си със сървъра и ще се свърже отново, ако е необходимо. След като имаме връзка, можем да я използваме за изпълнение на команди Redis или синхронно, или асинхронно.

RedisClient използва значителни системни ресурси, тъй като притежава Netty ресурси за комуникация със сървъра Redis. Приложенията, които изискват множество връзки, трябва да използват един RedisClient.

4.2. Redis URI

Създаваме RedisClient чрез предаване на URI на статичния фабричен метод.

Марулята използва персонализиран синтаксис за URI на Redis. Това е схемата:

redis :// [[email protected]] host [: port] [/ database] [? [timeout=timeout[d|h|m|s|ms|us|ns]] [&_database=database_]] 

Има четири схеми на URI:

  • redis - самостоятелен сървър на Redis
  • rediss - самостоятелен сървър на Redis чрез SSL връзка
  • redis-socket - самостоятелен сървър на Redis чрез Unix сокет за домейн
  • redis-sentinel - сървър на Redis Sentinel

Екземплярът на базата данни Redis може да бъде посочен като част от пътя на URL адреса или като допълнителен параметър. Ако са предоставени и двете, параметърът има по-голям приоритет.

В горния пример използваме представяне на String . Салатата също има клас RedisURI за изграждане на връзки. Той предлага модела Builder :

RedisURI.Builder .redis("localhost", 6379).auth("password") .database(1).build(); 

И конструктор:

new RedisURI("localhost", 6379, 60, TimeUnit.SECONDS); 

4.3. Синхронни команди

Подобно на джеди, марулята предлага пълен набор от команди на Redis под формата на методи.

Lettuce обаче изпълнява както синхронни, така и асинхронни версии. Ще разгледаме накратко синхронната версия и след това ще използваме асинхронната реализация за останалата част от урока.

След като създадем връзка, ние я използваме за създаване на набор от команди:

RedisCommands syncCommands = connection.sync(); 

Сега имаме интуитивен интерфейс за комуникация с Redis.

Можем да задаваме и получаваме String стойности:

syncCommands.set("key", "Hello, Redis!"); String value = syncommands.get(“key”); 

Можем да работим с хешове:

syncCommands.hset("recordName", "FirstName", "John"); syncCommands.hset("recordName", "LastName", "Smith"); Map record = syncCommands.hgetall("recordName"); 

Ще разгледаме още Redis по-късно в статията.

Синхронният API на маруля използва асинхронния API. Блокирането се извършва за нас на ниво команда. Това означава, че повече от един клиент може да споделя синхронна връзка.

4.4. Асинхронни команди

Нека да разгледаме асинхронните команди:

RedisAsyncCommands asyncCommands = connection.async(); 

We retrieve a set of RedisAsyncCommands from the connection, similar to how we retrieved the synchronous set. These commands return a RedisFuture (which is a CompletableFuture internally):

RedisFuture result = asyncCommands.get("key"); 

A guide to working with a CompletableFuture can be found here.

4.5. Reactive API

Finally, let’s see how to work with non-blocking reactive API:

RedisStringReactiveCommands reactiveCommands = connection.reactive(); 

These commands return results wrapped in a Mono or a Flux from Project Reactor.

A guide to working with Project Reactor can be found here.

5. Redis Data Structures

We briefly looked at strings and hashes above, let's look at how Lettuce implements the rest of Redis' data structures. As we'd expect, each Redis command has a similarly-named method.

5.1. Lists

Lists are lists of Strings with the order of insertion preserved. Values are inserted or retrieved from either end:

asyncCommands.lpush("tasks", "firstTask"); asyncCommands.lpush("tasks", "secondTask"); RedisFuture redisFuture = asyncCommands.rpop("tasks"); String nextTask = redisFuture.get(); 

In this example, nextTask equals “firstTask“. Lpush pushes values to the head of the list, and then rpop pops values from the end of the list.

We can also pop elements from the other end:

asyncCommands.del("tasks"); asyncCommands.lpush("tasks", "firstTask"); asyncCommands.lpush("tasks", "secondTask"); redisFuture = asyncCommands.lpop("tasks"); String nextTask = redisFuture.get(); 

We start the second example by removing the list with del. Then we insert the same values again, but we use lpop to pop the values from the head of the list, so the nextTask holds “secondTask” text.

5.2. Sets

Redis Sets are unordered collections of Strings similar to Java Sets; there are no duplicate elements:

asyncCommands.sadd("pets", "dog"); asyncCommands.sadd("pets", "cat"); asyncCommands.sadd("pets", "cat"); RedisFuture
    
      pets = asyncCommands.smembers("nicknames"); RedisFuture exists = asyncCommands.sismember("pets", "dog"); 
    

When we retrieve the Redis set as a Set, the size is two, since the duplicate “cat” was ignored. When we query Redis for the existence of “dog” with sismember, the response is true.

5.3. Hashes

We briefly looked at an example of hashes earlier. They are worth a quick explanation.

Redis Hashes are records with String fields and values. Each record also has a key in the primary index:

asyncCommands.hset("recordName", "FirstName", "John"); asyncCommands.hset("recordName", "LastName", "Smith"); RedisFuture lastName = syncCommands.hget("recordName", "LastName"); RedisFuture record = syncCommands.hgetall("recordName"); 

We use hset to add fields to the hash, passing in the name of the hash, the name of the field, and a value.

Then, we retrieve an individual value with hget, the name of the record and the field. Finally, we fetch the entire record as a hash with hgetall.

5.4. Sorted Sets

Sorted Sets contains values and a rank, by which they are sorted. The rank is 64-bit floating point value.

Items are added with a rank, and retrieved in a range:

asyncCommands.zadd("sortedset", 1, "one"); asyncCommands.zadd("sortedset", 4, "zero"); asyncCommands.zadd("sortedset", 2, "two"); RedisFuture
    
      valuesForward = asyncCommands.zrange(key, 0, 3); RedisFuture
     
       valuesReverse = asyncCommands.zrevrange(key, 0, 3); 
     
    

The second argument to zadd is a rank. We retrieve a range by rank with zrange for ascending order and zrevrange for descending.

We added “zero” with a rank of 4, so it will appear at the end of valuesForward and at the beginning of valuesReverse.

6. Transactions

Transactions allow the execution of a set of commands in a single atomic step. These commands are guaranteed to be executed in order and exclusively. Commands from another user won't be executed until the transaction finishes.

Either all commands are executed, or none of them are. Redis will not perform a rollback if one of them fails. Once exec() is called, all commands are executed in the order specified.

Let's look at an example:

asyncCommands.multi(); RedisFuture result1 = asyncCommands.set("key1", "value1"); RedisFuture result2 = asyncCommands.set("key2", "value2"); RedisFuture result3 = asyncCommands.set("key3", "value3"); RedisFuture execResult = asyncCommands.exec(); TransactionResult transactionResult = execResult.get(); String firstResult = transactionResult.get(0); String secondResult = transactionResult.get(0); String thirdResult = transactionResult.get(0); 

The call to multi starts the transaction. When a transaction is started, the subsequent commands are not executed until exec() is called.

In synchronous mode, the commands return null. In asynchronous mode, the commands return RedisFuture . Exec returns a TransactionResult which contains a list of responses.

Since the RedisFutures also receive their results, asynchronous API clients receive the transaction result in two places.

7. Batching

Under normal conditions, Lettuce executes commands as soon as they are called by an API client.

This is what most normal applications want, especially if they rely on receiving command results serially.

However, this behavior isn't efficient if applications don't need results immediately or if large amounts of data are being uploaded in bulk.

Asynchronous applications can override this behavior:

commands.setAutoFlushCommands(false); List
    
      futures = new ArrayList(); for (int i = 0; i < iterations; i++) { futures.add(commands.set("key-" + i, "value-" + i); } commands.flushCommands(); boolean result = LettuceFutures.awaitAll(5, TimeUnit.SECONDS, futures.toArray(new RedisFuture[0])); 
    

With setAutoFlushCommands set to false, the application must call flushCommands manually. In this example, we queued multiple set command and then flushed the channel. AwaitAll waits for all of the RedisFutures to complete.

This state is set on a per connection basis and effects all threads that use the connection. This feature isn't applicable to synchronous commands.

8. Publish/Subscribe

Redis offers a simple publish/subscribe messaging system. Subscribers consume messages from channels with the subscribe command. Messages aren't persisted; they are only delivered to users when they are subscribed to a channel.

Redis uses the pub/sub system for notifications about the Redis dataset, giving clients the ability to receive events about keys being set, deleted, expired, etc.

See the documentation here for more details.

8.1. Subscriber

A RedisPubSubListener receives pub/sub messages. This interface defines several methods, but we'll just show the method for receiving messages here:

public class Listener implements RedisPubSubListener { @Override public void message(String channel, String message) { log.debug("Got {} on channel {}", message, channel); message = new String(s2); } } 

We use the RedisClient to connect a pub/sub channel and install the listener:

StatefulRedisPubSubConnection connection = client.connectPubSub(); connection.addListener(new Listener()) RedisPubSubAsyncCommands async = connection.async(); async.subscribe("channel"); 

With a listener installed, we retrieve a set of RedisPubSubAsyncCommands and subscribe to a channel.

8.2. Publisher

Publishing is just a matter of connecting a Pub/Sub channel and retrieving the commands:

StatefulRedisPubSubConnection connection = client.connectPubSub(); RedisPubSubAsyncCommands async = connection.async(); async.publish("channel", "Hello, Redis!"); 

Publishing requires a channel and a message.

8.3. Reactive Subscriptions

Lettuce also offers a reactive interface for subscribing to pub/sub messages:

StatefulRedisPubSubConnection connection = client .connectPubSub(); RedisPubSubAsyncCommands reactive = connection .reactive(); reactive.observeChannels().subscribe(message -> { log.debug("Got {} on channel {}", message, channel); message = new String(s2); }); reactive.subscribe("channel").subscribe(); 

The Flux returned by observeChannels receives messages for all channels, but since this is a stream, filtering is easy to do.

9. High Availability

Redis offers several options for high availability and scalability. Complete understanding requires knowledge of Redis server configurations, but we'll go over a brief overview of how Lettuce supports them.

9.1. Master/Slave

Redis servers replicate themselves in a master/slave configuration. The master server sends the slave a stream of commands that replicate the master cache to the slave. Redis doesn't support bi-directional replication, so slaves are read-only.

Lettuce can connect to Master/Slave systems, query them for the topology, and then select slaves for reading operations, which can improve throughput:

RedisClient redisClient = RedisClient.create(); StatefulRedisMasterSlaveConnection connection = MasterSlave.connect(redisClient, new Utf8StringCodec(), RedisURI.create("redis://localhost")); connection.setReadFrom(ReadFrom.SLAVE); 

9.2. Sentinel

Redis Sentinel monitors master and slave instances and orchestrates failovers to slaves in the event of a master failover.

Lettuce can connect to the Sentinel, use it to discover the address of the current master, and then return a connection to it.

To do this, we build a different RedisURI and connect our RedisClient with it:

RedisURI redisUri = RedisURI.Builder .sentinel("sentinelhost1", "clustername") .withSentinel("sentinelhost2").build(); RedisClient client = new RedisClient(redisUri); RedisConnection connection = client.connect(); 

We built the URI with the hostname (or address) of the first Sentinel and a cluster name, followed by a second sentinel address. When we connect to the Sentinel, Lettuce queries it about the topology and returns a connection to the current master server for us.

The complete documentation is available here.

9.3. Clusters

Redis Cluster uses a distributed configuration to provide high-availability and high-throughput.

Clusters shard keys across up to 1000 nodes, therefore transactions are not available in a cluster:

RedisURI redisUri = RedisURI.Builder.redis("localhost") .withPassword("authentication").build(); RedisClusterClient clusterClient = RedisClusterClient .create(rediUri); StatefulRedisClusterConnection connection = clusterClient.connect(); RedisAdvancedClusterCommands syncCommands = connection .sync(); 

RedisAdvancedClusterCommands holds the set of Redis commands supported by the cluster, routing them to the instance that holds the key.

A complete specification is available here.

10. Conclusion

In this tutorial, we looked at how to use Lettuce to connect and query a Redis server from within our application.

Lettuce supports the complete set of Redis features, with the bonus of a completely thread-safe asynchronous interface. It also makes extensive use of Java 8's CompletionStage interface to give applications fine-grained control over how they receive data.

Примери за кодове, както винаги, можете да намерите в GitHub.