W PDFlibPas, bibliotece PDF dla Delphi, strona przeniesiona przez MovePage dostaje własne kopie wartości MediaBox, CropBox i Resources, które dziedziczyła ze swojego starego węzła Pages, a referencja pośrednia zostaje referencją. Podanie przeniesionej stronie dokładnie tych samych obiektów, które trzyma stary węzeł Pages, to oczywista implementacja — i znaczy, że późniejsze SetPageBox albo DrawText na przeniesionej stronie po cichu przepisze ten węzeł i każdą siostrę nadal dziedziczącą z niego. Ta sama reguła kopiuj-nie-dziel obejmuje dwie powiązane ścieżki: SetPageBox na pośrednim boxie współdzielonym przez kilka stron oraz CopyPageRanges, które materializuje wartości dziedziczone na stronach dokumentu źródłowego
Objawy tego rodzaju aliasingu nigdy nie wspominają o tożsamości obiektów. Brzmią jak „obciąłem stronę 7, a strony 8 do 12 też się obcięły", albo „zawęziłem CropBox, a MediaBox ruszył się razem z nim", albo — najbardziej mylące — „skopiowałem stronę do nowego dokumentu, a oryginalny plik się zmienił". Nic nie kracze, nic nie cieknie, a zapisany plik jest całkowicie poprawnym PDF-em. Po prostu zawiera geometrię, o którą nikt nie prosił
Jak SetPageBox na jednej stronie może przeskalować jej siostry?
Dzieje się tak, gdy dwa wpisy drzewa stron celują w jedną tablicę w pamięci, a SetPageBox edytuje swoją tablicę docelową na miejscu: każda strona albo węzeł Pages trzymające tę samą instancję widzą edycję. Trzy ścieżki kodu w edytorze drzewa stron mogą wyprodukować takie współdzielenie:
MovePagematerializuje atrybuty dziedziczne na stronie przed odłączeniem jej od rodzica; przypięcie własnych obiektów przodka zamiast kopii zostawia przeniesioną stronę i jej dawne siostry współdzielące tablicę boxa i słownik Resources- Pisarz boxów, który podąża za referencjami pośrednimi i edytuje wskazywaną tablicę, przeskaluje jednym wywołaniem każdą stronę celującą w jeden obiekt
/MediaBox 11 0 R— niezależnie od tego, czyMovePagew ogóle brał udział CopyPageRangesmaterializuje wartości dziedziczone na stronie źródłowej przed sklonowaniem jej do dokumentu docelowego; przypięcie instancji węzła Pages do strony źródłowej, plus samej instancji MediaBox jako domyślnego CropBoxa, spią wszystkie te elementy razem
Materializacja sama w sobie nie jest opcjonalna. Przenieś tylko /Resources, a strona przeniesiona pod innego rodzica po cichu przejmie jego rozmiar i obrót — dlatego MovePage wozi też MediaBox, CropBox i Rotate, na czym polega CollateDocumentsEx, gdy przestawia strony. Jedynym pytaniem jest, czy te wartości przychodzą jako kopie, czy jako współdzielone instancje
Wartości bezpośrednie, referencje pośrednie i dziedziczenie atrybutów strony
Poprawna kopia dziedziczonego atrybutu strony powiela wartości bezpośrednie i zostawia referencje pośrednie referencjami, bo takie rozróżnienie wprowadza sam ISO 32000-1. Obiekt bezpośredni, taki jak [0 0 400 300] zapisany w słowniku, należy tylko do tego słownika. Obiekt pośredni, zdefiniowany raz jako 11 0 obj i cytowany jako 11 0 R, jest z założenia współdzielony: ISO 32000-1 §7.3.10 czyni go adresowalnym z dowolnego miejsca pliku, a każde 11 0 R znaczy ten sam obiekt
Dziedziczenie atrybutów strony, ISO 32000-1 §7.7.3.4, dodaje trzeci przypadek. Resources, MediaBox, CropBox i Rotate mogą siedzieć na węźle Pages i obowiązywać każdą stronę potomną, która nie definiuje własnych. Strona nie trzyma wartości; odszukuje ją przez /Parent. Ten łańcuch odszukiwania pęka w momencie, gdy strona zmienia rodzica, dlatego MovePage i BalancePageTree muszą najpierw zapisać wartości efektywne na samej stronie. Pytanie brzmi tylko, jak je zapisać
Dlaczego pula obiektów ukrywa błąd
W PDFlibPas każdy sparsowany albo utworzony obiekt PDF jest własnością puli TPDFStructure dokumentu, a słowniki i tablice trzymają gołe wskaźniki na swoje wpisy. TPDFDictionary.Add zapamiętuje wskaźnik i nic poza tym. Dodanie jednej instancji do dwóch kontenerów rodzicielskich jest więc legalne na każdym poziomie, jaki runtime potrafi sprawdzić: żadnego podwójnego zwolnienia przy demontażu, żadnej liczby referencji, która mogłaby się pogubić, żadnego wyjątku. Serializacja jest równie wyrozumiała, bo każdy kontener zapisuje bieżącą wartość współdzielonej instancji inline, a przed jakąkolwiek edycją wyjście jest bajt w bajt tym, co wyprodukowałaby poprawna kopia
Aliasing wychodzi na jaw dopiero, gdy ktoś zmienia współdzieloną instancję w miejscu. Dokładnie to robi SetPageBox przez prostokątny wrapper na istniejącej tablicy, a rysowanie po stronie robi to ze słownikiem Resources w chwili rejestracji fontu albo obrazu. Edycja ląduje, po cichu, w każdym innym kontenerze trzymającym wskaźnik
Jak PDFlibPas kopiuje zamiast dzielić
PDFlibPas łapie problem na obu końcach: materializacja przypina kopie, a zapisy boxów edytują wyłącznie tablicę, którą strona posiada. Każda reguła pokrywa przypadek, którego druga nie obejmie
Pomocnik materializacji, PLInheritPageAttributes, przypina Page.Owner.Decode(Value.Output) zamiast samego Value. Podróż przez serializator tam i z powrotem to tępy, ale dokładny sposób zdobycia semantyki obiektów PDF za darmo. Bezpośrednia tablica albo słownik serializuje się do swojego dosłownego tekstu i dekoduje do świeżej, niezależnej instancji. Referencja pośrednia serializuje się do 11 0 R i dekoduje do nowego obiektu referencji celującego w ten sam obiekt 11, więc strona nadal odnosi się do współdzielonego obiektu zamiast dostać skopiowaną treść w linii. Kopia jest dokładnie tak głęboka jak struktura bezpośrednia: wszystko osiągalne przez referencję wewnątrz skopiowanego słownika pozostaje współdzielone, tak jak zamierza format pliku. BalancePageTree woła ten sam pomocnik dla każdej przenoszonej strony, więc strony materializowane tam też dostają osobne instancje
Samo kopiowanie nie wystarcza, bo przypadek referencyjny nadal celuje we współdzielony obiekt. Gdyby SetPageBox podążał za tą referencją i edytował obiekt 11, przeniesiona strona znów przeskalowałaby starego rodzica i jego pozostałe dzieci. Pisarz boxów stosuje więc copy-on-write: edytuje na miejscu tylko wtedy, gdy własny wpis strony jest bezpośrednią tablicą, a pośredni albo brakujący box zastępuje nową bezpośrednią tablicą. Obiekt 11 zostaje nietknięty dla każdej innej strony, która go cytuje
| Ścieżka kodu | Współdzielenie instancji (pułapka) | PDFlibPas |
|---|---|---|
Materializacja w MovePage | Strona trzyma bezpośrednie instancje przodka same w sobie | Strona trzyma zdekodowane kopie; referencje zostają referencjami |
SetPageBox | Podąża za referencją i edytuje współdzieloną tablicę | Edytuje tylko tablicę bezpośrednią na stronie, w innym wypadku zapisuje nową |
Strona źródłowa w CopyPageRanges | Dzieli boxy węzła Pages; CropBox to instancja MediaBoxa | Każda zmaterializowana wartość na stronie źródłowej to kopia |
| Domyślne boxy przy klonowaniu zasobów strony | CropBox, BleedBox, TrimBox i ArtBox dzielą jedną tablicę | Każdy domyślny box dostaje własną tablicę |
Ostatni wiersz to ten subtelny. Gdy biblioteka klonuje zasoby strony dla przechwycenia strony albo scalania, uzupełnia brakujące wpisy CropBox, BleedBox, TrimBox i ArtBox, a wypełnienie wszystkich czterech z jednej instancji tablicy zostawiłoby alias czekający na pierwszego wywołującego, który edytuje którąkolwiek z nich. Jak wybierane są te domyślne wartości boxów, to osobny temat — omawia go artykuł przewodnik PDFlibPas po domyślnych TrimBox, BleedBox i CropBox
Odtwarzanie aliasingu z MovePage na ręcznie zbudowanym PDF
Najszybszym sposobem przetestowania kodu edycji drzewa stron na aliasing jest mały ręcznie pisany PDF wczytany przez LoadFromString, w którym każdy numer obiektu zna się z góry. Pomocnik poniżej zapisuje klasyczną tabelę odniesień krzyżowych z poprawnie policzonymi offsetami bajtowymi, więc test nie polega na zachowaniu naprawczym parsera dla uszkodzonych plików
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); // offset bajtowy liczony od zera napisu "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 // każdy wpis ma dokładnie 20 bajtów
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;
Dokument testowy ma dwa pośrednie węzły Pages. Węzeł 3 niesie pośredni MediaBox (obiekt 11, 400 na 300 punktów), bezpośredni CropBox i bezpośredni słownik Resources oraz posiada dwie strony. Węzeł 4 ma MediaBox w rozmiarze Letter i posiada trzecią stronę. Przeniesienie strony 1 na pozycję 3 przepina ją pod węzeł 4, czyli dokładnie ten ruch, który wymaga materializacji: bez niej strona zamieniłaby się w stronę Letter
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); // strona, którą przed chwilą przeniesliśmy
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');
// Obejrzyj starego rodzica PRZED wybraniem innej strony (patrz niżej)
Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
'font registered in the old Pages node');
Lib.SelectPage(1); // dawna strona 2, wciąż pod węzłem 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) bierze typ boxa 1 dla MediaBox i 2 dla CropBox, a wymiar 2 dla szerokości. Przy domyślnym początku w lewym dolnym rogu SetPageBox(1, 0, 200, 200, 200) znaczy lewo 0, góra 200, 200 szerokości i 200 wysokości. Przy materializatorze dzielącym instancje kontrole sióstr zawodzą: edycja CropBoxa ląduje w bezpośredniej tablicy węzła 3, a pisarz boxów podążający za referencjami przepisuje obiekt 11
Czy CopyPageRanges zmienia dokument źródłowy?
CopyPageRanges faktycznie zapisuje na stronach źródłowych, ale każda zapisywana wartość to osobna kopia, więc późniejsze edycje źródła zostają lokalne w stronie, którą edytujesz. Samo zapisywanie jest zamierzone: strona źródłowa potrzebuje jawnych MediaBox, CropBox, Rotate i Resources, zanim jej słownik zostanie sklonowany do celu, inaczej kopia straciłaby wszystko, co dziedziczyła. Przenumerowanie i kopiowanie strony do celu pokrywa artykuł głęboka kopia obiektów między dokumentami w PDFlibPas; pułapka siedzi tu po stronie źródłowej, którą większość ludzi zakłada tylko czytaną
Zapisane wyjście nigdy tego nie pokaże. Współdzielone albo skopiowane, zmaterializowane wartości serializują się identycznie, więc oba dokumenty zapisują się bajt w bajt tak samo w obu przypadkach. Dopiero edycja dokumentu źródłowego po kopii ujawnia 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; // staje się wybranym dokumentem
Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');
Lib.SelectDocument(SourceID);
Lib.SelectPage(1);
Lib.SetPageBox(2, 50, 250, 100, 100); // zwęź tylko CropBox
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); // kopia zachowuje swój pierwotny rozmiar
Lib.SelectPage(Lib.PageCount);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
finally
Lib.Free;
end;
end;
Obie strony tutaj dziedziczą bezpośredni MediaBox węzła głównego. Krok kopiujący, który przypiąłby tę instancję do strony źródłowej 1 i przypiął ją ponownie jako CropBox strony 1, sprawiłby, że zawężenie CropBoxa zawęzi MediaBox, a zmiana rozmiaru MediaBoxa przeskaluje stronę 2 przez węzeł główny. Obiegi pracy, które kopiują strony, a potem kontynuują edycję źródła — jak składanie skanów dupleksowych w jeden PDF przed przycięciem oryginałów — to miejsca, gdzie taki alias wychodzi na jaw
Dlaczego aliasing instancji jest tak trudny do przetestowania?
Aliasing instancji jest trudny do przetestowania, bo obserwowalny efekt wymaga trzech kroków w konkretnej kolejności: utwórz alias, zmień jedną stronę, potem obejrzyj drugą, zanim cokolwiek innego ją dotknie. Większość testów robi tylko krok pierwszy i porównuje zapisane wyjście, które jest identyczne niezależnie od tego, czy alias istnieje
Pułapką kolejności w PDFlibPas jest SelectPage. Wybranie strony nakłada ponownie bieżący font przez SelectFont, co rejestruje ten font w zasobach strony. Strona bez własnego /Resources rozwiązuje się do słownika rodzica, więc samo wybranie takiej strony legalnie dokłada /Font do węzła Pages. W teście MovePage powyżej wybranie dawnej strony 2 dokłada wpis Helvetica do węzła 3 — to poprawne zachowanie, a nie wyciek. Dlatego kontrola GetObjectToString(3) biegnie przed SelectPage(1); zamień je miejscami, a test zawodzi nawet bez żadnego aliasu
Ta reguła oznacza też, czego PDFlibPas celowo nie rusza. Zapis zasobu do strony dziedziczącej swój słownik Resources pisze do słownika przodka i każda siostra widzi nowy wpis. To dziedziczenie działające według specyfikacji, nie współdzielenie instancji, i jest nieszkodliwe, bo dodanie nazwy fontu albo obrazu do współdzielonego słownika nie zmienia renderowania innych stron. Jeśli potrzebujesz, by strona przestała dziedziczyć, najpierw daj jej własny słownik Resources
Lista kontrolna dla kodu modelu obiektów PDF
Wnioski uogólniają się na każdy model obiektów PDF zbudowany na puli i kontenerach wskaźnikowych, w Delphi i gdziekolwiek indziej:
- Materializując dziedziczone atrybuty według ISO 32000-1 §7.7.3.4, kopiuj głęboko wartości bezpośrednie i zostawiaj referencje pośrednie jako nowe referencje na ten sam obiekt
- Nigdy nie dodawaj istniejącej instancji przez
Adddo drugiego kontenera, chyba że współdzielenie jest zamierzone i udokumentowane; własność puli znaczy, że runtime nigdy nie zaprotestuje - Edytuj w miejscu tylko to, co bieżący węzeł posiada jako obiekt bezpośredni; wartości pośrednie albo odziedziczone zastępuj świeżym obiektem bezpośrednim (copy-on-write)
- Wartości domyślne wyprowadzone z innego wpisu, jak CropBox z MediaBoxa, potrzebują własnej instancji
- Testuj aliasing sekwencjami zmień-potem-obejrzyj na drugim posiadaczu i sprawdzaj kolejność wywołań, które mogłyby legalnie zapisać po drodze
- Porównywanie zapisanego wyjścia niczego tu nie dowodzi: współdzielone i skopiowane wartości serializują się identycznie do pierwszej edycji
PDFlibPas wystawia edycję drzewa stron, kopiowanie między dokumentami i kontrolę boxów stron przez jedną klasę TPDFlib dla Delphi, C++Builder i Free Pascal. Wydania, platformy i pełną referencję API znajdziesz na stronie produktu PDFlibPas Delphi PDF library