In PDFlibPas, der Delphi-PDF-Bibliothek, bekommt eine mit MovePage verschobene Seite eigene Kopien der MediaBox-, CropBox- und Resources-Werte, die sie von ihrem alten Pages-Knoten geerbt hatte, und eine indirekte Referenz bleibt eine Referenz. Der verschobenen Seite dieselben Objekte zu geben, die der alte Pages-Knoten hält, ist die naheliegende Implementierung, und sie bedeutet, dass ein späteres SetPageBox oder DrawText auf der verschobenen Seite still diesen Knoten und jedes Geschwister umschreibt, das noch von ihm erbt. Dieselbe Kopieren-statt-Teilen-Regel deckt zwei verwandte Pfade ab: SetPageBox auf einer indirekten Box, die mehrere Seiten teilen, und CopyPageRanges, das geerbte Werte auf den Seiten des Quelldokuments materialisiert
Symptome dieser Art von Aliasing erwähnen nie die Objektidentität. Sie klingen wie "Ich habe Seite 7 zugeschnitten und die Seiten 8 bis 12 wurden mit zugeschnitten", oder "Ich habe die CropBox verkleinert und die MediaBox ist mitgewandert", oder, das verwirrendste, "Ich habe eine Seite in ein neues Dokument kopiert und die Originaldatei hat sich geändert". Nichts stürzt ab, nichts leckt, und die gespeicherte Datei ist völlig valides PDF. Sie enthält nur Geometrie, nach der niemand gefragt hat
Wie kann SetPageBox auf einer Seite ihre Geschwister verkleinern?
Es passiert, wenn zwei Seitenbaum-Einträge auf ein In-Memory-Array zeigen und SetPageBox sein Zielarray an Ort und Stelle editiert: Jede Seite oder jeder Pages-Knoten, der dieselbe Instanz hält, sieht die Änderung. Drei Codepfade in einem Seitenbaum-Editor können dieses Teilen erzeugen:
MovePagematerialisiert die vererbbaren Attribute auf die Seite, bevor es sie vom Parent abtrennt; die eigenen Objekte des Ahnen statt Kopien anzuhängen lässt die verschobene Seite und ihre früheren Geschwister ein Box-Array und ein Resources-Dictionary teilen- Ein Box-Schreiber, der indirekten Referenzen folgt und das referenzierte Array editiert, verkleinert mit einem einzigen Aufruf jede Seite, die auf ein
/MediaBox 11 0 R-Objekt zeigt, obMovePageje beteiligt war oder nicht CopyPageRangesmaterialisiert geerbte Werte auf der Quellseite, bevor es sie in das Zieldokument klont; die Pages-Knoten-Instanzen an die Quellseite anzuhängen, plus die MediaBox-Instanz selbst als Standard-CropBox, verknotet alle miteinander
Materialisierung selbst ist nicht optional. Nur /Resources mitzunehmen und eine Seite unter einen anderen Parent zu verschieben lässt sie still Größe und Drehung des Parents annehmen, also trägt MovePage MediaBox, CropBox und Rotate ebenfalls mit, worauf sich auch CollateDocumentsEx verlässt, wenn es Seiten umordnet. Die einzige Frage ist, ob diese Werte als Kopien oder als geteilte Instanzen ankommen
Direkte Werte, indirekte Referenzen und die Vererbung von Seitenattributen
Eine korrekte Kopie eines geerbten Seitenattributs dupliziert direkte Werte und belässt indirekte Referenzen als Referenzen, denn das ist genau die Unterscheidung, die ISO 32000-1 selbst zieht. Ein direktes Objekt wie [0 0 400 300], geschrieben innerhalb eines Dictionaries, gehört diesem Dictionary allein. Ein indirektes Objekt, einmal definiert als 11 0 obj und zitiert als 11 0 R, ist per Design geteilt: ISO 32000-1 §7.3.10 macht es von überall in der Datei adressierbar, und jedes 11 0 R bedeutet dasselbe Objekt
Die Vererbung von Seitenattributen, ISO 32000-1 §7.7.3.4, fügt einen dritten Fall hinzu. Resources, MediaBox, CropBox und Rotate dürfen auf einem Pages-Knoten sitzen und gelten für jede Nachfolgeseite, die keine eigenen definiert. Die Seite hält den Wert nicht; sie schlägt ihn über /Parent nach. Diese Nachschlagkette bricht in dem Moment, in dem eine Seite den Parent wechselt, deshalb müssen MovePage und BalancePageTree zuerst die effektiven Werte auf die Seite selbst schreiben. Die Frage ist nur, wie man sie schreibt
Warum ein Objekt-Pool den Fehler versteckt
In PDFlibPas gehört jedes geparste oder erzeugte PDF-Objekt dem TPDFStructure-Pool des Dokuments, und Dictionaries und Arrays speichern schlicht Zeiger auf ihre Einträge. TPDFDictionary.Add notiert den Zeiger und nichts weiter. Eine Instanz an zwei Parent-Container anzuhängen ist also auf jeder Ebene legal, die die Runtime prüfen kann: kein Double Free beim Abbau, kein Referenzzähler, der schiefgehen könnte, keine Exception. Die Serialisierung ist ebenso gnädig, denn jeder Container schreibt den aktuellen Wert der geteilten Instanz inline, und vor jeder Änderung ist die Ausgabe byte für byte das, was eine korrekte Kopie liefern würde
Das Aliasing kommt erst ans Licht, wenn jemand die geteilte Instanz an Ort und Stelle mutiert. SetPageBox tut genau das über einen Rechteck-Wrapper über dem bestehenden Array, und das Zeichnen auf einer Seite tut es am Resources-Dictionary, sobald ein Font oder Bild registriert wird. Die Änderung landet, stillschweigend, in jedem anderen Container, der den Zeiger hält
Wie PDFlibPas kopiert, statt zu teilen
PDFlibPas behandelt das Problem an beiden Enden: Die Materialisierung hängt Kopien an, und Box-Schreibvorgänge editieren nur ein Array, das die Seite besitzt. Jede Regel deckt einen Fall ab, den die andere nicht kann
Der Materialisierungs-Helfer, PLInheritPageAttributes, hängt Page.Owner.Decode(Value.Output) an statt Value selbst. Der Round-Trip durch den Serialisierer ist eine plumpe, aber exakte Art, die PDF-Semantik gratis zu bekommen. Ein direktes Array oder Dictionary serialisiert zu seinem Literaltext und dekodiert zu einer frischen, unabhängigen Instanz. Eine indirekte Referenz serialisiert zu 11 0 R und dekodiert zu einem neuen Referenzobjekt, das auf dasselbe Objekt 11 zeigt, also verweist die Seite weiterhin auf das geteilte Objekt, statt eine inline Kopie zu erhalten. Die Kopie ist exakt so tief wie die direkte Struktur: Alles, was über eine Referenz innerhalb eines kopierten Dictionaries erreichbar ist, bleibt geteilt, wie das Dateiformat es vorsieht. BalancePageTree ruft denselben Helfer für jede Seite auf, deren Parent es wechselt, also bekommen auch dort materialisierte Seiten getrennte Instanzen
Kopieren allein reicht nicht, denn der Referenzfall zeigt weiterhin auf ein geteiltes Objekt. Folgte SetPageBox dieser Referenz und editierte Objekt 11, würde die verschobene Seite erneut den alten Parent und seine anderen Kinder verkleinern. Also wendet der Box-Schreiber Copy-on-Write an: Er editiert nur an Ort und Stelle, wenn der eigene Eintrag der Seite ein direktes Array ist, und ersetzt eine indirekte oder fehlende Box durch ein neues direktes Array. Objekt 11 bleibt unangetastet für jede andere Seite, die es zitiert
| Codepfad | Geteilte Instanzen (die Falle) | PDFlibPas |
|---|---|---|
MovePage-Materialisierung | Seite hält die eigenen direkten Instanzen des Ahnen | Seite hält dekodierte Kopien; Referenzen bleiben Referenzen |
SetPageBox | Folgt einer Referenz und editiert das geteilte Array | Editiert nur ein direktes Array auf der Seite, schreibt sonst ein neues |
CopyPageRanges-Quellseite | Teilt Pages-Knoten-Boxen; CropBox ist die MediaBox-Instanz | Jeder materialisierte Wert auf der Quellseite ist eine Kopie |
| Default-Boxen beim Klonen von Seitenressourcen | CropBox, BleedBox, TrimBox und ArtBox teilen ein Array | Jede Default-Box bekommt ihr eigenes Array |
Die letzte Zeile ist die subtile. Klont die Bibliothek die Ressourcen einer Seite für Seiten-Erfassung oder Merging, füllt sie fehlende CropBox-, BleedBox-, TrimBox- und ArtBox-Einträge auf, und alle vier aus einer Array-Instanz zu füllen ließe ein Alias warten auf den ersten Aufrufer, der eine davon editiert. Wie diese Default-Box-Werte gewählt werden, ist ein eigenes Thema, behandelt im PDFlibPas-Leitfaden zu TrimBox-, BleedBox- und CropBox-Defaults
Das MovePage-Aliasing mit einem handgebauten PDF reproduzieren
Der schnellste Weg, Seitenbaum-Editier-Code auf Aliasing zu testen, ist ein kleines handgeschriebenes PDF, geladen mit LoadFromString, bei dem jede Objektnummer im Voraus bekannt ist. Der Helfer unten schreibt eine klassische Cross-Reference-Tabelle mit korrekt berechneten Byte-Offsets, sodass der Test nicht auf das Wiederherstellungs-Verhalten des Parsers bei beschädigten Dateien angewiesen ist
uses
System.SysUtils, PDFlibrary;
function BuildPdf(const Objects: array of AnsiString): AnsiString;
var
Offsets: array of Integer;
I, XRefPos: Integer;
begin
Result := '%PDF-1.4'#10;
SetLength(Offsets, Length(Objects));
for I := 0 to High(Objects) do
begin
Offsets[I] := Length(Result); // 0-basiertes Byte-Offset von "N 0 obj"
Result := Result + AnsiString(IntToStr(I + 1)) + ' 0 obj'#10 +
Objects[I] + #10'endobj'#10;
end;
XRefPos := Length(Result);
Result := Result + 'xref'#10'0 ' + AnsiString(IntToStr(Length(Objects) + 1)) +
#10'0000000000 65535 f '#10;
for I := 0 to High(Offsets) do // jeder Eintrag ist exakt 20 Bytes
Result := Result + AnsiString(Format('%.10d 00000 n ', [Offsets[I]])) + #10;
Result := Result + 'trailer'#10'<< /Size ' +
AnsiString(IntToStr(Length(Objects) + 1)) + ' /Root 1 0 R >>'#10 +
'startxref'#10 + AnsiString(IntToStr(XRefPos)) + #10'%%EOF'#10;
end;
function StreamObj(const Content: AnsiString): AnsiString;
begin
Result := '<< /Length ' + AnsiString(IntToStr(Length(Content))) +
' >>'#10'stream'#10 + Content + #10'endstream';
end;
Das Testdokument hat zwei Zwischen-Pages-Knoten. Knoten 3 trägt eine indirekte MediaBox (Objekt 11, 400 mal 300 Punkte), eine direkte CropBox und ein direktes Resources-Dictionary und besitzt zwei Seiten. Knoten 4 hat eine Letter-große MediaBox und besitzt die dritte Seite. Seite 1 auf Position 3 zu verschieben hängt sie unter Knoten 4 um, genau die Verschiebung also, die Materialisierung braucht: ohne sie würde die Seite zu einer Letter-Seite
procedure Check(Condition: Boolean; const Msg: string);
begin
if not Condition then
raise Exception.Create(Msg);
end;
procedure CheckMovedPageIsIsolated;
var
Lib: TPDFlib;
FontID: Integer;
begin
Lib := TPDFlib.Create;
try
Check(Lib.LoadFromString(BuildPdf([
'<< /Type /Catalog /Pages 2 0 R >>',
'<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 3 >>',
'<< /Type /Pages /Parent 2 0 R /Kids [5 0 R 6 0 R] /Count 2 ' +
'/MediaBox 11 0 R /CropBox [10 20 390 280] /Resources << >> >>',
'<< /Type /Pages /Parent 2 0 R /Kids [7 0 R] /Count 1 ' +
'/MediaBox [0 0 612 792] >>',
'<< /Type /Page /Parent 3 0 R /Contents 8 0 R >>',
'<< /Type /Page /Parent 3 0 R /Contents 9 0 R >>',
'<< /Type /Page /Parent 4 0 R /Contents 10 0 R >>',
StreamObj('1 w'), StreamObj('2 w'), StreamObj('3 w'),
'[0 0 400 300]']), '') = 1, 'load failed');
Lib.SelectPage(1);
Check(Lib.MovePage(3) = 1, 'MovePage failed');
Lib.SelectPage(3); // die Seite, die wir gerade verschoben haben
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'inherited MediaBox lost');
Lib.SetPageBox(1, 0, 200, 200, 200); // MediaBox 200 x 200
Lib.SetPageBox(2, 0, 100, 100, 100); // CropBox 100 x 100
FontID := Lib.AddStandardFont(4); // Helvetica
Lib.SelectFont(FontID);
Lib.SetTextSize(12);
Lib.DrawText(20, 20, 'MOVED');
// Den alten Parent ansehen, BEVOR eine andere Seite gewählt wird (siehe unten)
Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
'font registered in the old Pages node');
Lib.SelectPage(1); // frühere Seite 2, weiterhin unter Knoten 3
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling MediaBox changed');
Check(Abs(Lib.GetPageBox(2, 2) - 380) < 0.001, 'sibling CropBox changed');
Check(Pos(AnsiString('400'), Lib.GetObjectToString(11)) > 0,
'shared object 11 was rewritten');
finally
Lib.Free;
end;
end;
GetPageBox(BoxType, Dimension) nimmt den Box-Typ 1 für MediaBox und 2 für CropBox, und Dimension 2 für die Breite. Beim voreingestellten Ursprung unten links bedeutet SetPageBox(1, 0, 200, 200, 200) links 0, oben 200, 200 breit und 200 hoch. Mit einem Materialisierer, der Instanzen teilt, scheitern die Geschwister-Prüfungen: Die CropBox-Änderung landet im direkten Array von Knoten 3, und ein Box-Schreiber, der Referenzen folgt, schreibt Objekt 11 um
Ändert CopyPageRanges das Quelldokument?
CopyPageRanges schreibt tatsächlich auf die Quellseiten, aber jeder Wert, den es schreibt, ist eine separate Kopie, also bleiben spätere Änderungen an der Quelle lokal bei der Seite, die man editiert. Das Schreiben selbst ist Absicht: Die Quellseite braucht explizite MediaBox, CropBox, Rotate und Resources, bevor ihr Dictionary in das Ziel geklont wird, sonst würde die Kopie alles verlieren, was sie geerbt hatte. Umnummerierung und das Kopieren der Seite ins Ziel sind in dokumentübergreifende Objekt-Deep-Copy in PDFlibPas behandelt; die Falle hier sitzt auf der Quellseite, von der die meisten annehmen, eine Kopie lese sie nur
Die gespeicherte Ausgabe zeigt es nie. Geteilt oder kopiert, die materialisierten Werte serialisieren identisch, also speichern beide Dokumente so oder so byte für byte dasselbe. Erst eine Änderung am Quelldokument nach der Kopie enthüllt einen Alias:
procedure CheckSourceSurvivesCopy;
var
Lib: TPDFlib;
SourceID, TargetID: Integer;
begin
Lib := TPDFlib.Create;
try
Check(Lib.LoadFromString(BuildPdf([
'<< /Type /Catalog /Pages 2 0 R >>',
'<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 2 ' +
'/MediaBox [0 0 400 300] /Resources << >> >>',
'<< /Type /Page /Parent 2 0 R /Contents 5 0 R >>',
'<< /Type /Page /Parent 2 0 R /Contents 6 0 R >>',
StreamObj('1 w'), StreamObj('2 w')]), '') = 1, 'load failed');
SourceID := Lib.SelectedDocument;
TargetID := Lib.NewDocument; // wird das gewählte Dokument
Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');
Lib.SelectDocument(SourceID);
Lib.SelectPage(1);
Lib.SetPageBox(2, 50, 250, 100, 100); // nur die CropBox verkleinern
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'MediaBox followed CropBox');
Lib.SetPageBox(1, 0, 200, 200, 200);
Lib.SelectPage(2);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling page resized');
Lib.SelectDocument(TargetID); // die Kopie behält ihre Originalgröße
Lib.SelectPage(Lib.PageCount);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
finally
Lib.Free;
end;
end;
Beide Seiten hier erben die direkte MediaBox des Wurzelknotens. Ein Kopier-Schritt, der diese Instanz an Quellseite 1 anhängt, und sie erneut als CropBox von Seite 1 anhängt, würde das Verkleinern der CropBox die MediaBox verkleinern lassen und das Verkleinern der MediaBox Seite 2 über den Wurzelknoten verkleinern. Workflows, die Seiten herauskopieren und dann weiter an der Quelle editieren, etwa Duplex-Scans zu einem PDF kollatieren, bevor man die Originale beschneidet, sind der Ort, an dem diese Art von Alias auftaucht
Warum ist Instanz-Aliasing so schwer zu testen?
Instanz-Aliasing ist schwer zu testen, weil der beobachtbare Effekt drei Schritte in einer bestimmten Reihenfolge braucht: das Aliasing erzeugen, eine Seite mutieren, dann die andere Seite ansehen, bevor irgendetwas anderes sie anfasst. Die meisten Tests tun nur den ersten Schritt und vergleichen gespeicherte Ausgabe, die identisch ist, ob das Aliasing existiert oder nicht
Die Reihenfolgen-Falle in PDFlibPas ist SelectPage. Eine Seite zu wählen wendet den aktuellen Font erneut über SelectFont an, was diesen Font in den Ressourcen der Seite registriert. Eine Seite ohne eigenes /Resources löst zum Dictionary ihres Parents auf, also fügt das schlichte Wählen einer solchen Seite legitim /Font zum Pages-Knoten hinzu. Im MovePage-Test oben fügt das Wählen der früheren Seite 2 den Helvetica-Eintrag zu Knoten 3 hinzu, korrektes Verhalten und kein Leak. Deshalb läuft die GetObjectToString(3)-Prüfung vor SelectPage(1); vertauscht man die beiden, scheitert der Test, selbst wenn kein Alias existiert
Diese Regel markiert auch, was PDFlibPas bewusst in Ruhe lässt. Eine Ressource auf eine Seite zu schreiben, die ihr Resources-Dictionary erbt, schreibt in das Dictionary des Ahnen, und jedes Geschwister sieht den neuen Eintrag. Das ist Vererbung, wie sie spezifiziert ist, nicht Instanz-Teilen, und es ist harmlos, denn das Hinzufügen eines Font- oder Bild-Namens zu einem geteilten Dictionary ändert nicht, wie andere Seiten rendern. Soll eine Seite aufhören zu erben, erst ein eigenes Resources-Dictionary geben
Checkliste für PDF-Objektmodell-Code
Die Lektionen verallgemeinern sich auf jedes PDF-Objektmodell, das auf einem Pool und Zeiger-Containern baut, in Delphi oder woanders:
- Werden geerbte Attribute nach ISO 32000-1 §7.7.3.4 materialisiert, direkte Werte deep-copyen und indirekte Referenzen als neue Referenzen auf dasselbe Objekt belassen
- Niemals eine bestehende Instanz per
Addan einen zweiten Container hängen, außer das Teilen ist beabsichtigt und dokumentiert; das Eigentum eines Pools bedeutet, dass die Runtime sich nie beschwert - Nur das an Ort und Stelle editieren, was der aktuelle Knoten als direktes Objekt besitzt; indirekte oder geerbte Werte durch ein frisches direktes Objekt ersetzen (Copy-on-Write)
- Standardwerte, die aus einem anderen Eintrag abgeleitet sind, etwa eine CropBox aus einer MediaBox, brauchen ihre eigene Instanz
- Aliasing mit Mutieren-dann-Prüfen-Sequenzen am anderen Halter testen, und die Reihenfolge von Aufrufen prüfen, die zwischendurch legitim schreiben könnten
- Gespeicherte Ausgabe zu vergleichen beweist hier nichts: geteilte und kopierte Werte serialisieren identisch, bis zur ersten Änderung
PDFlibPas exponiert Seitenbaum-Editing, dokumentübergreifendes Kopieren und Seitenbox-Steuerung über eine einzige TPDFlib-Klasse für Delphi, C++Builder und Free Pascal. Editionen, Plattformen und die vollständige API-Referenz finden Sie auf der Produktseite der PDFlibPas-Delphi-PDF-Bibliothek