Package net.dv8tion.jda.api.utils.cache

Interface CacheView<T>

Type Parameters:

T - The cache type

All Superinterfaces:

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 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

The Iterable.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 the Iterable.iterator() which has to first create a snapshot to avoid concurrent modifications. Alternatively the lockedIterator() 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 of ClosableIterator. Streams from stream()/parallelStream() both use Iterable.iterator() with a snapshot of the backing data store to avoid concurrent modifications.
Using getElementsByName(String) is more efficient than asList() as it uses Iterable.forEach(Consumer) for pattern matching and thus does not need to create a snapshot of the entire data store like asList() does.
Both size() and isEmpty() 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. Using Iterable.forEach(Consumer) on a SortedSnowflakeCacheView will copy the cache in order to sort it, use SortedSnowflakeCacheView.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 class	CacheView.SimpleCacheView<T>	Basic implementation of CacheView interface.

Method Summary

Modifier and Type	Method	Description
default void	acceptStream(Consumer<? super Stream<T>> action)	Creates an unordered sequenced stream of the elements in this cache.
static <E> CacheView<E>	all(Collection<? extends CacheView<E>> cacheViews)	Creates a combined CacheView for all provided CacheView implementations.
static <E> CacheView<E>	all(Supplier<? extends Stream<? extends CacheView<E>>> generator)	Creates a combined CacheView for all provided CacheView implementations.
static UnifiedMemberCacheView	allMembers(Collection<? extends MemberCacheView> cacheViews)	Creates a combined UnifiedMemberCacheView for all provided MemberCacheView implementations.
static UnifiedMemberCacheView	allMembers(Supplier<? extends Stream<? extends MemberCacheView>> generator)	Creates a combined UnifiedMemberCacheView for all provided MemberCacheView implementations.
static ShardCacheView	allShards(Collection<ShardCacheView> cacheViews)	Creates a combined ShardCacheView for all provided ShardCacheView implementations.
static ShardCacheView	allShards(Supplier<? extends Stream<? extends ShardCacheView>> generator)	Creates a combined ShardCacheView for all provided ShardCacheView implementations.
static <E extends ISnowflake> SnowflakeCacheView<E>	allSnowflakes(Collection<? extends SnowflakeCacheView<E>> cacheViews)	Creates a combined SnowflakeCacheView for all provided SnowflakeCacheView implementations.
static <E extends ISnowflake> SnowflakeCacheView<E>	allSnowflakes(Supplier<? extends Stream<? extends SnowflakeCacheView<E>>> generator)	Creates a combined SnowflakeCacheView for all provided SnowflakeCacheView implementations.
default <R> R	applyStream(Function<? super Stream<T>,? extends R> action)	Creates an unordered sequenced stream of the elements in this cache.
List<T>	asList()	Creates an immutable snapshot of the current cache state.
Set<T>	asSet()	Creates an immutable snapshot of the current cache state.
default <R,A> R	collect(Collector<? super T,A,R> collector)	Collects all cached entities into a single Collection using the provided Collector.
default void	forEachUnordered(Consumer<? super T> action)	Behavior similar to Iterable.forEach(Consumer) but does not preserve order.
default List<T>	getElementsByName(String name)	Creates an immutable list of all elements matching the given name.
List<T>	getElementsByName(String name, boolean ignoreCase)	Creates an immutable list of all elements matching the given name.
boolean	isEmpty()	Whether the cache is empty
ClosableIterator<T>	lockedIterator()	Returns an iterator with direct access to the underlying data store.
Stream<T>	parallelStream()	Creates a parallel Stream of all cached elements.
long	size()	The current size of this cache This is a long as it may be a projected view of multiple caches (See all(java.util.function.Supplier))
Stream<T>	stream()	Creates a Stream of all cached elements.

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Method Detail

asList

@Nonnull
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 a SortedSnowflakeCacheView.

Returns:

Immutable list of cached elements

asSet

@Nonnull
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:

ClosableIterator holding a read-lock on the data structure.

Since:

4.0.0

forEachUnordered

default void forEachUnordered(@Nonnull
                              Consumer<? super T> action)

Behavior similar to Iterable.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:

NullPointerException - If provided with null

Since:

4.0.0

applyStream

@Nullable
default <R> R applyStream(@Nonnull
                          Function<? super 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 unlike stream().

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:

IllegalArgumentException - If the action is null

Since:

4.0.0

See Also:

acceptStream(Consumer)

acceptStream

default void acceptStream(@Nonnull
                          Consumer<? super Stream<T>> action)

Creates an unordered sequenced stream of the elements in this cache.
This does not copy the backing cache prior to consumption unlike stream().

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:

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 a long as it may be a projected view of multiple caches (See all(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 empty

This 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
List<T> getElementsByName(@Nonnull
                          String name,
                          boolean ignoreCase)

Creates an immutable list of all elements matching the given name.
For a MemberCacheView this will check the Effective Name of the cached members.

Parameters:

name - The name to check

ignoreCase - Whether to ignore case when comparing names

Returns:

Immutable list of elements with the given name

Throws:

IllegalArgumentException - If the provided name is null

getElementsByName

@Nonnull
default List<T> getElementsByName(@Nonnull
                                  String name)

Creates an immutable list of all elements matching the given name.
For a MemberCacheView this will check the Effective Name of the cached members.

Parameters:

name - The name to check

Returns:

Immutable list of elements with the given name

Throws:

IllegalArgumentException - If the provided name is null

stream

@Nonnull
Stream<T> stream()

Creates a Stream of all cached elements.
This will be sorted for a SortedSnowflakeCacheView.

Returns:

Stream of elements

parallelStream

@Nonnull
Stream<T> parallelStream()

Creates a parallel Stream of all cached elements.
This will be sorted for a SortedSnowflakeCacheView.

Returns:

Parallel Stream of elements

collect

@Nonnull
default <R,A> R collect(@Nonnull
                              Collector<? super T,A,R> collector)

Collects all cached entities into a single Collection using the provided Collector. Shortcut for stream().collect(collector).

Type Parameters:

R - The output type

A - The accumulator type

Parameters:

collector - The collector used to collect the elements

Returns:

Resulting collections

Throws:

IllegalArgumentException - If the provided collector is null

all

@Nonnull
static <E> CacheView<E> all(@Nonnull
                            Collection<? extends CacheView<E>> cacheViews)

Creates a combined CacheView for 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 of CacheView implementations

Returns:

Combined CacheView spanning over all provided implementation instances

all

@Nonnull
static <E> CacheView<E> all(@Nonnull
                            Supplier<? extends Stream<? extends CacheView<E>>> generator)

Creates a combined CacheView for 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 of CacheView implementations

Returns:

Combined CacheView spanning over all provided implementation instances

allShards

@Nonnull
static ShardCacheView allShards(@Nonnull
                                Collection<ShardCacheView> cacheViews)

Creates a combined ShardCacheView for all provided ShardCacheView implementations.

Parameters:

cacheViews - Collection of ShardCacheView implementations

Returns:

Combined ShardCacheView spanning over all provided implementation instances

allShards

@Nonnull
static ShardCacheView allShards(@Nonnull
                                Supplier<? extends Stream<? extends ShardCacheView>> generator)

Creates a combined ShardCacheView for all provided ShardCacheView implementations.

Parameters:

generator - Stream generator of ShardCacheView implementations

Returns:

Combined ShardCacheView spanning over all provided implementation instances

allSnowflakes

@Nonnull
static <E extends ISnowflake> SnowflakeCacheView<E> allSnowflakes(@Nonnull
                                                                  Collection<? extends SnowflakeCacheView<E>> cacheViews)

Creates a combined SnowflakeCacheView for 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 of SnowflakeCacheView implementations

Returns:

Combined SnowflakeCacheView spanning over all provided implementation instances

allSnowflakes

@Nonnull
static <E extends ISnowflake> SnowflakeCacheView<E> allSnowflakes(@Nonnull
                                                                  Supplier<? extends Stream<? extends SnowflakeCacheView<E>>> generator)

Creates a combined SnowflakeCacheView for 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 of SnowflakeCacheView implementations

Returns:

Combined SnowflakeCacheView spanning over all provided implementation instances

allMembers

@Nonnull
static UnifiedMemberCacheView allMembers(@Nonnull
                                         Collection<? extends MemberCacheView> cacheViews)

Creates a combined UnifiedMemberCacheView for all provided MemberCacheView implementations.
This allows to combine cache of multiple JDA sessions or Guilds.

Parameters:

cacheViews - Collection of MemberCacheView instances

Returns:

Combined MemberCacheView spanning over all provided instances

allMembers

@Nonnull
static UnifiedMemberCacheView allMembers(@Nonnull
                                         Supplier<? extends Stream<? extends MemberCacheView>> generator)

Creates a combined UnifiedMemberCacheView for all provided MemberCacheView implementations.
This allows to combine cache of multiple JDA sessions or Guilds.

Parameters:

generator - Stream generator of MemberCacheView instances

Returns:

Combined MemberCacheView spanning over all provided instances