Interface CacheView<T>
-
- Type Parameters:
T- The cache type
- All Superinterfaces:
java.lang.Iterable<T>
- All Known Subinterfaces:
MemberCacheView,ShardCacheView,SnowflakeCacheView<T>,SortedSnowflakeCacheView<T>,UnifiedMemberCacheView
- All Known Implementing Classes:
net.dv8tion.jda.internal.utils.cache.AbstractCacheView,CacheView.SimpleCacheView
public interface CacheView<T> extends java.lang.Iterable<T>Read-only view on internal JDA cache of items.
This can be useful to check information such as size without creating an immutable snapshot first.Memory Efficient Usage
TheIterable.forEach(Consumer)method can be used to avoid creating a snapshot of the backing data store, it is implemented by first acquiring a read-lock and then iterating the code. The enhanced-for-loop uses theIterable.iterator()which has to first create a snapshot to avoid concurrent modifications. Alternatively thelockedIterator()can be used to acquire an iterator which holds a read-lock on the data store and thus prohibits concurrent modifications, for more details read the documentation ofClosableIterator. Streams fromstream()/parallelStream()both useIterable.iterator()with a snapshot of the backing data store to avoid concurrent modifications.
UsinggetElementsByName(String)is more efficient thanasList()as it usesIterable.forEach(Consumer)for pattern matching and thus does not need to create a snapshot of the entire data store likeasList()does.
Bothsize()andisEmpty()are atomic operations.Note that making a copy is a requirement if a specific order is desired. If using
lockedIterator()the order is not guaranteed as it directly iterates the backing cache. UsingIterable.forEach(Consumer)on aSortedSnowflakeCacheViewwill copy the cache in order to sort it, useSortedSnowflakeCacheView.forEachUnordered(Consumer)to avoid this overhead. The backing cache is stored using an un-ordered hash map.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static classCacheView.SimpleCacheView<T>Basic implementation ofCacheViewinterface.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default voidacceptStream(java.util.function.Consumer<? super java.util.stream.Stream<T>> action)Creates an unordered sequenced stream of the elements in this cache.static <E> CacheView<E>all(java.util.Collection<? extends CacheView<E>> cacheViews)Creates a combinedCacheViewfor all provided CacheView implementations.static <E> CacheView<E>all(java.util.function.Supplier<? extends java.util.stream.Stream<? extends CacheView<E>>> generator)Creates a combinedCacheViewfor all provided CacheView implementations.static UnifiedMemberCacheViewallMembers(java.util.Collection<? extends MemberCacheView> cacheViews)Creates a combinedUnifiedMemberCacheViewfor all provided MemberCacheView implementations.static UnifiedMemberCacheViewallMembers(java.util.function.Supplier<? extends java.util.stream.Stream<? extends MemberCacheView>> generator)Creates a combinedUnifiedMemberCacheViewfor all provided MemberCacheView implementations.static ShardCacheViewallShards(java.util.Collection<ShardCacheView> cacheViews)Creates a combinedShardCacheViewfor all provided ShardCacheView implementations.static ShardCacheViewallShards(java.util.function.Supplier<? extends java.util.stream.Stream<? extends ShardCacheView>> generator)Creates a combinedShardCacheViewfor all provided ShardCacheView implementations.static <E extends ISnowflake>
SnowflakeCacheView<E>allSnowflakes(java.util.Collection<? extends SnowflakeCacheView<E>> cacheViews)Creates a combinedSnowflakeCacheViewfor all provided SnowflakeCacheView implementations.static <E extends ISnowflake>
SnowflakeCacheView<E>allSnowflakes(java.util.function.Supplier<? extends java.util.stream.Stream<? extends SnowflakeCacheView<E>>> generator)Creates a combinedSnowflakeCacheViewfor all provided SnowflakeCacheView implementations.default <R> RapplyStream(java.util.function.Function<? super java.util.stream.Stream<T>,? extends R> action)Creates an unordered sequenced stream of the elements in this cache.java.util.List<T>asList()Creates an immutable snapshot of the current cache state.java.util.Set<T>asSet()Creates an immutable snapshot of the current cache state.default <R,A>
Rcollect(java.util.stream.Collector<? super T,A,R> collector)Collects all cached entities into a single Collection using the providedCollector.default voidforEachUnordered(java.util.function.Consumer<? super T> action)Behavior similar toIterable.forEach(Consumer)but does not preserve order.default java.util.List<T>getElementsByName(java.lang.String name)Creates an immutable list of all elements matching the given name.java.util.List<T>getElementsByName(java.lang.String name, boolean ignoreCase)Creates an immutable list of all elements matching the given name.booleanisEmpty()Whether the cache is emptyClosableIterator<T>lockedIterator()Returns an iterator with direct access to the underlying data store.java.util.stream.Stream<T>parallelStream()Creates a parallelStreamof all cached elements.longsize()The current size of this cache
This is alongas it may be a projected view of multiple caches (Seeall(java.util.function.Supplier))java.util.stream.Stream<T>stream()Creates aStreamof all cached elements.
-
-
-
Method Detail
-
asList
@Nonnull java.util.List<T> asList()
Creates an immutable snapshot of the current cache state.
This will copy all elements contained in this cache into a list.
This will be sorted for aSortedSnowflakeCacheView.- Returns:
- Immutable list of cached elements
-
asSet
@Nonnull java.util.Set<T> asSet()
Creates an immutable snapshot of the current cache state.
This will copy all elements contained in this cache into a set.- Returns:
- Immutable set of cached elements
-
lockedIterator
@Nonnull ClosableIterator<T> lockedIterator()
Returns an iterator with direct access to the underlying data store. This iterator does not support removing elements.
After usage this iterator should be closed to allow modifications by the library internals.Note: Order is not preserved in this iterator to be more efficient, if order is desired use
Iterable.iterator()instead!- Returns:
ClosableIteratorholding a read-lock on the data structure.- Since:
- 4.0.0
-
forEachUnordered
default void forEachUnordered(@Nonnull java.util.function.Consumer<? super T> action)Behavior similar toIterable.forEach(Consumer)but does not preserve order.
This will not copy the data store as sorting is not needed.- Parameters:
action- The action to perform- Throws:
java.lang.NullPointerException- If provided with null- Since:
- 4.0.0
-
applyStream
@Nullable default <R> R applyStream(@Nonnull java.util.function.Function<? super java.util.stream.Stream<T>,? extends R> action)Creates an unordered sequenced stream of the elements in this cache.
This does not copy the backing cache prior to consumption unlikestream().The stream will be closed once this method returns and cannot be used anymore.
Example
CacheView<User> view = jda.getUserCache();
long shortNames = view.applyStream(stream -> stream.filter(it -> it.getName().length() < 4).count());
System.out.println(shortNames + " users with less than 4 characters in their name");- Type Parameters:
R- The return type after performing the specified action- Parameters:
action- The action to perform on the stream- Returns:
- The resulting value after the action was performed
- Throws:
java.lang.IllegalArgumentException- If the action is null- Since:
- 4.0.0
- See Also:
acceptStream(Consumer)
-
acceptStream
default void acceptStream(@Nonnull java.util.function.Consumer<? super java.util.stream.Stream<T>> action)Creates an unordered sequenced stream of the elements in this cache.
This does not copy the backing cache prior to consumption unlikestream().The stream will be closed once this method returns and cannot be used anymore.
Example
CacheView<TextChannel> view = guild.getTextChannelCache();
view.acceptStream(stream -> stream.filter(it -> it.isNSFW()).forEach(it -> it.sendMessage("lewd").queue()));- Parameters:
action- The action to perform on the stream- Throws:
java.lang.IllegalArgumentException- If the action is null- Since:
- 4.0.0
- See Also:
applyStream(Function)
-
size
long size()
The current size of this cache
This is alongas it may be a projected view of multiple caches (Seeall(java.util.function.Supplier))This is more efficient than creating a list or set snapshot first as it checks the size of the internal cache directly.
- Returns:
- The current size of this cache
-
isEmpty
boolean isEmpty()
Whether the cache is emptyThis is more efficient than creating a list or set snapshot first as it checks the size of the internal cache directly.
On a projected cache view this will simply look through all projected views and return false the moment it finds one that is not empty.- Returns:
- True, if this cache is currently empty
-
getElementsByName
@Nonnull java.util.List<T> getElementsByName(@Nonnull java.lang.String name, boolean ignoreCase)
Creates an immutable list of all elements matching the given name.
For aMemberCacheViewthis will check theEffective Nameof the cached members.- Parameters:
name- The name to checkignoreCase- Whether to ignore case when comparing names- Returns:
- Immutable list of elements with the given name
- Throws:
java.lang.IllegalArgumentException- If the provided name isnull
-
getElementsByName
@Nonnull default java.util.List<T> getElementsByName(@Nonnull java.lang.String name)
Creates an immutable list of all elements matching the given name.
For aMemberCacheViewthis will check theEffective Nameof the cached members.- Parameters:
name- The name to check- Returns:
- Immutable list of elements with the given name
- Throws:
java.lang.IllegalArgumentException- If the provided name isnull
-
stream
@Nonnull java.util.stream.Stream<T> stream()
Creates aStreamof all cached elements.
This will be sorted for aSortedSnowflakeCacheView.- Returns:
- Stream of elements
-
parallelStream
@Nonnull java.util.stream.Stream<T> parallelStream()
Creates a parallelStreamof all cached elements.
This will be sorted for aSortedSnowflakeCacheView.- Returns:
- Parallel Stream of elements
-
collect
@Nonnull default <R,A> R collect(@Nonnull java.util.stream.Collector<? super T,A,R> collector)Collects all cached entities into a single Collection using the providedCollector. Shortcut forstream().collect(collector).- Type Parameters:
R- The output typeA- The accumulator type- Parameters:
collector- The collector used to collect the elements- Returns:
- Resulting collections
- Throws:
java.lang.IllegalArgumentException- If the provided collector isnull
-
all
@Nonnull static <E> CacheView<E> all(@Nonnull java.util.Collection<? extends CacheView<E>> cacheViews)
Creates a combinedCacheViewfor all provided CacheView implementations. This allows to combine cache of multiple JDA sessions or Guilds.- Type Parameters:
E- The target type of the projection- Parameters:
cacheViews- Collection ofCacheViewimplementations- Returns:
- Combined CacheView spanning over all provided implementation instances
-
all
@Nonnull static <E> CacheView<E> all(@Nonnull java.util.function.Supplier<? extends java.util.stream.Stream<? extends CacheView<E>>> generator)
Creates a combinedCacheViewfor all provided CacheView implementations. This allows to combine cache of multiple JDA sessions or Guilds.- Type Parameters:
E- The target type of the projection- Parameters:
generator- Stream generator ofCacheViewimplementations- Returns:
- Combined CacheView spanning over all provided implementation instances
-
allShards
@Nonnull static ShardCacheView allShards(@Nonnull java.util.Collection<ShardCacheView> cacheViews)
Creates a combinedShardCacheViewfor all provided ShardCacheView implementations.- Parameters:
cacheViews- Collection ofShardCacheViewimplementations- Returns:
- Combined ShardCacheView spanning over all provided implementation instances
-
allShards
@Nonnull static ShardCacheView allShards(@Nonnull java.util.function.Supplier<? extends java.util.stream.Stream<? extends ShardCacheView>> generator)
Creates a combinedShardCacheViewfor all provided ShardCacheView implementations.- Parameters:
generator- Stream generator ofShardCacheViewimplementations- Returns:
- Combined ShardCacheView spanning over all provided implementation instances
-
allSnowflakes
@Nonnull static <E extends ISnowflake> SnowflakeCacheView<E> allSnowflakes(@Nonnull java.util.Collection<? extends SnowflakeCacheView<E>> cacheViews)
Creates a combinedSnowflakeCacheViewfor all provided SnowflakeCacheView implementations.
This allows to combine cache of multiple JDA sessions or Guilds.- Type Parameters:
E- The target type of the chain- Parameters:
cacheViews- Collection ofSnowflakeCacheViewimplementations- Returns:
- Combined SnowflakeCacheView spanning over all provided implementation instances
-
allSnowflakes
@Nonnull static <E extends ISnowflake> SnowflakeCacheView<E> allSnowflakes(@Nonnull java.util.function.Supplier<? extends java.util.stream.Stream<? extends SnowflakeCacheView<E>>> generator)
Creates a combinedSnowflakeCacheViewfor all provided SnowflakeCacheView implementations.
This allows to combine cache of multiple JDA sessions or Guilds.- Type Parameters:
E- The target type of the chain- Parameters:
generator- Stream generator ofSnowflakeCacheViewimplementations- Returns:
- Combined SnowflakeCacheView spanning over all provided implementation instances
-
allMembers
@Nonnull static UnifiedMemberCacheView allMembers(@Nonnull java.util.Collection<? extends MemberCacheView> cacheViews)
Creates a combinedUnifiedMemberCacheViewfor all provided MemberCacheView implementations.
This allows to combine cache of multiple JDA sessions or Guilds.- Parameters:
cacheViews- Collection ofMemberCacheViewinstances- Returns:
- Combined MemberCacheView spanning over all provided instances
-
allMembers
@Nonnull static UnifiedMemberCacheView allMembers(@Nonnull java.util.function.Supplier<? extends java.util.stream.Stream<? extends MemberCacheView>> generator)
Creates a combinedUnifiedMemberCacheViewfor all provided MemberCacheView implementations.
This allows to combine cache of multiple JDA sessions or Guilds.- Parameters:
generator- Stream generator ofMemberCacheViewinstances- Returns:
- Combined MemberCacheView spanning over all provided instances
-
-