org.springframework.data.redis.support.collections.RedisZSet Maven / Gradle / Ivy
/*
* Copyright 2011-2022 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.data.redis.support.collections;
import java.util.Collection;
import java.util.Comparator;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.SortedSet;
import java.util.concurrent.TimeUnit;
import org.springframework.data.redis.connection.RedisZSetCommands;
import org.springframework.data.redis.connection.RedisZSetCommands.Limit;
import org.springframework.data.redis.connection.RedisZSetCommands.Range;
import org.springframework.data.redis.core.BoundZSetOperations;
import org.springframework.data.redis.core.RedisOperations;
import org.springframework.data.redis.core.ZSetOperations.TypedTuple;
/**
* Redis ZSet (or sorted set (by weight)). Acts as a {@link SortedSet} based on the given priorities or weights
* associated with each item.
*
* Since using a {@link Comparator} does not apply, a ZSet implements the {@link SortedSet} methods where applicable.
*
* @author Costin Leau
* @author Mark Paluch
* @author Christoph Strobl
* @author Andrey Shlykov
*/
public interface RedisZSet extends RedisCollection, Set {
/**
* Constructs a new {@link RedisZSet} instance with a default score of {@literal 1}.
*
* @param key Redis key of this set.
* @param operations {@link RedisOperations} for the value type of this set.
* @since 2.6
*/
static RedisZSet create(String key, RedisOperations operations) {
return new DefaultRedisZSet<>(key, operations, 1);
}
/**
* Constructs a new {@link RedisZSet} instance.
*
* @param key Redis key of this set.
* @param operations {@link RedisOperations} for the value type of this set.
* @param defaultScore
* @since 2.6
*/
static RedisZSet create(String key, RedisOperations operations, double defaultScore) {
return new DefaultRedisZSet<>(key, operations, defaultScore);
}
/**
* Diff this set and another {@link RedisZSet}.
*
* @param set must not be {@literal null}.
* @return a {@link Set} containing the values that differ.
* @since 2.6
*/
Set diff(RedisZSet set);
/**
* Diff this set and other {@link RedisZSet}s.
*
* @param sets must not be {@literal null}.
* @return a {@link Set} containing the values that differ.
* @since 2.6
*/
Set diff(Collection> sets);
/**
* Diff this set and another {@link RedisZSet}.
*
* @param set must not be {@literal null}.
* @return a {@link Set} containing the values that differ with their scores.
* @since 2.6
*/
Set> diffWithScores(RedisZSet set);
/**
* Diff this set and other {@link RedisZSet}s.
*
* @param sets must not be {@literal null}.
* @return a {@link Set} containing the values that differ with their scores.
* @since 2.6
*/
Set> diffWithScores(Collection> sets);
/**
* Create a new {@link RedisZSet} by diffing this sorted set and {@link RedisZSet} and store result in destination
* {@code destKey}.
*
* @param set must not be {@literal null}.
* @param destKey must not be {@literal null}.
* @return a new {@link RedisZSet} pointing at {@code destKey}.
* @since 2.6
*/
RedisZSet diffAndStore(RedisZSet set, String destKey);
/**
* Create a new {@link RedisZSet} by diffing this sorted set and the collection {@link RedisZSet} and store result in
* destination {@code destKey}.
*
* @param sets must not be {@literal null}.
* @param destKey must not be {@literal null}.
* @return a new {@link RedisZSet} pointing at {@code destKey}.
* @since 2.6
*/
RedisZSet diffAndStore(Collection> sets, String destKey);
/**
* Intersect this set and another {@link RedisZSet}.
*
* @param set must not be {@literal null}.
* @return a {@link Set} containing the intersecting values.
* @since 2.6
*/
Set intersect(RedisZSet set);
/**
* Intersect this set and other {@link RedisZSet}s.
*
* @param sets must not be {@literal null}.
* @return a {@link Set} containing the intersecting values.
* @since 2.6
*/
Set intersect(Collection> sets);
/**
* Intersect this set and another {@link RedisZSet}.
*
* @param set must not be {@literal null}.
* @return a {@link Set} containing the intersecting values with their scores.
* @since 2.6
*/
Set> intersectWithScores(RedisZSet set);
/**
* Intersect this set and other {@link RedisZSet}s.
*
* @param sets must not be {@literal null}.
* @return a {@link Set} containing the intersecting values with their scores.
* @since 2.6
*/
Set> intersectWithScores(Collection> sets);
/**
* Create a new {@link RedisZSet} by intersecting this sorted set and {@link RedisZSet} and store result in
* destination {@code destKey}.
*
* @param set must not be {@literal null}.
* @param destKey must not be {@literal null}.
* @return a new {@link RedisZSet} pointing at {@code destKey}
*/
RedisZSet intersectAndStore(RedisZSet set, String destKey);
/**
* Create a new {@link RedisZSet} by intersecting this sorted set and the collection {@link RedisZSet} and store
* result in destination {@code destKey}.
*
* @param sets must not be {@literal null}.
* @param destKey must not be {@literal null}.
* @return a new {@link RedisZSet} pointing at {@code destKey}
*/
RedisZSet intersectAndStore(Collection> sets, String destKey);
/**
* Union this set and another {@link RedisZSet}.
*
* @param set must not be {@literal null}.
* @return a {@link Set} containing the combined values.
* @since 2.6
*/
Set union(RedisZSet set);
/**
* Union this set and other {@link RedisZSet}s.
*
* @param sets must not be {@literal null}.
* @return a {@link Set} containing the combined values.
* @since 2.6
*/
Set union(Collection> sets);
/**
* Union this set and another {@link RedisZSet}.
*
* @param set must not be {@literal null}.
* @return a {@link Set} containing the combined values with their scores.
* @since 2.6
*/
Set> unionWithScores(RedisZSet set);
/**
* Union this set and other {@link RedisZSet}s.
*
* @param sets must not be {@literal null}.
* @return a {@link Set} containing the combined values with their scores.
* @since 2.6
*/
Set> unionWithScores(Collection> sets);
/**
* Create a new {@link RedisZSet} by union this sorted set and {@link RedisZSet} and store result in destination
* {@code destKey}.
*
* @param set must not be {@literal null}.
* @param destKey must not be {@literal null}.
* @return a new {@link RedisZSet} pointing at {@code destKey}
*/
RedisZSet unionAndStore(RedisZSet set, String destKey);
/**
* Create a new {@link RedisZSet} by union this sorted set and the collection {@link RedisZSet} and store result in
* destination {@code destKey}.
*
* @param sets must not be {@literal null}.
* @param destKey must not be {@literal null}.
* @return a new {@link RedisZSet} pointing at {@code destKey}
*/
RedisZSet unionAndStore(Collection> sets, String destKey);
/**
* Get random element from the set.
*
* @return
* @since 2.6
*/
E randomValue();
/**
* Get elements between {@code start} and {@code end} from sorted set.
*
* @param start
* @param end
* @return
*/
Set range(long start, long end);
/**
* Get elements in range from {@code start} to {@code end} from sorted set ordered from high to low.
*
* @param start
* @param end
* @return
*/
Set reverseRange(long start, long end);
/**
* Get all elements with lexicographical ordering with a value between {@link Range#getMin()} and
* {@link Range#getMax()}.
*
* @param range must not be {@literal null}.
* @return
* @see BoundZSetOperations#rangeByLex(Range)
* @since 1.7
*/
default Set rangeByLex(Range range) {
return rangeByLex(range, Limit.unlimited());
}
/**
* Get all elements {@literal n} elements, where {@literal n = } {@link Limit#getCount()}, starting at
* {@link Limit#getOffset()} with lexicographical ordering having a value between {@link Range#getMin()} and
* {@link Range#getMax()}.
*
* @param range must not be {@literal null}.
* @param limit can be {@literal null}.
* @return
* @since 1.7
* @see BoundZSetOperations#rangeByLex(Range, Limit)
*/
Set rangeByLex(Range range, Limit limit);
/**
* Get all elements with reverse lexicographical ordering with a value between {@link Range#getMin()} and
* {@link Range#getMax()}.
*
* @param range must not be {@literal null}.
* @return
* @since 2.4
* @see BoundZSetOperations#reverseRangeByLex(Range)
*/
default Set reverseRangeByLex(Range range) {
return reverseRangeByLex(range, Limit.unlimited());
}
/**
* Get all elements {@literal n} elements, where {@literal n = } {@link Limit#getCount()}, starting at
* {@link Limit#getOffset()} with reverse lexicographical ordering having a value between {@link Range#getMin()} and
* {@link Range#getMax()}.
*
* @param range must not be {@literal null}.
* @param limit can be {@literal null}.
* @return
* @since 2.4
* @see BoundZSetOperations#reverseRangeByLex(Range, Limit)
*/
Set reverseRangeByLex(Range range, Limit limit);
/**
* Get elements where score is between {@code min} and {@code max} from sorted set.
*
* @param min
* @param max
* @return
*/
Set rangeByScore(double min, double max);
/**
* Get elements where score is between {@code min} and {@code max} from sorted set ordered from high to low.
*
* @param min
* @param max
* @return
*/
Set reverseRangeByScore(double min, double max);
/**
* Get set of {@link RedisZSetCommands.Tuple}s between {@code start} and {@code end} from sorted set.
*
* @param start
* @param end
* @return
*/
Set> rangeWithScores(long start, long end);
/**
* Get set of {@link RedisZSetCommands.Tuple}s in range from {@code start} to {@code end} from sorted set ordered from
* high to low.
*
* @param start
* @param end
* @return
*/
Set> reverseRangeWithScores(long start, long end);
/**
* Get set of {@link RedisZSetCommands.Tuple}s where score is between {@code min} and {@code max} from sorted set.
*
* @param min
* @param max
* @return
*/
Set> rangeByScoreWithScores(double min, double max);
/**
* Get set of {@link RedisZSetCommands.Tuple}s where score is between {@code min} and {@code max} from sorted set
* ordered from high to low.
*
* @param min
* @param max
* @return
*/
Set> reverseRangeByScoreWithScores(double min, double max);
/**
* Remove elements in range between {@code start} and {@code end} from sorted set.
*
* @param start
* @param end
* @return {@code this} set.
*/
RedisZSet remove(long start, long end);
/**
* Remove all elements in range.
*
* @param range must not be {@literal null}.
* @return {@code this} set.
* @since 2.5
*/
// TODO: Switch to RedisZSet
Set removeByLex(Range range);
/**
* Remove elements with scores between {@code min} and {@code max} from sorted set with the bound key.
*
* @param min
* @param max
* @return {@code this} set.
*/
RedisZSet removeByScore(double min, double max);
/**
* Adds an element to the set with the given score, or updates the score if the element exists.
*
* @param e element to add
* @param score element score
* @return true if a new element was added, false otherwise (only the score has been updated)
*/
boolean add(E e, double score);
/**
* Adds an element to the set with a default score. Equivalent to {@code add(e, getDefaultScore())}. The score value
* is implementation specific. {@inheritDoc}
*/
boolean add(E e);
/**
* Adds an element to the set using the {@link #getDefaultScore() default score} if the element does not already exists.
*
* @param e element to add
* @return true if a new element was added, false otherwise (only the score has been updated)
* @since 2.5
*/
default boolean addIfAbsent(E e) {
return addIfAbsent(e, getDefaultScore());
}
/**
* Adds an element to the set with the given score if the element does not already exists.
*
* @param e element to add
* @param score element score
* @return true if a new element was added, false otherwise (only the score has been updated)
* @since 2.5
*/
boolean addIfAbsent(E e, double score);
/**
* Count number of elements within sorted set with value between {@code Range#min} and {@code Range#max} applying
* lexicographical ordering.
*
* @param range must not be {@literal null}.
* @return
* @since 2.4
* @see Redis Documentation: ZLEXCOUNT
*/
Long lexCount(Range range);
/**
* Returns the score of the given element. Returns null if the element is not contained by the set.
*
* @param o object
* @return the score associated with the given object
*/
Double score(Object o);
/**
* Returns the rank (position) of the given element in the set, in ascending order. Returns null if the element is not
* contained by the set.
*
* @param o object
* @return rank of the given object
*/
Long rank(Object o);
/**
* Returns the rank (position) of the given element in the set, in descending order. Returns null if the element is
* not contained by the set.
*
* @param o object
* @return reverse rank of the given object
*/
Long reverseRank(Object o);
/**
* Returns the default score used by this set.
*
* @return the default score used by the implementation.
*/
Double getDefaultScore();
/**
* Returns the first (lowest) element currently in this sorted set.
*
* @return the first (lowest) element currently in this sorted set.
* @throws NoSuchElementException sorted set is empty.
*/
E first();
/**
* Removes the first (lowest) object at the top of this sorted set and returns that object as the value of this
* function.
*
* @return the first (lowest) element currently in this sorted set.
* @throws NoSuchElementException sorted set is empty.
* @since 2.6
*/
E popFirst();
/**
* Removes the first (lowest) object at the top of this sorted set and returns that object as the value of this
* function. Blocks connection until element available or {@code timeout} reached.
*
* @param timeout
* @param unit must not be {@literal null}.
* @return the first (lowest) element currently in this sorted set.
* @throws NoSuchElementException sorted set is empty.
* @since 2.6
*/
E popFirst(long timeout, TimeUnit unit);
/**
* Returns the last (highest) element currently in this sorted set.
*
* @return the last (highest) element currently in this sorted set.
* @throws NoSuchElementException sorted set is empty.
*/
E last();
/**
* Removes the last (highest) object at the top of this sorted set and returns that object as the value of this
* function.
*
* @return the last (highest) element currently in this sorted set.
* @throws NoSuchElementException sorted set is empty.
* @since 2.6
*/
E popLast();
/**
* Removes the last (highest) object at the top of this sorted set and returns that object as the value of this
* function. Blocks connection until element available or {@code timeout} reached.
*
* @param timeout
* @param unit must not be {@literal null}.
* @return the last (highest) element currently in this sorted set.
* @throws NoSuchElementException sorted set is empty.
* @since 2.6
*/
E popLast(long timeout, TimeUnit unit);
/**
* @since 1.4
* @return
*/
Iterator scan();
}