com.lordofthejars.nosqlunit.redis.embedded
Class ListDatatypeOperations

java.lang.Object
  com.lordofthejars.nosqlunit.redis.embedded.ExpirationDatatypeOperations
      com.lordofthejars.nosqlunit.redis.embedded.ListDatatypeOperations

All Implemented Interfaces:

RedisDatatypeOperations

public class ListDatatypeOperations
extends ExpirationDatatypeOperations
implements RedisDatatypeOperations

Nested Class Summary

static class

ListDatatypeOperations.ListPositionEnum

Nested classes/interfaces inherited from class com.lordofthejars.nosqlunit.redis.embedded.ExpirationDatatypeOperations

ExpirationDatatypeOperations.TtlState

Field Summary

protected BlockingMap<ByteBuffer,ByteBuffer>	blockingMultimap
protected static String	LIST

Fields inherited from class com.lordofthejars.nosqlunit.redis.embedded.ExpirationDatatypeOperations

expirationsInMillis, NO_EXPIRATION

Constructor Summary

ListDatatypeOperations()

Method Summary

List<byte[]>	blpop(int timeout, byte[]... keys) BLPOP (and BRPOP) is a blocking list pop primitive.
List<byte[]>	brpop(int timeout, byte[]... keys) BLPOP (and BRPOP) is a blocking list pop primitive.
byte[]	brpoplpush(byte[] source, byte[] destination, int timeout) Pop a value from a list, push it to another list and return it; or block until one is available
Long	del(byte[]... keys)
boolean	exists(byte[] key)
void	flushAllKeys()
long	getNumberOfKeys()
List<byte[]>	keys()
byte[]	lindex(byte[] key, int index) Return the specified element of the list stored at the specified key.
Long	linsert(byte[] key, ListDatatypeOperations.ListPositionEnum where, byte[] pivot, byte[] value)
Long	llen(byte[] key) Return the length of the list stored at the specified key.
byte[]	lpop(byte[] key) Atomically return and remove the first (LPOP) or last (RPOP) element of the list.
Long	lpush(byte[] key, byte[]... values) Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key.
Long	lpushx(byte[] key, byte[] value)
List<byte[]>	lrange(byte[] key, int start, int end) Return the specified elements of the list stored at the specified key.
Long	lrem(byte[] key, int count, byte[] value) Remove the first count occurrences of the value element from the list.
String	lset(byte[] key, int index, byte[] value) Set a new value as the element at index position of the List at key.
String	ltrim(byte[] key, int start, int end) Trim an existing list so that it will contain only the specified range of elements specified.
boolean	renameKey(byte[] key, byte[] newKey)
byte[]	rpop(byte[] key) Atomically return and remove the first (LPOP) or last (RPOP) element of the list.
Long	rpush(byte[] key, byte[]... values) Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key.
Long	rpushx(byte[] key, byte[] value)
List<byte[]>	sort(byte[] key)
String	type()

Methods inherited from class com.lordofthejars.nosqlunit.redis.embedded.ExpirationDatatypeOperations

addExpirationAt, addExpirationTime, remainingTime, removeExpiration, renameTtlKey, timedoutState

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.lordofthejars.nosqlunit.redis.embedded.RedisDatatypeOperations

addExpirationAt, addExpirationTime, remainingTime, removeExpiration, timedoutState

Field Detail

LIST

protected static final String LIST

See Also:

Constant Field Values

blockingMultimap

protected BlockingMap<ByteBuffer,ByteBuffer> blockingMultimap

Constructor Detail

ListDatatypeOperations

public ListDatatypeOperations()

Method Detail

blpop

public List<byte[]> blpop(int timeout,
                          byte[]... keys)

BLPOP (and BRPOP) is a blocking list pop primitive. You can see this commands as blocking versions of LPOP and RPOP able to block if the specified keys don't exist or contain empty lists.

The following is a description of the exact semantic. We describe BLPOP but the two commands are identical, the only difference is that BLPOP pops the element from the left (head) of the list, and BRPOP pops from the right (tail).

Non blocking behavior

When BLPOP is called, if at least one of the specified keys contain a non empty list, an element is popped from the head of the list and returned to the caller together with the name of the key (BLPOP returns a two elements array, the first element is the key, the second the popped value).

Keys are scanned from left to right, so for instance if you issue BLPOP list1 list2 list3 0 against a dataset where list1 does not exist but list2 and list3 contain non empty lists, BLPOP guarantees to return an element from the list stored at list2 (since it is the first non empty list starting from the left).

Blocking behavior

If none of the specified keys exist or contain non empty lists, BLPOP blocks until some other client performs a LPUSH or an RPUSH operation against one of the lists.

Once new data is present on one of the lists, the client finally returns with the name of the key unblocking it and the popped value.

When blocking, if a non-zero timeout is specified, the client will unblock returning a nil special value if the specified amount of seconds passed without a push operation against at least one of the specified keys.

The timeout argument is interpreted as an integer value. A timeout of zero means instead to block forever.

Multiple clients blocking for the same keys

Multiple clients can block for the same key. They are put into a queue, so the first to be served will be the one that started to wait earlier, in a first-blpopping first-served fashion.

blocking POP inside a MULTI/EXEC transaction

BLPOP and BRPOP can be used with pipelining (sending multiple commands and reading the replies in batch), but it does not make sense to use BLPOP or BRPOP inside a MULTI/EXEC block (a Redis transaction).

The behavior of BLPOP inside MULTI/EXEC when the list is empty is to return a multi-bulk nil reply, exactly what happens when the timeout is reached. If you like science fiction, think at it like if inside MULTI/EXEC the time will flow at infinite speed :)

Parameters:

timeout -

keys -

Returns:

BLPOP returns a two-elements array via a multi bulk reply in order to return both the unblocking key and the popped value.

When a non-zero timeout is specified, and the BLPOP operation timed out, the return value is a nil multi bulk reply. Most client values will return false or nil accordingly to the programming language used.

See Also:

#brpop(int, String...)

brpoplpush

public byte[] brpoplpush(byte[] source,
                         byte[] destination,
                         int timeout)

Pop a value from a list, push it to another list and return it; or block until one is available

Parameters:

source -

destination -

timeout -

Returns:

the element

linsert

public Long linsert(byte[] key,
                    ListDatatypeOperations.ListPositionEnum where,
                    byte[] pivot,
                    byte[] value)

lpop

public byte[] lpop(byte[] key)

Atomically return and remove the first (LPOP) or last (RPOP) element of the list. For example if the list contains the elements "a","b","c" LPOP will return "a" and the list will become "b","c".

If the key does not exist or the list is already empty the special value 'nil' is returned.

Parameters:

key -

Returns:

Bulk reply

See Also:

rpop(byte[])

rpop

public byte[] rpop(byte[] key)

Atomically return and remove the first (LPOP) or last (RPOP) element of the list. For example if the list contains the elements "a","b","c" LPOP will return "a" and the list will become "b","c".

If the key does not exist or the list is already empty the special value 'nil' is returned.

Parameters:

key -

Returns:

Bulk reply

See Also:

lpop(byte[])

llen

public Long llen(byte[] key)

Return the length of the list stored at the specified key. If the key does not exist zero is returned (the same behaviour as for empty lists). If the value stored at key is not a list an error is returned.

Parameters:

key -

Returns:

The length of the list.

lset

public String lset(byte[] key,
                   int index,
                   byte[] value)

Set a new value as the element at index position of the List at key.

Out of range indexes will generate an error.

Similarly to other list commands accepting indexes, the index can be negative to access elements starting from the end of the list. So -1 is the last element, -2 is the penultimate, and so forth.

Time complexity:

Parameters:

key -

index -

value -

Returns:

Status code reply

See Also:

lindex(byte[], int)

lindex

public byte[] lindex(byte[] key,
                     int index)

Return the specified element of the list stored at the specified key. 0 is the first element, 1 the second and so on. Negative indexes are supported, for example -1 is the last element, -2 the penultimate and so on.

If the value stored at key is not of list type an error is returned. If the index is out of range a 'nil' reply is returned.

Note that even if the average time complexity is O(n) asking for the first or the last element of the list is O(1).

Parameters:

key -

index -

Returns:

Bulk reply, specifically the requested element

brpop

public List<byte[]> brpop(int timeout,
                          byte[]... keys)

BLPOP (and BRPOP) is a blocking list pop primitive. You can see this commands as blocking versions of LPOP and RPOP able to block if the specified keys don't exist or contain empty lists.

The following is a description of the exact semantic. We describe BLPOP but the two commands are identical, the only difference is that BLPOP pops the element from the left (head) of the list, and BRPOP pops from the right (tail).

Non blocking behavior

When BLPOP is called, if at least one of the specified keys contain a non empty list, an element is popped from the head of the list and returned to the caller together with the name of the key (BLPOP returns a two elements array, the first element is the key, the second the popped value).

Keys are scanned from left to right, so for instance if you issue BLPOP list1 list2 list3 0 against a dataset where list1 does not exist but list2 and list3 contain non empty lists, BLPOP guarantees to return an element from the list stored at list2 (since it is the first non empty list starting from the left).

Blocking behavior

If none of the specified keys exist or contain non empty lists, BLPOP blocks until some other client performs a LPUSH or an RPUSH operation against one of the lists.

Once new data is present on one of the lists, the client finally returns with the name of the key unblocking it and the popped value.

When blocking, if a non-zero timeout is specified, the client will unblock returning a nil special value if the specified amount of seconds passed without a push operation against at least one of the specified keys.

The timeout argument is interpreted as an integer value. A timeout of zero means instead to block forever.

Multiple clients blocking for the same keys

Multiple clients can block for the same key. They are put into a queue, so the first to be served will be the one that started to wait earlier, in a first-blpopping first-served fashion.

blocking POP inside a MULTI/EXEC transaction

BLPOP and BRPOP can be used with pipelining (sending multiple commands and reading the replies in batch), but it does not make sense to use BLPOP or BRPOP inside a MULTI/EXEC block (a Redis transaction).

The behavior of BLPOP inside MULTI/EXEC when the list is empty is to return a multi-bulk nil reply, exactly what happens when the timeout is reached. If you like science fiction, think at it like if inside MULTI/EXEC the time will flow at infinite speed :)

Parameters:

timeout -

keys -

Returns:

BLPOP returns a two-elements array via a multi bulk reply in order to return both the unblocking key and the popped value.

When a non-zero timeout is specified, and the BLPOP operation timed out, the return value is a nil multi bulk reply. Most client values will return false or nil accordingly to the programming language used.

See Also:

#blpop(int, String...)

lpush

public Long lpush(byte[] key,
                  byte[]... values)

Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key. If the key does not exist an empty list is created just before the append operation. If the key exists but is not a List an error is returned.

Parameters:

key -

elements -

Returns:

Integer reply, specifically, the number of elements inside the list after the push operation.

See Also:

BinaryJedis#rpush(byte[], byte[]...)

lpushx

public Long lpushx(byte[] key,
                   byte[] value)

rpushx

public Long rpushx(byte[] key,
                   byte[] value)

lrange

public List<byte[]> lrange(byte[] key,
                           int start,
                           int end)

Return the specified elements of the list stored at the specified key. Start and end are zero-based indexes. 0 is the first element of the list (the list head), 1 the next element and so on.

For example LRANGE foobar 0 2 will return the first three elements of the list.

start and end can also be negative numbers indicating offsets from the end of the list. For example -1 is the last element of the list, -2 the penultimate element and so on.

Consistency with range functions in various programming languages

Note that if you have a list of numbers from 0 to 100, LRANGE 0 10 will return 11 elements, that is, rightmost item is included. This may or may not be consistent with behavior of range-related functions in your programming language of choice (think Ruby's Range.new, Array#slice or Python's range() function).

LRANGE behavior is consistent with one of Tcl.

Out-of-range indexes

Indexes out of range will not produce an error: if start is over the end of the list, or start > end, an empty list is returned. If end is over the end of the list Redis will threat it just like the last element of the list.

Parameters:

key -

start -

end -

Returns:

Multi bulk reply, specifically a list of elements in the specified range.

rpush

public Long rpush(byte[] key,
                  byte[]... values)

Add the string value to the head (LPUSH) or tail (RPUSH) of the list stored at key. If the key does not exist an empty list is created just before the append operation. If the key exists but is not a List an error is returned.

Time complexity: O(1)

Parameters:

key -

elements -

Returns:

Integer reply, specifically, the number of elements inside the list after the push operation.

See Also:

BinaryJedis#rpush(byte[], byte[]...)

lrem

public Long lrem(byte[] key,
                 int count,
                 byte[] value)

Remove the first count occurrences of the value element from the list. If count is zero all the elements are removed. If count is negative elements are removed from tail to head, instead to go from head to tail that is the normal behaviour. So for example LREM with count -2 and hello as value to remove against the list (a,b,c,hello,x,hello,hello) will have the list (a,b,c,hello,x). The number of removed elements is returned as an integer, see below for more information about the returned value. Note that non existing keys are considered like empty lists by LREM, so LREM against non existing keys will always return 0.

Time complexity: O(N) (with N being the length of the list)

Parameters:

key -

count -

value -

Returns:

Integer Reply, specifically: The number of removed elements if the operation succeeded

ltrim

public String ltrim(byte[] key,
                    int start,
                    int end)

Trim an existing list so that it will contain only the specified range of elements specified. Start and end are zero-based indexes. 0 is the first element of the list (the list head), 1 the next element and so on.

For example LTRIM foobar 0 2 will modify the list stored at foobar key so that only the first three elements of the list will remain.

start and end can also be negative numbers indicating offsets from the end of the list. For example -1 is the last element of the list, -2 the penultimate element and so on.

Indexes out of range will not produce an error: if start is over the end of the list, or start > end, an empty list is left as value. If end over the end of the list Redis will threat it just like the last element of the list.

Hint: the obvious use of LTRIM is together with LPUSH/RPUSH. For example:

lpush("mylist", "someelement"); ltrim("mylist", 0, 99); *

The above two commands will push elements in the list taking care that the list will not grow without limits. This is very useful when using Redis to store logs for example. It is important to note that when used in this way LTRIM is an O(1) operation because in the average case just one element is removed from the tail of the list.

Parameters:

key -

start -

end -

Returns:

Status code reply

getNumberOfKeys

public long getNumberOfKeys()

Specified by:

getNumberOfKeys in interface RedisDatatypeOperations

flushAllKeys

public void flushAllKeys()

Specified by:

flushAllKeys in interface RedisDatatypeOperations

del

public Long del(byte[]... keys)

Specified by:

del in interface RedisDatatypeOperations

exists

public boolean exists(byte[] key)

Specified by:

exists in interface RedisDatatypeOperations

renameKey

public boolean renameKey(byte[] key,
                         byte[] newKey)

Specified by:

renameKey in interface RedisDatatypeOperations

keys

public List<byte[]> keys()

Specified by:

keys in interface RedisDatatypeOperations

type

public String type()

Specified by:

type in interface RedisDatatypeOperations

sort

public List<byte[]> sort(byte[] key)

Specified by:

sort in interface RedisDatatypeOperations