cloud.opencode.base.serialization.filter.ClassFilterBuilder

public final class ClassFilterBuilder extends Object

ClassFilterBuilder - Builder for Composite Class Filters 组合类过滤器构建器

Provides a fluent API for building composite ClassFilter instances that support allow/deny rules by exact class name, package prefix, and regex pattern. The built filter evaluates rules in a deterministic order: deny rules first, then allow rules, and finally the default policy.

提供流式 API 来构建组合 ClassFilter 实例，支持按精确类名、包前缀和正则表达式的允许/拒绝规则。构建的过滤器按确定性顺序评估规则：先拒绝规则，再允许规则，最后默认策略。

Features | 主要功能:

Exact class name allow/deny rules - 精确类名允许/拒绝规则
Package prefix allow/deny rules - 包前缀允许/拒绝规则
Regex pattern allow/deny rules - 正则模式允许/拒绝规则
Configurable default policy (allow or deny) - 可配置默认策略（允许或拒绝）

Evaluation Order | 评估顺序:

Check denied classes (exact match) - 检查拒绝的类（精确匹配）
Check denied packages (prefix match) - 检查拒绝的包（前缀匹配）
Check denied patterns (regex match) - 检查拒绝的模式（正则匹配）
Check allowed classes (exact match) - 检查允许的类（精确匹配）
Check allowed packages (prefix match) - 检查允许的包（前缀匹配）
Check allowed patterns (regex match) - 检查允许的模式（正则匹配）
Fall back to default policy - 回退到默认策略

Usage Examples | 使用示例:

// Build a filter that denies dangerous classes but allows everything else
ClassFilter filter = new ClassFilterBuilder()
    .denyPackage("javax.naming", "java.rmi", "sun.rmi")
    .denyPattern("org\\.apache\\.commons\\.collections\\.functors\\..*")
    .defaultAllow()
    .build();

// Build a strict allowlist filter
ClassFilter strict = new ClassFilterBuilder()
    .allowPackage("java.lang", "java.util", "java.time")
    .allow("java.math.BigDecimal", "java.math.BigInteger")
    .defaultDeny()
    .build();

Security | 安全性:

Thread-safe: No (builder is mutable), but built ClassFilter is thread-safe - 线程安全: 否（构建器可变），但构建的 ClassFilter 是线程安全的

Since:

JDK 25, opencode-base-serialization V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

Constructor Summary

Constructors

Constructor

Description

ClassFilterBuilder()

Creates a new ClassFilterBuilder with default-allow policy.
Method Summary

Modifier and Type

Method

Description

ClassFilterBuilder

allow(String... classNames)

Adds exact class names to the allow list.

ClassFilterBuilder

allowPackage(String... packages)

Adds package prefixes to the allow list.

ClassFilterBuilder

allowPattern(String regex)

Adds a regex pattern to the allow list.

ClassFilter

build()

Builds an immutable, thread-safe ClassFilter from the current configuration.

ClassFilterBuilder

defaultAllow()

Sets the default policy to allow classes not matched by any rule.

ClassFilterBuilder

defaultDeny()

Sets the default policy to deny classes not matched by any rule.

ClassFilterBuilder

deny(String... classNames)

Adds exact class names to the deny list.

ClassFilterBuilder

denyPackage(String... packages)

Adds package prefixes to the deny list.

ClassFilterBuilder

denyPattern(String regex)

Adds a regex pattern to the deny list.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- ClassFilterBuilder
  
  public ClassFilterBuilder()
  
  Creates a new ClassFilterBuilder with default-allow policy. 创建一个默认允许策略的 ClassFilterBuilder。
Method Details
- allow
  
  public ClassFilterBuilder allow(String... classNames)
  
  Adds exact class names to the allow list. 将精确类名添加到允许列表。
  
  Parameters:
  
  classNames - the fully qualified class names to allow | 要允许的完全限定类名
  
  Returns:
  
  this builder | 此构建器
  
  Throws:
  
  NullPointerException - if classNames is null or contains null | 当 classNames 为 null 或包含 null 时抛出
- allowPackage
  
  public ClassFilterBuilder allowPackage(String... packages)
  
  Adds package prefixes to the allow list. 将包前缀添加到允许列表。
  A class is matched if its fully qualified name starts with any of the given package prefixes followed by a dot. For example, package "java.lang" matches "java.lang.String" but not "java.language.Foo".
  
  如果类的完全限定名以给定包前缀加点号开头，则匹配。例如包 "java.lang" 匹配 "java.lang.String" 但不匹配 "java.language.Foo"。
  
  Parameters:
  
  packages - the package prefixes to allow | 要允许的包前缀
  
  Returns:
  
  this builder | 此构建器
  
  Throws:
  
  NullPointerException - if packages is null or contains null | 当 packages 为 null 或包含 null 时抛出
- allowPattern
  
  public ClassFilterBuilder allowPattern(String regex)
  
  Adds a regex pattern to the allow list. 将正则模式添加到允许列表。
  
  Parameters:
  
  regex - the regex pattern to match class names against | 用于匹配类名的正则模式
  
  Returns:
  
  this builder | 此构建器
  
  Throws:
  
  NullPointerException - if regex is null | 当 regex 为 null 时抛出
  
  PatternSyntaxException - if regex is invalid | 当正则表达式无效时抛出
- deny
  
  public ClassFilterBuilder deny(String... classNames)
  
  Adds exact class names to the deny list. 将精确类名添加到拒绝列表。
  
  Parameters:
  
  classNames - the fully qualified class names to deny | 要拒绝的完全限定类名
  
  Returns:
  
  this builder | 此构建器
  
  Throws:
  
  NullPointerException - if classNames is null or contains null | 当 classNames 为 null 或包含 null 时抛出
- denyPackage
  
  public ClassFilterBuilder denyPackage(String... packages)
  
  Adds package prefixes to the deny list. 将包前缀添加到拒绝列表。
  A class is matched if its fully qualified name starts with any of the given package prefixes followed by a dot. For example, package "javax.naming" matches "javax.naming.InitialContext" but not "javax.namingExtra".
  
  如果类的完全限定名以给定包前缀加点号开头，则匹配。例如包 "javax.naming" 匹配 "javax.naming.InitialContext" 但不匹配 "javax.namingExtra"。
  
  Parameters:
  
  packages - the package prefixes to deny | 要拒绝的包前缀
  
  Returns:
  
  this builder | 此构建器
  
  Throws:
  
  NullPointerException - if packages is null or contains null | 当 packages 为 null 或包含 null 时抛出
- denyPattern
  
  public ClassFilterBuilder denyPattern(String regex)
  
  Adds a regex pattern to the deny list. 将正则模式添加到拒绝列表。
  
  Parameters:
  
  regex - the regex pattern to match class names against | 用于匹配类名的正则模式
  
  Returns:
  
  this builder | 此构建器
  
  Throws:
  
  NullPointerException - if regex is null | 当 regex 为 null 时抛出
  
  PatternSyntaxException - if regex is invalid | 当正则表达式无效时抛出
- defaultAllow
  
  public ClassFilterBuilder defaultAllow()
  
  Sets the default policy to allow classes not matched by any rule. 设置默认策略为允许未被任何规则匹配的类。
  This is the default behavior. Classes that do not match any deny or allow rule will be allowed.
  
  这是默认行为。不匹配任何拒绝或允许规则的类将被允许。
  
  Returns:
  
  this builder | 此构建器
- defaultDeny
  
  public ClassFilterBuilder defaultDeny()
  
  Sets the default policy to deny classes not matched by any rule. 设置默认策略为拒绝未被任何规则匹配的类。
  This creates a strict allowlist: only classes explicitly allowed by allow rules will pass the filter.
  
  这将创建严格的白名单：只有被允许规则明确允许的类才能通过过滤器。
  
  Returns:
  
  this builder | 此构建器
- build
  public ClassFilter build()
  
  Builds an immutable, thread-safe ClassFilter from the current configuration. 根据当前配置构建不可变的、线程安全的 ClassFilter。
  The returned filter evaluates rules in the following order:
  
  If the class is in the denied classes set, deny
  
  If the class matches a denied package prefix, deny
  
  If the class matches a denied pattern, deny
  
  If the class is in the allowed classes set, allow
  
  If the class matches an allowed package prefix, allow
  
  If the class matches an allowed pattern, allow
  
  Otherwise, apply the default policy
  
  Returns:
  
  the built class filter | 构建的类过滤器

Class ClassFilterBuilder

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Details

ClassFilterBuilder

Method Details

allow

allowPackage

allowPattern

deny

denyPackage

denyPattern

defaultAllow

defaultDeny

build