Class DocumentBuilder

java.lang.Object
cloud.opencode.base.pdf.document.DocumentBuilder
public final class DocumentBuilder extends Object
PDF Document Builder PDF 文档构建器

Fluent API for creating PDF documents.

用于创建 PDF 文档的流畅 API。

Features | 主要功能:

  • Set document metadata - 设置文档元数据
  • Configure page settings - 配置页面设置
  • Add pages with content - 添加带内容的页面
  • Set encryption and permissions - 设置加密和权限

Usage Examples | 使用示例:

// Create simple document
DocumentBuilder.create()
    .title("My Document")
    .author("John Doe")
    .addPage()
        .text("Hello, World!", 100, 700)
    .endPage()
    .save(Path.of("hello.pdf"));

// Create with settings
DocumentBuilder.create(PageSize.A4)
    .title("Report")
    .orientation(Orientation.LANDSCAPE)
    .margins(72, 72, 72, 72)
    .addPage()
        .text("Content", 100, 500)
    .endPage()
    .save(Path.of("report.pdf"));

Security | 安全性:

  • Thread-safe: No — not designed for concurrent use - 线程安全: 否 — 非并发设计
  • Null-safe: Yes — parameters are validated - 空值安全: 是 — 参数已验证

Performance | 性能特性:

  • Time complexity: O(1) per setter call; O(p) overall where p is the number of pages added - 时间复杂度: 每次 setter 调用 O(1)；整体为 O(p)，p 为添加的页面数
  • Space complexity: O(p) - stores one PageBuilder reference per page - 空间复杂度: O(p) - 每页存储一个 PageBuilder 引用
Since:
JDK 25, opencode-base-pdf V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • title

      public DocumentBuilder title(String title)
      Sets document title. 设置文档标题。
      Parameters:
      title - document title | 文档标题
      Returns:
      this builder | 当前构建器

    • author

      public DocumentBuilder author(String author)
      Sets document author. 设置文档作者。
      Parameters:
      author - document author | 文档作者
      Returns:
      this builder | 当前构建器

    • subject

      public DocumentBuilder subject(String subject)
      Sets document subject. 设置文档主题。
      Parameters:
      subject - document subject | 文档主题
      Returns:
      this builder | 当前构建器

    • keywords

      public DocumentBuilder keywords(String... keywords)
      Sets document keywords. 设置文档关键词。
      Parameters:
      keywords - document keywords | 文档关键词
      Returns:
      this builder | 当前构建器

    • creator

      public DocumentBuilder creator(String creator)
      Sets document creator. 设置文档创建者（软件）。
      Parameters:
      creator - creator application | 创建应用
      Returns:
      this builder | 当前构建器

    • pageSize

      public DocumentBuilder pageSize(PageSize pageSize)
      Sets default page size. 设置默认页面大小。
      Parameters:
      pageSize - page size | 页面大小
      Returns:
      this builder | 当前构建器

    • orientation

      public DocumentBuilder orientation(Orientation orientation)
      Sets default page orientation. 设置默认页面方向。
      Parameters:
      orientation - page orientation | 页面方向
      Returns:
      this builder | 当前构建器

    • margins

      public DocumentBuilder margins(float top, float right, float bottom, float left)
      Sets default margins. 设置默认边距。
      Parameters:
      top - top margin | 上边距
      right - right margin | 右边距
      bottom - bottom margin | 下边距
      left - left margin | 左边距
      Returns:
      this builder | 当前构建器

    • margins

      public DocumentBuilder margins(float margin)
      Sets uniform margins. 设置统一边距。
      Parameters:
      margin - margin size | 边距大小
      Returns:
      this builder | 当前构建器

    • defaultFont

      public DocumentBuilder defaultFont(PdfFont font)
      Sets default font. 设置默认字体。
      Parameters:
      font - default font | 默认字体
      Returns:
      this builder | 当前构建器

    • embedFont

      public DocumentBuilder embedFont(Path fontPath, String fontName)
      Embeds a TrueType font. 嵌入 TrueType 字体。
      Parameters:
      fontPath - path to TTF file | TTF 文件路径
      fontName - name to reference font | 引用字体的名称
      Returns:
      this builder | 当前构建器

    • watermark

      public DocumentBuilder watermark(PdfWatermark watermark)
      Sets document watermark. 设置文档水印。
      Parameters:
      watermark - watermark configuration | 水印配置
      Returns:
      this builder | 当前构建器

    • watermark

      public DocumentBuilder watermark(String text)
      Sets document watermark with text (convenience method). 设置文档文本水印（便捷方法）。
      Parameters:
      text - watermark text | 水印文本
      Returns:
      this builder | 当前构建器

    • header

      public DocumentBuilder header(PdfHeader header)
      Sets document header. 设置文档页眉。
      Parameters:
      header - header configuration | 页眉配置
      Returns:
      this builder | 当前构建器

    • header

      public DocumentBuilder header(String centerText)
      Sets document header with centered text (convenience method). 设置文档居中页眉（便捷方法）。
      Parameters:
      centerText - center text | 居中文本
      Returns:
      this builder | 当前构建器

    • footer

      public DocumentBuilder footer(PdfFooter footer)
      Sets document footer. 设置文档页脚。
      Parameters:
      footer - footer configuration | 页脚配置
      Returns:
      this builder | 当前构建器

    • footer

      public DocumentBuilder footer(String centerText)
      Sets document footer with centered text (convenience method). 设置文档居中页脚（便捷方法）。
      Parameters:
      centerText - center text | 居中文本
      Returns:
      this builder | 当前构建器

    • addPage

      public PageBuilder addPage()
      Adds a new page. 添加新页面。
      Returns:
      page builder for the new page | 新页面的构建器

    • addPage

      public PageBuilder addPage(PageSize pageSize)
      Adds a new page with specific size. 添加指定大小的新页面。
      Parameters:
      pageSize - page size | 页面大小
      Returns:
      page builder | 页面构建器

    • addPage

      public PageBuilder addPage(PageSize pageSize, Orientation orientation)
      Adds a new page with specific size and orientation. 添加指定大小和方向的新页面。
      Parameters:
      pageSize - page size | 页面大小
      orientation - page orientation | 页面方向
      Returns:
      page builder | 页面构建器

    • addPage

      public PageBuilder addPage(float width, float height)
      Adds a new page with custom dimensions in points. 添加自定义尺寸（点）的新页面。

      Use this overload when the page size cannot be expressed via PageSize enum — for example, barcode/QR renderers targeting arbitrary output dimensions.

      当页面尺寸无法用 PageSize 枚举表达时使用此重载， 例如条码/二维码渲染器针对任意输出尺寸的场景。

      Parameters:
      width - page width in points (must be positive) | 页面宽度（点，必须为正）
      height - page height in points (must be positive) | 页面高度（点，必须为正）
      Returns:
      page builder | 页面构建器
      Throws:
      IllegalArgumentException - if width or height is not positive | 宽或高不为正抛出

    • encrypt

      public DocumentBuilder encrypt(String userPassword, String ownerPassword)
      Sets document encryption. 设置文档加密。
      Parameters:
      userPassword - password to open document | 打开文档的密码
      ownerPassword - password for full access | 完全访问权限的密码
      Returns:
      this builder | 当前构建器

    • permissions

      public DocumentBuilder permissions(boolean allowPrinting, boolean allowCopying, boolean allowModifying, boolean allowAnnotations)
      Sets document permissions. 设置文档权限。
      Parameters:
      allowPrinting - allow printing | 允许打印
      allowCopying - allow copying | 允许复制
      allowModifying - allow modifying | 允许修改
      allowAnnotations - allow annotations | 允许注释
      Returns:
      this builder | 当前构建器

    • build

      public PdfDocument build()
      Builds the PDF document. 构建 PDF 文档。
      Returns:
      the built document | 构建的文档

    • save

      public void save(Path path)
      Builds and saves to file. 构建并保存到文件。
      Parameters:
      path - target file path | 目标文件路径

    • save

      public void save(OutputStream outputStream)
      Builds and writes to stream. 构建并写入流。
      Parameters:
      outputStream - target stream | 目标流

    • toBytes

      public byte[] toBytes()
      Builds and returns as bytes. 构建并返回字节数组。
      Returns:
      PDF bytes | PDF 字节数组

    • getTitle

      public String getTitle()

    • getAuthor

      public String getAuthor()

    • getSubject

      public String getSubject()

    • getKeywords

      public List<String> getKeywords()

    • getCreator

      public String getCreator()

    • getPageSize

      public PageSize getPageSize()

    • getOrientation

      public Orientation getOrientation()

    • getMarginTop

      public float getMarginTop()

    • getMarginRight

      public float getMarginRight()

    • getMarginBottom

      public float getMarginBottom()

    • getMarginLeft

      public float getMarginLeft()

    • getDefaultFont

      public PdfFont getDefaultFont()

    • getEmbeddedFonts

      public List<DocumentBuilder.EmbeddedFontEntry> getEmbeddedFonts()

    • getPages

      public List<PageBuilder> getPages()

    • isEncrypted

      public boolean isEncrypted()

    • getWatermark

      public PdfWatermark getWatermark()

    • getHeader

      public PdfHeader getHeader()

    • getFooter

      public PdfFooter getFooter()

    • create

      public static DocumentBuilder create()
      Creates a new document builder. 创建新的文档构建器。
      Returns:
      document builder | 文档构建器

    • create

      public static DocumentBuilder create(PageSize pageSize)
      Creates a new document builder with page size. 创建指定页面大小的文档构建器。
      Parameters:
      pageSize - page size | 页面大小
      Returns:
      document builder | 文档构建器