Package com.pd4ml.pdf.merge.internal

Class StructureTreeMerger

java.lang.Object

com.pd4ml.pdf.merge.internal.StructureTreeMerger

public final class StructureTreeMerger
extends java.lang.Object

Reconciles the accessibility structure tree (/StructTreeRoot / StructElem / ParentTree / /StructParents) across the pages pulled in from one or more source documents, building a single merged tree in the target document. com.pd4ml.pdf.cos has no built-in awareness of this model (it's read-only plumbing); this class implements the relevant parts of the structure-tree chapter of the PDF spec directly.

One instance is used for an entire merge operation, sharing the same COSObjectImporter used for page content so a StructElem's /Pg back-reference and a page's own clone are always the same target object.

Best-effort behavior: a page whose source document isn't tagged (or that itself has no /StructParents) is simply included with no structure; the merged document ends up tagged only if at least one selected page contributed structure.

Constructor Summary

Constructors

Constructor	Description
StructureTreeMerger(COSObjectImporter importer)

Method Summary

Modifier and Type	Method	Description
COSObject	finish()	Finalizes the merged tree: prunes any structure that ended up referencing pages that were never actually selected/cloned (e.g.
void	mergePage(COSDocument sourceDoc, COSDictionary sourceStructTreeRoot, COSDictionary sourcePageDict, COSDictionary clonedPageDict)	Merges one page's structure contribution, if any.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StructureTreeMerger

public StructureTreeMerger(COSObjectImporter importer)

Method Detail

mergePage

public void mergePage(COSDocument sourceDoc,
                      COSDictionary sourceStructTreeRoot,
                      COSDictionary sourcePageDict,
                      COSDictionary clonedPageDict)

Merges one page's structure contribution, if any. sourceStructTreeRoot is null when the source document isn't tagged at all -- the page is then simply left untagged, per this class's best-effort contract.

Two independent structure associations are reconciled per page: the page's own /StructParents (the parent-tree key for its content marked-content sequences, i.e. tagged text/graphics), and each of its /Annots entries' own /StructParent (the parent-tree key for that annotation specifically -- e.g. the /Form structure element wrapping a form field's Widget, or the /Link element wrapping a hyperlink's Link annotation). Missing the second one leaves such annotations in the merged output with no structure element referencing them at all -- present and functional, but invisible to assistive technology and a PDF/UA conformance failure.

finish

public COSObject finish()

Finalizes the merged tree: prunes any structure that ended up referencing pages that were never actually selected/cloned (e.g. a table spanning pages that were only partially selected), and returns the target StructTreeRoot reference to attach to the merged Catalog -- or null if no selected page contributed any structure, so the caller can leave the merged document untagged entirely rather than emit a vacuous StructTreeRoot.