In PDFlibPas, la libreria PDF Delphi, una pagina spostata con MovePage riceve le sue copie dei valori MediaBox, CropBox e Resources che ereditava dal suo vecchio nodo Pages, e un riferimento indiretto resta un riferimento. Consegnare alla pagina spostata gli identici oggetti che il vecchio nodo Pages tiene è l'implementazione ovvia, e significa che un successivo SetPageBox o DrawText sulla pagina spostata riscrive in silenzio quel nodo e ogni sorella che eredita ancora da esso. La stessa regola copia-non-condividere copre due percorsi correlati: SetPageBox su una box indiretta che più pagine condividono, e CopyPageRanges, che materializza i valori ereditati sulle pagine del documento sorgente
I sintomi di questo tipo di aliasing non menzionano mai l'identità degli oggetti. Suonano come "ho ritagliato la pagina 7 e le pagine da 8 a 12 si sono ritagliate anche loro", o "ho ristretto il CropBox e il MediaBox si è spostato con esso", o, il più confondente, "ho copiato una pagina in un nuovo documento e il file originale è cambiato". Niente crash, niente leak, e il file salvato è PDF perfettamente valido. Contiene solo geometria che nessuno ha chiesto
Come può SetPageBox su una pagina ridimensionare le sorelle?
Succede quando due voci dell'albero pagine puntano a un array in memoria e SetPageBox modifica il suo array di destinazione sul posto: qualsiasi pagina o nodo Pages che tiene la stessa istanza vede la modifica. Tre percorsi di codice in un editor dell'albero pagine possono produrre quella condivisione:
MovePagematerializza gli attributi ereditabili sulla pagina prima di staccarla dal suo genitore; attaccare gli oggetti propri dell'antenato invece che copie lascia la pagina spostata e le sue ex sorelle che condividono un array di box e un dizionario Resources- Uno scrittore di box che segue i riferimenti indiretti e modifica l'array referenziato ridimensiona ogni pagina che punta a un oggetto
/MediaBox 11 0 Rcon una singola chiamata, cheMovePagesia mai coinvolto o no CopyPageRangesmaterializza i valori ereditati sulla pagina sorgente prima di clonarla nel documento di destinazione; attaccare le istanze dei nodi Pages alla pagina sorgente, più l'istanza MediaBox stessa come CropBox predefinito, lega tutto insieme
La materializzazione in sé non è opzionale. Portare attraverso solo /Resources e una pagina spostata sotto un genitore diverso prende in silenzio dimensione e rotazione di quel genitore, quindi MovePage porta anche MediaBox, CropBox e Rotate, cosa di cui conta anche CollateDocumentsEx quando riordina le pagine. L'unica domanda è se quei valori arrivano come copie o come istanze condivise
Valori diretti, riferimenti indiretti ed ereditarietà degli attributi di pagina
Una copia corretta di un attributo di pagina ereditato duplica i valori diretti e conserva i riferimenti indiretti come riferimenti, perché è questa la distinzione che traccia lo stesso ISO 32000-1. Un oggetto diretto come [0 0 400 300] scritto dentro un dizionario appartiene a quel dizionario da solo. Un oggetto indiretto, definito una volta come 11 0 obj e citato come 11 0 R, è condiviso per progetto: ISO 32000-1 §7.3.10 lo rende indirizzabile da qualsiasi punto del file, e ogni 11 0 R significa lo stesso oggetto
L'ereditarietà degli attributi di pagina, ISO 32000-1 §7.7.3.4, aggiunge un terzo caso. Resources, MediaBox, CropBox e Rotate possono stare su un nodo Pages e valere per ogni pagina discendente che non definisce i propri. La pagina non tiene il valore; lo risale attraverso /Parent. Quella catena di ricerca si spezza nel momento in cui una pagina cambia genitore, ed è per questo che MovePage e BalancePageTree devono prima scrivere i valori effettivi sulla pagina stessa. La domanda è solo come scriverli
Perché un object pool nasconde l'errore
In PDFlibPas ogni oggetto PDF analizzato o creato appartiene al pool TPDFStructure del documento, e i dizionari e gli array memorizzano semplici puntatori alle proprie voci. TPDFDictionary.Add registra il puntatore e nient'altro. Aggiungere una istanza a due contenitori padre è quindi legale a ogni livello che il runtime può controllare: niente doppia liberazione allo smontaggio, niente reference count che sbaglia, niente eccezioni. La serializzazione è altrettanto permissiva, dato che ogni contenitore scrive inline il valore corrente dell'istanza condivisa, e prima di qualsiasi modifica l'output è byte per byte ciò che una copia corretta produrrebbe
L'aliasing emerge solo quando qualcuno modifica sul posto l'istanza condivisa. SetPageBox fa esattamente questo attraverso un wrapper rettangolo sull'array esistente, e disegnare su una pagina lo fa al dizionario Resources quando si registra un font o un'immagine. La modifica atterra, in silenzio, in ogni altro contenitore che tiene il puntatore
Come PDFlibPas copia invece di condividere
PDFlibPas gestisce il problema da entrambe le estremità: la materializzazione attacca copie, e le scritture di box modificano solo un array che la pagina possiede. Ogni regola copre un caso che l'altra non può
La helper di materializzazione, PLInheritPageAttributes, attacca Page.Owner.Decode(Value.Output) piuttosto che Value stessa. Il round-trip attraverso il serializzatore è un modo brutale ma esatto di avere gratis la semantica PDF. Un array o dizionario diretto si serializza nel suo testo letterale e si decodifica in una istanza fresca e indipendente. Un riferimento indiretto si serializza in 11 0 R e si decodifica in un nuovo oggetto riferimento che punta allo stesso oggetto 11, quindi la pagina continua a riferirsi all'oggetto condiviso invece di ricevere una copia inline. La copia è profonda esattamente quanto la struttura diretta: qualsiasi cosa raggiunta attraverso un riferimento dentro un dizionario copiato resta condivisa, come il formato file intende. BalancePageTree chiama la stessa helper per ogni pagina di cui cambia genitore, quindi le pagine materializzate lì prendono anch'esse istanze separate
Copiare da solo non basta, perché il caso riferimento punta ancora a un oggetto condiviso. Se SetPageBox seguisse quel riferimento e modificasse l'oggetto 11, la pagina spostata ridimensionerebbe di nuovo il vecchio genitore e i suoi altri figli. Così lo scrittore di box applica copy-on-write: modifica sul posto solo quando la voce della pagina è un array diretto, e sostituisce una box indiretta o mancante con un nuovo array diretto. L'oggetto 11 resta intatto per ogni altra pagina che lo cita
| Percorso di codice | Condivisione di istanze (la trappola) | PDFlibPas |
|---|---|---|
Materializzazione di MovePage | La pagina tiene le istanze dirette proprie dell'antenato | La pagina tiene copie decodificate; i riferimenti restano riferimenti |
SetPageBox | Segue un riferimento e modifica l'array condiviso | Modifica solo un array diretto sulla pagina, altrimenti ne scrive uno nuovo |
Pagina sorgente di CopyPageRanges | Condivide le box dei nodi Pages; il CropBox è l'istanza MediaBox | Ogni valore materializzato sulla pagina sorgente è una copia |
| Box predefinite alla clonazione delle risorse di pagina | CropBox, BleedBox, TrimBox e ArtBox condividono un array | Ogni box predefinita prende il suo array |
L'ultima riga è quella sottile. Quando la libreria clona le risorse di una pagina per cattura o merge di pagine, riempie le voci mancanti di CropBox, BleedBox, TrimBox e ArtBox, e riempire tutte e quattro da una istanza array lascerebbe un alias in attesa del primo chiamante che ne modifica una. Come vengono scelte quelle box predefinite è un tema a sé, trattato nella guida PDFlibPas ai predefiniti di TrimBox, BleedBox e CropBox
Riprodurre l'aliasing di MovePage con un PDF costruito a mano
Il modo più veloce di testare codice di editing dell'albero pagine per aliasing è un piccolo PDF scritto a mano caricato con LoadFromString, dove ogni numero di oggetto è noto in anticipo. La helper sotto scrive una classica tabella cross-reference con offset di byte calcolati correttamente, così il test non conta sul comportamento di recupero del parser per file danneggiati
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 di byte a base zero di "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 // ogni voce è esattamente 20 byte
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;
Il documento di prova ha due nodi Pages intermedi. Il nodo 3 porta un MediaBox indiretto (oggetto 11, 400 per 300 punti), un CropBox diretto e un dizionario Resources diretto, e possiede due pagine. Il nodo 4 ha un MediaBox formato Letter e possiede la terza pagina. Spostare la pagina 1 alla posizione 3 le cambia genitore sotto il nodo 4, che è esattamente lo spostamento che richiede materializzazione: senza, la pagina diventerebbe una pagina 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); // la pagina appena spostata
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');
// Ispeziona il vecchio parent PRIMA di selezionare un'altra pagina (vedi sotto)
Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
'font registered in the old Pages node');
Lib.SelectPage(1); // ex pagina 2, ancora sotto il nodo 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) prende il tipo box 1 per MediaBox e 2 per CropBox, e la dimensione 2 per la larghezza. Con l'origine in basso a sinistra predefinita, SetPageBox(1, 0, 200, 200, 200) significa sinistra 0, cima 200, 200 largo e 200 alto. Con un materializzatore che condivide istanze, i controlli sulle sorelle falliscono: la modifica del CropBox atterra nell'array diretto del nodo 3, e uno scrittore di box che segue i riferimenti riscrive l'oggetto 11
CopyPageRanges cambia il documento sorgente?
CopyPageRanges scrive sì sulle pagine sorgenti, ma ogni valore che scrive è una copia separata, così le modifiche successive alla sorgente restano locali alla pagina che modificate. La scrittura in sé è intenzionale: la pagina sorgente vuole MediaBox, CropBox, Rotate e Resources espliciti prima che il suo dizionario venga clonato nella destinazione, altrimenti la copia perderebbe tutto ciò che ha ereditato. Rinumerazione e copia della pagina nella destinazione sono trattate in copia profonda di oggetti tra documenti in PDFlibPas; la trappola qui sta sul lato sorgente, che la maggior parte della gente assume che una copia solo legga
L'output salvato non lo mostra mai. Condivisi o copiati, i valori materializzati si serializzano identici, quindi entrambi i documenti si salvano byte per byte uguali in entrambi i casi. Solo una modifica al documento sorgente dopo la copia rivela un 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; // diventa il documento selezionato
Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');
Lib.SelectDocument(SourceID);
Lib.SelectPage(1);
Lib.SetPageBox(2, 50, 250, 100, 100); // restringe solo il 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); // la copia conserva la dimensione originale
Lib.SelectPage(Lib.PageCount);
Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
finally
Lib.Free;
end;
end;
Entrambe le pagine qui ereditano il MediaBox diretto del nodo radice. Un passo di copia che avesse attaccato quell'istanza alla pagina sorgente 1, e l'avesse attaccata di nuovo come CropBox della pagina 1, farebbe sì che restringere il CropBox restringa il MediaBox, e che ridimensionare il MediaBox ridimensioni la pagina 2 attraverso il nodo radice. I flussi di lavoro che copiano pagine fuori e poi continuano a modificare la sorgente, come collazionare scansioni duplex in un PDF prima di ritagliare gli originali, sono dove questo tipo di alias compare
Perché l'aliasing di istanze è così difficile da testare?
L'aliasing di istanze è difficile da testare perché l'effetto osservabile richiede tre passi in un ordine preciso: creare l'alias, modificare un lato, poi ispezionare l'altro lato prima che qualsiasi altra cosa lo tocchi. La maggior parte dei test fa solo il primo passo e confronta l'output salvato, che è identico che l'alias esista o no
La trappola d'ordine in PDFlibPas è SelectPage. Selezionare una pagina riapplica il font corrente tramite SelectFont, che registra quel font nelle risorse della pagina. Una pagina senza /Resources proprie si risolve al dizionario del genitore, così il solo selezionare una simile pagina aggiunge legittimamente /Font al nodo Pages. Nel test MovePage sopra, selezionare l'ex pagina 2 aggiunge la voce Helvetica al nodo 3, che è comportamento corretto e non un leak. Ecco perché il controllo GetObjectToString(3) gira prima di SelectPage(1); scambiateli e il test fallisce anche quando nessun alias esiste
Quella regola segna anche ciò che PDFlibPas lascia deliberamente in pace. Scrivere una risorsa su una pagina che eredita il suo dizionario Resources scrive nel dizionario dell'antenato, e ogni sorella vede la nuova voce. È l'ereditarietà che lavora come specificato, non condivisione di istanze, ed è innocua perché aggiungere un nome di font o immagine a un dizionario condiviso non cambia come renderizzano le altre pagine. Se vi serve che una pagina smetta di ereditare, datele prima il suo dizionario Resources
Lista di controlli per il codice di object model PDF
Le lezioni si generalizzano a qualsiasi object model PDF costruito su un pool e contenitori a puntatori, in Delphi o altrove:
- Quando materializzate attributi ereditati per ISO 32000-1 §7.7.3.4, copiate in profondità i valori diretti e conservate i riferimenti indiretti come nuovi riferimenti allo stesso oggetto
- Mai
Adddi un'istanza esistente a un secondo contenitore a meno che la condivisione sia voluta e documentata; la ownership da parte di un pool significa che il runtime non si lamenterà mai - Modificate sul posto solo ciò che il nodo corrente possiede come oggetto diretto; sostituite valori indiretti o ereditati con un oggetto diretto fresco (copy-on-write)
- I valori predefiniti derivati da un'altra voce, come un CropBox da un MediaBox, vogliono la propria istanza
- Testate l'aliasing con sequenze modifica-poi-ispeziona sull'altro detentore, e controllate l'ordine delle chiamate che potrebbero scrivere legittimamente in mezzo
- Confrontare l'output salvato non prova nulla qui: valori condivisi e copiati si serializzano identici fino alla prima modifica
PDFlibPas espone editing dell'albero pagine, copia tra documenti e controllo delle page box attraverso un'unica classe TPDFlib per Delphi, C++Builder e Free Pascal. Vedi la pagina prodotto della PDFlibPas Delphi PDF library per edizioni, piattaforme e il riferimento API completo