sirius.db.redis

Class Redis

java.lang.Object

sirius.db.redis.Redis

All Implemented Interfaces:

sirius.kernel.di.std.Priorized, sirius.kernel.Startable, sirius.kernel.Stoppable

public class Redis
extends Object
implements sirius.kernel.Startable, sirius.kernel.Stoppable

Provides a thin layer to access Redis.

The connection parameters are setup using the system configuration. Most probably a value for redis.host is all that is required. Another good practice is to use redis.db=1 for developement system so that they can run in parallel with a test system (which uses the default database 0 - unless configured otherwise).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Redis.LockInfo Data object for storing information of a redis lock

Field Summary

Fields

Modifier and Type	Field and Description
protected sirius.kernel.health.Average	callDuration
static String	INFO_USED_MEMORY Contains the entry name of the info section under which redis reports the amount of consumed ram
protected redis.clients.jedis.JedisPool	jedis
static sirius.kernel.health.Log	LOG
protected sirius.kernel.health.Average	messageDuration
protected redis.clients.jedis.JedisSentinelPool	sentinelPool

Fields inherited from interface sirius.kernel.di.std.Priorized

DEFAULT_PRIORITY

Constructor Summary

Constructors

Constructor and Description
Redis()

Method Summary

Modifier and Type	Method and Description
protected Optional<Redis.LockInfo>	computeLockInfo(redis.clients.jedis.Jedis redis, String key)
void	exec(Supplier<String> description, Consumer<redis.clients.jedis.Jedis> task) Executes one or more Redis commands without any return value.
Map<String,String>	getInfo() Returns a map of monitoring info about the redis server.
List<Redis.LockInfo>	getLockList() Returns a list of all currently held locks.
int	getPriority()
protected void	handlePubSubMessage(String channel, String message, Subscriber subscriber)
boolean	isConfigured() Determines if access to Redis is configured.
boolean	isLocked(String lock) Determines if the given lock is currently locked by this or another node.
String	pollQueue(String queue) Polls an element off a queue in Redis.
void	publish(String topic, String message) Broadcasts a message to a pub-sub topic in redis.
void	pushToQueue(String queue, String data) Pushes a piece of data to a queue in Redis.
<T> T	query(Supplier<String> description, Function<redis.clients.jedis.Jedis,T> task) Executes one or more Redis commands and returns a value of the given type.
void	started()
void	stopped()
boolean	tryLock(String lock, Duration acquireTimeout, Duration lockTimeout) Tries to acquire the given lock in the given timeslot.
void	tryLocked(String lock, Duration acquireTimeout, Duration lockTimeout, Runnable lockedTask) Boilerplate method to perform the given task while holding the given lock.
void	unlock(String lock) Releases the lock.
void	unlock(String lock, boolean force) Releases the given lock.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

public static final sirius.kernel.health.Log LOG

callDuration

protected sirius.kernel.health.Average callDuration

messageDuration

protected sirius.kernel.health.Average messageDuration

jedis

protected redis.clients.jedis.JedisPool jedis

sentinelPool

protected redis.clients.jedis.JedisSentinelPool sentinelPool

INFO_USED_MEMORY

public static final String INFO_USED_MEMORY

Contains the entry name of the info section under which redis reports the amount of consumed ram

See Also:

Constant Field Values

Constructor Detail

Redis

public Redis()

Method Detail

handlePubSubMessage

protected void handlePubSubMessage(String channel,
                                   String message,
                                   Subscriber subscriber)

getPriority

public int getPriority()

Specified by:

getPriority in interface sirius.kernel.di.std.Priorized

Specified by:

getPriority in interface sirius.kernel.Startable

Specified by:

getPriority in interface sirius.kernel.Stoppable

started

public void started()

Specified by:

started in interface sirius.kernel.Startable

stopped

public void stopped()

Specified by:

stopped in interface sirius.kernel.Stoppable

isConfigured

public boolean isConfigured()

Determines if access to Redis is configured.

Returns:

true if at least a host is given or at least one sentinel is available, false otherwise

query

public <T> T query(Supplier<String> description,
                   Function<redis.clients.jedis.Jedis,T> task)

Executes one or more Redis commands and returns a value of the given type.

Type Parameters:

T - the generic type of the result

Parameters:

description - a description of the actions performed used for debugging and tracing

task - the actual task to perform using redis

Returns:

a result computed by task

exec

public void exec(Supplier<String> description,
                 Consumer<redis.clients.jedis.Jedis> task)

Executes one or more Redis commands without any return value.

Parameters:

description - a description of the actions performed used for debugging and tracing

task - the actual task to perform using redis

pushToQueue

public void pushToQueue(String queue,
                        String data)

Pushes a piece of data to a queue in Redis.

Parameters:

queue - the name of the queue

data - the data to push

pollQueue

@Nullable
public String pollQueue(String queue)

Polls an element off a queue in Redis.

Parameters:

queue - the name of the queue

Returns:

the next entry in the queue or null if the queue is empty

publish

public void publish(String topic,
                    String message)

Broadcasts a message to a pub-sub topic in redis.

Parameters:

topic - the name of the topic to broadcast to

message - the message to send

getInfo

public Map<String,String> getInfo()

Returns a map of monitoring info about the redis server.

Returns:

a map containing statistical values supplied by the server

getLockList

public List<Redis.LockInfo> getLockList()

Returns a list of all currently held locks.

This is mainly inteded to be used for monitoring and maintenance (e.g. RedisCommand)

Returns:

a list of all currently known locks

computeLockInfo

protected Optional<Redis.LockInfo> computeLockInfo(redis.clients.jedis.Jedis redis,
                                                   String key)

tryLock

public boolean tryLock(@Nonnull
                       String lock,
                       @Nullable
                       Duration acquireTimeout,
                       @Nonnull
                       Duration lockTimeout)

Tries to acquire the given lock in the given timeslot.

The system will try to acquire the given lock. If the lock is currently in use, it will retry in regular intervals until either the lock is acquired or the acquireTimeout is over.

A sane value for the timeout might be in the range of 5-50s, highly depending on the algorithm being protected by the lock. If the value is null, no retries will be performed.

The lockTimeout controls the max. age of the lock. After the given period, the lock will be released, even if unlock wasn't called. This is to prevent a cluster from locking itself out due to a single node crash. However, it is very important to chose a sane value here.

Parameters:

lock - the name of the lock to acquire

acquireTimeout - the max duration during which retires (in 1 second intervals) will be performed

lockTimeout - the max duration for which the lock will be kept before auto-releasing it

Returns:

true if the lock was acquired, false otherwise

tryLocked

public void tryLocked(@Nonnull
                      String lock,
                      @Nullable
                      Duration acquireTimeout,
                      @Nonnull
                      Duration lockTimeout,
                      @Nonnull
                      Runnable lockedTask)

Boilerplate method to perform the given task while holding the given lock.

See tryLock(String, Duration, Duration) for details on acquiring a lock.

If the lock cannot be acquired, nothing will happen (neighter the task will be execute nor an exception will be thrown).

Parameters:

lock - the name of the lock to acquire

acquireTimeout - the max duration during which retires (in 1 second intervals) will be performed

lockTimeout - the max duration for which the lock will be kept before auto-releasing it

lockedTask - the task to execute while holding the given lock. The task will not be executed if the lock cannot be acquired within the given period

isLocked

public boolean isLocked(@Nonnull
                        String lock)

Determines if the given lock is currently locked by this or another node.

Parameters:

lock - the lock to check

Returns:

true if the lock is currently active, false otherwise

unlock

public void unlock(String lock)

Releases the lock.

Parameters:

lock - the lock to release

unlock

public void unlock(String lock,
                   boolean force)

Releases the given lock.

Parameters:

lock - the lock to release

force - if true, the lock will even be released if it is held by another node. This is a very dangerous operation and should only be used by maintenance and management tools like RedisCommand.