Class JigsawCaptchaGenerator

java.lang.Object
cloud.opencode.base.captcha.generator.AbstractCaptchaGenerator
cloud.opencode.base.captcha.interactive.JigsawCaptchaGenerator
All Implemented Interfaces:
CaptchaGenerator
public final class JigsawCaptchaGenerator extends AbstractCaptchaGenerator implements CaptchaGenerator
Jigsaw Captcha Generator — Generates puzzle piece ordering CAPTCHA 拼接验证码生成器 — 生成碎片排序验证码

This generator creates a jigsaw-style interactive CAPTCHA where an image is split into a grid of pieces that are shuffled. The user must arrange the pieces back into the correct order.

此生成器创建拼图式交互验证码，将图像切割成网格碎片并打乱顺序。 用户需要将碎片重新排列为正确顺序。

Features | 主要功能:

  • Grid-based puzzle piece ordering - 基于网格的碎片排序
  • Procedurally generated background (no external images) - 程序生成背景（无需外部图片）
  • Fisher-Yates shuffle with guaranteed displacement - Fisher-Yates 洗牌确保至少一个碎片移位
  • Base64-encoded piece images in metadata - 元数据中包含 Base64 编码的碎片图像
  • Configurable grid size (default 3x3) - 可配置网格大小（默认 3x3）

Usage Examples | 使用示例:

CaptchaGenerator gen = new JigsawCaptchaGenerator();
Captcha captcha = gen.generate(config);

// Retrieve shuffled piece images from metadata
List<String> pieces = (List<String>) captcha.metadata().get("pieces");
int gridSize = (int) captcha.metadata().get("gridSize");

// User submits answer as comma-separated positions: "1,2,0,..."
// Answer represents the position of each original piece in the shuffled layout

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是（无状态）
  • Null-safe: No (config must not be null) - 空值安全: 否（配置不能为null）
  • Low entropy: A 3x3 grid has 9! = 362,880 permutations. Must be used with BehaviorAnalyzer and CaptchaRateLimiter for adequate protection. 低熵: 3x3 网格有 9! = 362,880 种排列。必须配合 BehaviorAnalyzer 和 CaptchaRateLimiter 使用。

Performance | 性能:

  • Image generation is O(width * height) for background rendering - 背景渲染时间复杂度 O(width * height)
  • Piece cutting and encoding is O(gridSize^2 * pieceArea) - 碎片切割和编码 O(gridSize^2 * pieceArea)
  • Each piece is independently PNG-encoded for transport - 每个碎片独立 PNG 编码以便传输
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • JigsawCaptchaGenerator

      public JigsawCaptchaGenerator()

  • Method Details

    • getType

      public CaptchaType getType()
      Description copied from interface: CaptchaGenerator
      Gets the supported CAPTCHA type. 获取支持的验证码类型。
      Specified by:
      getType in interface CaptchaGenerator
      Returns:
      the CAPTCHA type | 验证码类型

    • generate

      public Captcha generate(CaptchaConfig config)
      Description copied from interface: CaptchaGenerator
      Generates a CAPTCHA with the specified configuration. 使用指定配置生成验证码。
      Specified by:
      generate in interface CaptchaGenerator
      Parameters:
      config - the configuration | 配置
      Returns:
      the generated CAPTCHA | 生成的验证码