Class CacheQuery<K,V>

java.lang.Object
cloud.opencode.base.cache.query.CacheQuery<K,V>
Type Parameters:
K - key type | 键类型
V - value type | 值类型

Security | 安全性:

  • Thread-safe: Yes (immutable builder, delegates to thread-safe cache) - 线程安全: 是（不可变构建器，委托给线程安全的缓存）
  • Null-safe: Yes - 空值安全: 是
public class CacheQuery<K,V> extends Object
Cache Query - Fluent API for querying cache entries 缓存查询 - 用于查询缓存条目的流式 API

Provides a fluent builder pattern for querying cache entries with filtering, pagination, and projection capabilities.

提供用于查询缓存条目的流式构建器模式， 具有过滤、分页和投影功能。

Features | 主要功能:

  • Key pattern matching - 键模式匹配
  • Value predicate filtering - 值谓词过滤
  • Range queries - 范围查询
  • Pagination - 分页
  • Sorting - 排序
  • Projection - 投影

Usage Examples | 使用示例:

// Simple key prefix query
List<User> users = CacheQuery.from(cache)
    .keyPrefix("user:")
    .values();

// Complex query with filtering and pagination
CacheQuery.Result<String, User> result = CacheQuery.from(cache)
    .keyPattern("user:*")
    .valueFilter(user -> user.isActive())
    .orderByKey()
    .skip(10)
    .limit(20)
    .execute();

// Range query for comparable keys
List<Order> orders = CacheQuery.from(orderCache)
    .keyRange("order:2024-01-01", "order:2024-12-31")
    .values();
Since:
JDK 25, opencode-base-cache V2.0.5
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • from

      public static <K,V> CacheQuery<K,V> from(Cache<K,V> cache)
      Create a query for a cache 为缓存创建查询
      Type Parameters:
      K - key type | 键类型
      V - value type | 值类型
      Parameters:
      cache - the cache to query | 要查询的缓存
      Returns:
      cache query builder | 缓存查询构建器

    • keyFilter

      public CacheQuery<K,V> keyFilter(Predicate<K> predicate)
      Filter by key predicate 通过键谓词过滤
      Parameters:
      predicate - key predicate | 键谓词
      Returns:
      this query | 此查询

    • keyPrefix

      public CacheQuery<K,V> keyPrefix(String prefix)
      Filter by key prefix (for String keys) 通过键前缀过滤（用于 String 键）
      Parameters:
      prefix - key prefix | 键前缀
      Returns:
      this query | 此查询

    • keySuffix

      public CacheQuery<K,V> keySuffix(String suffix)
      Filter by key suffix (for String keys) 通过键后缀过滤（用于 String 键）
      Parameters:
      suffix - key suffix | 键后缀
      Returns:
      this query | 此查询

    • keyPattern

      public CacheQuery<K,V> keyPattern(String pattern)
      Filter by key pattern (glob-style, for String keys) 通过键模式过滤（glob 风格，用于 String 键）
      Parameters:
      pattern - glob pattern (e.g., "user:*:profile") | glob 模式
      Returns:
      this query | 此查询

    • keyRegex

      public CacheQuery<K,V> keyRegex(String regex)
      Filter by key regex pattern (for String keys) 通过键正则表达式模式过滤（用于 String 键）
      Parameters:
      regex - regex pattern | 正则表达式模式
      Returns:
      this query | 此查询

    • keyRange

      public CacheQuery<K,V> keyRange(K fromKey, K toKey)
      Filter by key range (for Comparable keys) 通过键范围过滤（用于 Comparable 键）
      Parameters:
      fromKey - start key (inclusive) | 起始键（包含）
      toKey - end key (exclusive) | 结束键（不包含）
      Returns:
      this query | 此查询

    • keyIn

      public CacheQuery<K,V> keyIn(Set<K> keys)
      Filter by key set 通过键集合过滤
      Parameters:
      keys - set of keys to include | 要包含的键集合
      Returns:
      this query | 此查询

    • keyNotIn

      public CacheQuery<K,V> keyNotIn(Set<K> keys)
      Exclude specific keys 排除特定键
      Parameters:
      keys - set of keys to exclude | 要排除的键集合
      Returns:
      this query | 此查询

    • valueFilter

      public CacheQuery<K,V> valueFilter(Predicate<V> predicate)
      Filter by value predicate 通过值谓词过滤
      Parameters:
      predicate - value predicate | 值谓词
      Returns:
      this query | 此查询

    • entryFilter

      public CacheQuery<K,V> entryFilter(BiPredicate<K,V> predicate)
      Filter by entry predicate (key and value) 通过条目谓词过滤（键和值）
      Parameters:
      predicate - entry predicate | 条目谓词
      Returns:
      this query | 此查询

    • nonNull

      public CacheQuery<K,V> nonNull()
      Filter non-null values only 仅过滤非 null 值
      Returns:
      this query | 此查询

    • orderByKey

      public CacheQuery<K,V> orderByKey()
      Order by key (ascending, requires Comparable keys) 按键排序（升序，需要 Comparable 键）
      Returns:
      this query | 此查询

    • orderByKeyDesc

      public CacheQuery<K,V> orderByKeyDesc()
      Order by key descending (requires Comparable keys) 按键降序排序（需要 Comparable 键）
      Returns:
      this query | 此查询

    • orderBy

      public CacheQuery<K,V> orderBy(Comparator<Map.Entry<K,V>> comparator)
      Order by custom comparator 按自定义比较器排序
      Parameters:
      comparator - entry comparator | 条目比较器
      Returns:
      this query | 此查询

    • skip

      public CacheQuery<K,V> skip(long count)
      Skip first N results 跳过前 N 个结果
      Parameters:
      count - number to skip | 要跳过的数量
      Returns:
      this query | 此查询

    • limit

      public CacheQuery<K,V> limit(long count)
      Limit results to N 将结果限制为 N 个
      Parameters:
      count - maximum results | 最大结果数
      Returns:
      this query | 此查询

    • page

      public CacheQuery<K,V> page(int page, int pageSize)
      Paginate results 分页结果
      Parameters:
      page - page number (0-based) | 页码（从 0 开始）
      pageSize - page size | 页大小
      Returns:
      this query | 此查询

    • execute

      public CacheQuery.Result<K,V> execute()
      Execute query and return result 执行查询并返回结果
      Returns:
      query result | 查询结果

    • keys

      public List<K> keys()
      Execute and return only keys 执行并仅返回键
      Returns:
      list of matching keys | 匹配键列表

    • values

      public List<V> values()
      Execute and return only values 执行并仅返回值
      Returns:
      list of matching values | 匹配值列表

    • toMap

      public Map<K,V> toMap()
      Execute and return as map 执行并作为 Map 返回
      Returns:
      map of matching entries | 匹配条目的 Map

    • count

      public long count()
      Execute and return count 执行并返回计数
      Returns:
      count of matching entries | 匹配条目的计数

    • first

      public Optional<Map.Entry<K,V>> first()
      Execute and return first match 执行并返回第一个匹配项
      Returns:
      optional first entry | 可选的第一个条目

    • exists

      public boolean exists()
      Check if any entry matches 检查是否有任何条目匹配
      Returns:
      true if any match | 如果有匹配返回 true

    • stream

      public Stream<Map.Entry<K,V>> stream()
      Return as stream for custom processing 返回为 Stream 以进行自定义处理
      Returns:
      stream of matching entries | 匹配条目的 Stream