Package net.dv8tion.jda.api.utils

Interface MemberCachePolicy

All Known Implementing Classes:
LRUMemberCachePolicy
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface MemberCachePolicy
Policy which decides whether a member (and respective user) should be kept in cache.
This will be called throughout JDA when a member gets constructed or modified and allows for a dynamically adjusting cache of users.

When Guild.pruneMemberCache() is called, the configured policy will be used to unload any members that the policy has decided not to cache.

If GUILD_MEMBERS intent is disabled you should not use ALL or ONLINE. This intent enables guild member leave events which are required to remove members from cache properly.

This can be configured with JDABuilder.setMemberCachePolicy(MemberCachePolicy).

Example Policy


 MemberCachePolicy.VOICE                         // Keep in cache if currently in voice (skip LRU and ONLINE)
     .or(MemberCachePolicy.ONLINE)               // Otherwise, only add to cache if online
     .and(MemberCachePolicy.lru(1000)            // keep 1000 recently active members
         .unloadUnless(MemberCachePolicy.VOICE)) // only unload if they are not in voice/guild owner
Since:
4.2.0
See Also:

  • Field Details

    • NONE

      static final MemberCachePolicy NONE
      Disable all member caching

    • ALL

      static final MemberCachePolicy ALL
      Enable all member caching.

      Not recommended without GUILD_MEMBERS intent enabled. The api will only send the guild member leave events when this intent is enabled. Without those events the members will stay in cache indefinitely.

    • OWNER

      static final MemberCachePolicy OWNER
      Cache owner of the guild. This simply checks Member.isOwner().

    • ONLINE

      static final MemberCachePolicy ONLINE
      Cache online/idle/dnd users.
      Requires GatewayIntent.GUILD_PRESENCES and CacheFlag.ONLINE_STATUS to be enabled.

      This cannot cache online members immediately when they come online, due to discord limitations. Discord only sends presence information without member details so the member will be cached once they become active.

      Not recommended without GUILD_MEMBERS intent enabled. The api will only send the guild member leave events when this intent is enabled. Without those events the members will stay in cache indefinitely.

    • VOICE

      static final MemberCachePolicy VOICE
      Cache members who are connected to a voice channel.
      Requires GatewayIntent.GUILD_VOICE_STATES and CacheFlag.VOICE_STATE to be enabled.

    • BOOSTER

      static final MemberCachePolicy BOOSTER
      Cache members who are boosting the guild. This checks Member.isBoosting()
      Requires GUILD_MEMBERS to be enabled.

    • PENDING

      @Incubating static final MemberCachePolicy PENDING
      Caches members who haven't passed Membership Screening.

      Not recommended without GUILD_MEMBERS intent enabled. The api will only send the guild member update events when this intent is enabled. Without those events the members will stay in cache indefinitely.

      Incubating:
      Discord is still trying to figure this out

    • DEFAULT

      static final MemberCachePolicy DEFAULT
      The default policy to use with JDABuilder.createDefault(String).
      This is identical to VOICE.or(OWNER).
      See Also:

  • Method Details

    • cacheMember

      boolean cacheMember(@Nonnull Member member)
      Idempotent (ideally pure) function which decided whether to cache the provided member or not.
      The function should avoid throwing any exceptions or blocking.
      Parameters:
      member - The member
      Returns:
      True, if the member should be cached

    • or

      @Nonnull default MemberCachePolicy or(@Nonnull MemberCachePolicy policy)
      Convenience method to concatenate another policy.
      This is identical to (member) -> policy1.cacheMember(member) || policy2.cacheMember(member).
      Parameters:
      policy - The policy to concat
      Returns:
      New policy which combines both using a logical OR
      Throws:
      IllegalArgumentException - If the provided policy is null

    • and

      @Nonnull default MemberCachePolicy and(@Nonnull MemberCachePolicy policy)
      Convenience method to require another policy.
      This is identical to (member) -> policy1.cacheMember(member) && policy2.cacheMember(member).
      Parameters:
      policy - The policy to require in addition to this one
      Returns:
      New policy which combines both using a logical AND
      Throws:
      IllegalArgumentException - If the provided policy is null

    • any

      @Nonnull static MemberCachePolicy any(@Nonnull MemberCachePolicy policy, @Nonnull MemberCachePolicy... policies)
      Composes a policy by concatenating multiple other policies.
      This is logically identical to policy1 || policy2 || policy3 || ... || policyN.
      Parameters:
      policy - The first policy
      policies - The other policies
      Returns:
      New policy which combines all provided polices using a logical OR

    • all

      @Nonnull static MemberCachePolicy all(@Nonnull MemberCachePolicy policy, @Nonnull MemberCachePolicy... policies)
      Composes a policy which requires multiple other policies.
      This is logically identical to policy1 && policy2 && policy3 && ... && policyN.
      Parameters:
      policy - The first policy
      policies - The other policies
      Returns:
      New policy which combines all provided polices using a logical AND

    • lru

      @Nonnull static LRUMemberCachePolicy lru(int maxSize)
      Implementation using a Least-Recently-Used (LRU) cache strategy.

      Example

      
 MemberCachePolicy.ONLINE.and( // only cache online members
   MemberCachePolicy.lru(1000) // of those online members, track the 1000 most active members
     .unloadUnless(MemberCachePolicy.VOICE) // always keep voice members cached regardless of age
 )
      This policy would add online members into the pool of cached members. The cached members are limited to 1000 active members, which are handled by the LRU policy. When the LRU cache exceeds the maximum, it will evict the least recently active member from cache. If the sub-policy, in this case VOICE, evaluates to true, the member is retained in cache. Otherwise, the member is unloaded using Guild.unloadMember(long).

      Note that the LRU policy itself always returns true for cacheMember(Member), since that makes the member the most recently used instead.

      Parameters:
      maxSize - The maximum cache capacity of the LRU cache
      Returns:
      LRUMemberCachePolicy