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

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

    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.

    • 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 a SortedSnowflakeCacheView.
        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:
        ClosableIterator holding 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 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:
        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 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:
        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 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:
        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 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
java.util.List<T> getElementsByName​(@Nonnull
                                    java.lang.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:
        java.lang.IllegalArgumentException - If the provided name is null

      • 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 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:
        java.lang.IllegalArgumentException - If the provided name is null

      • stream

        @Nonnull
java.util.stream.Stream<T> stream()
        Creates a Stream of all cached elements.
        This will be sorted for a SortedSnowflakeCacheView.
        Returns:
        Stream of elements

      • parallelStream

        @Nonnull
java.util.stream.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
                              java.util.stream.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:
        java.lang.IllegalArgumentException - If the provided collector is null

      • all

        @Nonnull
static <E> CacheView<E> all​(@Nonnull
                            java.util.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
                            java.util.function.Supplier<? extends java.util.stream.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
                                java.util.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
                                java.util.function.Supplier<? extends java.util.stream.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
                                                                  java.util.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
                                                                  java.util.function.Supplier<? extends java.util.stream.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
                                         java.util.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
                                         java.util.function.Supplier<? extends java.util.stream.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