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.

  • Method Details

    • 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

      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:

    • 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