Interface SafeConstructor

All Known Implementing Classes:
SafeConstructor.DefaultSafeConstructor
public sealed interface SafeConstructor permits SafeConstructor.DefaultSafeConstructor
Safe Constructor - SPI interface for secure YAML construction 安全构造器 - 安全 YAML 构造的 SPI 接口

This interface provides an abstraction for safe YAML object construction, preventing arbitrary type instantiation and code execution vulnerabilities.

此接口为安全的 YAML 对象构造提供抽象， 防止任意类型实例化和代码执行漏洞。

Features | 主要功能:

  • Whitelist-based type safety for YAML deserialization - 基于白名单的 YAML 反序列化类型安全
  • Per-type and per-package allow rules - 按类型和按包的允许规则
  • Custom validator predicates - 自定义验证器谓词
  • Built-in safe types (primitives, dates, UUIDs) - 内置安全类型（基本类型、日期、UUID）

Usage Examples | 使用示例:

// Create a safe constructor with default settings
SafeConstructor constructor = SafeConstructor.create();

// Check if a type is safe
if (constructor.isSafeType(MyClass.class)) {
    // proceed with deserialization
}

// Create with custom allowed types
SafeConstructor custom = SafeConstructor.builder()
    .allowType(MyConfig.class)
    .allowPackage("com.myapp.config")
    .build();

Security | 安全性:

  • Thread-safe: Yes (immutable after construction) - 线程安全: 是（构建后不可变）
  • Null-safe: Yes (returns false for null types) - 空值安全: 是（空类型返回 false）
Since:
JDK 25, opencode-base-yml V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

    • BASIC_SAFE_TYPES

      static final Set<Class<?>> BASIC_SAFE_TYPES
      Default set of safe basic types 默认的安全基本类型集合

  • Method Details

    • create

      static SafeConstructor create()
      Creates a default safe constructor. 创建默认的安全构造器。
      Returns:
      safe constructor | 安全构造器

    • builder

      static SafeConstructor.Builder builder()
      Creates a builder for safe constructor. 创建安全构造器的构建器。
      Returns:
      builder | 构建器

    • isSafeType

      boolean isSafeType(Class<?> type)
      Checks if a type is safe for construction. 检查类型是否可以安全构造。
      Parameters:
      type - the type to check | 要检查的类型
      Returns:
      true if safe | 如果安全则返回 true

    • isSafeType

      boolean isSafeType(String typeName)
      Checks if a type name is safe for construction. 检查类型名称是否可以安全构造。
      Parameters:
      typeName - the type name | 类型名称
      Returns:
      true if safe | 如果安全则返回 true

    • validateType

      default void validateType(Class<?> type)
      Validates that a type is safe, throwing if not. 验证类型是否安全，如果不安全则抛出异常。
      Parameters:
      type - the type to validate | 要验证的类型
      Throws:
      YmlSecurityException - if type is not safe | 如果类型不安全

    • validateType

      default void validateType(String typeName)
      Validates that a type name is safe, throwing if not. 验证类型名称是否安全，如果不安全则抛出异常。
      Parameters:
      typeName - the type name to validate | 要验证的类型名称
      Throws:
      YmlSecurityException - if type is not safe | 如果类型不安全

    • getAllowedTypes

      Set<Class<?>> getAllowedTypes()
      Gets the set of allowed types. 获取允许的类型集合。
      Returns:
      allowed types | 允许的类型

    • getAllowedPackages

      Set<String> getAllowedPackages()
      Gets the set of allowed packages. 获取允许的包名集合。
      Returns:
      allowed packages | 允许的包名