PDFBox 3无法保留自定义PDPage子类实例问题求助

问题原因 #

PDFBox内部的页面管理机制导致了这个问题：当调用PDDocument.addPage()传入自定义的MyPage实例时，PDFBox不会直接存储这个子类对象，而是基于该页面对应的底层COS（PDF对象系统）结构，重新创建标准的PDPage实例来管理。后续调用getPage()时，返回的是PDFBox内部生成的PDPage对象，而非最初传入的MyPage子类实例，因此强转时会抛出ClassCastException。

代码复现 #

自定义子类代码：

package pdfBox;

import org.apache.pdfbox.pdmodel.PDPage;

public class MyPage extends PDPage {
}

测试代码：

package pdfBox;

import org.apache.pdfbox.pdmodel.PDDocument;

public class PageTest {
  public static void main(String[] args) {
    PDDocument doc = new PDDocument();
    doc.addPage(new MyPage());
    MyPage myPage = (MyPage)doc.getPage(0);
  }
}

异常信息：

java.lang.ClassCastException: class org.apache.pdfbox.pdmodel.PDPage cannot be cast to class pdfBox.MyPage

解决方案 #

1. 采用组合模式替代继承（推荐）：
   放弃继承PDPage，转而将PDPage作为自定义类的成员变量，封装布局相关功能。示例如下：

package pdfBox;

import org.apache.pdfbox.pdmodel.PDPage;

public class MyPage {
    private PDPage page;

    public MyPage() {
        this.page = new PDPage();
    }

    // 自定义布局方法
    public void doLayout() {
        // 实现布局逻辑，操作page对象
    }

    public PDPage getPDPage() {
        return page;
    }
}

使用时将内部的PDPage实例传入PDDocument：

MyPage myPage = new MyPage();
doc.addPage(myPage.getPDPage());

2. 自定义文档页面管理逻辑（不推荐）：
   如果必须保留子类实例，可以尝试重写PDDocument中添加和获取页面的方法，直接存储和返回自定义子类对象。但这种方式会侵入PDFBox内部实现，后续版本升级可能导致兼容性问题，需谨慎使用。

内容的提问来源于stack exchange，提问作者Neil