Man tippt einen Namen in das Applicant-Feld auf Seite 1 eines frisch zusammengeführten Antragspakets, tabt weiter, und in vielen Viewern füllt sich das Applicant-Feld auf Seite 6 mit demselben Text. Niemand hat diese beiden Steuerelemente verbunden. Teil 1 und Teil 3 des Pakets stammen von unterschiedlichen Autoren, beide nannten ein Top-Level-Feld Applicant, und ein PDF-Formular identifiziert ein Feld über seinen vollqualifizierten Namen. Zwei Felder mit einem Namen sind, was das Dateiformat angeht, ein Feld, das zweimal gezeichnet wird
Die Lösung ist, vor dem Merge zu entscheiden, was ein geteilter Name bedeuten soll: verweigern, mit Absicht behalten oder den Neuankömmling umbenennen. Hinterher zu entscheiden ist viel schwerer, als es klingt
Was ISO 32000 unter einem Feldnamen versteht
Ein Feldname ist Identität, und die Spezifikation sagt das. ISO 32000-1 §12.7.3.2 baut den vollqualifizierten Namen aus dem partiellen Namen (dem T-Eintrag) eines Felds und jedes seiner Vorfahren auf, verbunden mit Punkten. Dieselbe Seite erlaubt mehreren Field-Dictionaries, sich einen vollqualifizierten Namen zu teilen, und beschreibt sie als unterschiedliche Repräsentationen desselben zugrunde liegenden Felds, die sich eigentlich nur in der Darstellung unterscheiden sollten. Die Fields-Arrays zweier unabhängig erstellter Formulare aneinanderzuhängen erzeugt genau diese Anordnung aus Versehen
Der Schaden hängt davon ab, was die kollidierenden Felder enthielten. Ein Date, das auf dem einen Formular das Geburtsdatum und auf dem anderen das Unterschriftsdatum meinte, hat jetzt einen einzigen Wert-Slot, und welcher Wert sich der Viewer zurechtlegt, landet an beiden Stellen. Ein Total auf einem Spesenblatt und ein Total auf einem Einzahlungsformular werden auseinanderlaufen, sobald einer von beiden berechnet wird. Signaturfelder sind der schlimmste Fall: zwei Signatur-Widgets auf verschiedenen Seiten, ein Name, und keine saubere Antwort darauf, welches Widget der Unterzeichner tatsächlich gebilligt hat
Groß- und Kleinschreibung zählt ebenfalls. Partielle Namen sind Text-Strings, und nichts in der Spezifikation faltet sie, also sind Total und total zwei verschiedene Felder. Eine Kollisionsprüfung, die Namen vor dem Vergleich lowercased, meldet Konflikte, die nicht existieren, und benennt unter einer Umbenennungs-Strategie Felder um, die niemand anfassen musste
Namen prüfen, bevor sich etwas bewegt
PDF Library for Delphi behandelt die Kollision in MergeDocumentEx(DocumentID, DuplicateFieldStrategy), das das durch DocumentID identifizierte Dokument in das aktuell ausgewählte Dokument zusammenführt und jeden Namenskonflikt klärt, bevor ein einziges Objekt umnummeriert wird. Die Strategie ist ein TPDFlibDuplicateFieldStrategy-Wert: dfsReject, dfsMerge oder dfsAutoNumber. Das schlichte MergeDocument verkettet die beiden Wurzel-Feld-Arrays weiterhin unverändert, was die richtige Wahl ist, wenn man beide Formulare besitzt und weiß, dass ihre Namen disjunkt sind
Die Reihenfolge ist der ganze Entwurf. Ein Merge muss die Objektnummern des eingehenden Dokuments verschieben, damit sie nicht mit denen des Ziels kollidieren, seine Seiten in den Seitenbaum des Ziels einnähen und seine Felder an das Formular anhängen. Taucht eine Kollision erst nach diesen Schritten auf, ist die Verweigerung nicht mehr gratis — das Ziel hat bereits Seiten geschluckt, die Objekte der Quelle tragen Nummern, mit denen keine der Dateien begann, und der Aufrufer hat keinen Zustand, auf den er zurückfallen könnte, außer beide Dateien neu von der Platte zu laden. MergeDocumentEx sammelt zuerst die Top-Level-Feldnamen beider Dokumente in eine geordnete, groß-/kleinschreibungssensible Menge und wendet die Strategie gegen diese Menge an. Unter dfsReject lässt eine Kollision den Aufruf 0 zurückgeben, mit LastErrorCode auf 705 gesetzt, und beide Dokumente bleiben exakt wie geladen: Sie können direkt nach der Verweigerung einen Feldwert aus dem Quelldokument lesen und bekommen den originalen Text zurück
Der Scan selbst ist billig. Bei n Namen im Ziel und m in der Quelle kostet das Sortieren in eine Menge in der Größenordnung von (n + m) log(n + m) Vergleichen, also fügt ein Paket mit ein paar hundert Feldern nichts hinzu, was neben dem Parsen der Dateien auffiele
Drei Eigenschaften des Scans zeigen sich in echten Formularpaketen:
- Verglichen werden nur Top-Level-Felder. In einem hierarchischen Formular heißt das der partielle Name des Elternteils, also kollidieren zwei Formulare, die je einen Elternteil namens
applicanthaben, selbst wenn ihre Kinder differieren, und die Auto-Nummerierung benennt das Elternteil um: Die eingehenden Kinder lesen sich dann alsapplicant_2.nameundapplicant_2.address - Eingehende Namen kommen geprüft in die Menge. Ein Quelldokument, das bereits zwei Top-Level-Felder mit demselben Namen trägt, triggert die Strategie beim zweiten, selbst wenn das Ziel überhaupt kein Feld dieses Namens hat
- Felder mit leerem partiellen Namen werden übersprungen, und hat eines der Dokumente kein AcroForm, gibt es nichts zu vergleichen, also läuft der Merge unter jeder Strategie durch
Die Ladeseite hat eine eigene Falle. LoadFromFile fügt der Bibliothek ein neues Dokument hinzu und wählt es aus, also ist die zu behaltende Kennung die, die SelectedDocument nach jedem Laden zurückgibt. Greift man vor dem Laden zu, hält man ein anderes Dokument in der Hand als das, in das man zu mergen glaubt
uses
SysUtils, PDFlibrary;
procedure BuildPack(const Part1, Part2, OutFile: WideString);
var
Lib: TPDFlib;
TargetDoc, SourceDoc: Integer;
begin
Lib := TPDFlib.Create;
try
if Lib.LoadFromFile(Part1, '') = 0 then
raise Exception.CreateFmt('Cannot load %s', [Part1]);
TargetDoc := Lib.SelectedDocument; // nach dem Laden lesen, nicht davor
if Lib.LoadFromFile(Part2, '') = 0 then
raise Exception.CreateFmt('Cannot load %s', [Part2]);
SourceDoc := Lib.SelectedDocument;
Lib.SelectDocument(TargetDoc); // das ausgewählte Dokument empfängt den Merge
if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
begin
if Lib.LastErrorCode <> 705 then
raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
// Doppelte Top-Level-Namen: beide Dokumente sind unberührt,
// also kann SourceDoc direkt in einen zweiten Versuch zurück
WriteLn('Duplicate field names in ', Part2, ', retrying with auto-numbering');
if Lib.MergeDocumentEx(SourceDoc, dfsAutoNumber) = 0 then
raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
end;
Lib.SaveToFile(OutFile);
finally
Lib.Free;
end;
end;
Zuerst streng, dann nachsichtig. Diese Zwei-Schritt-Form funktioniert nur, weil die Verweigerung SourceDoc geladen und intakt lässt; bei einem Merge, der auf halbem Weg scheitert, müsste der Fallback-Zweig mit dem Neuladen beider Dateien beginnen. Speziell auf 705 zu prüfen ist ebenfalls wichtig, denn eine ungültige Dokument-Kennung oder ein außerhalb des Bereichs liegender Strategie-Wert scheitert mit einem anderen Code, und ein Retry mit einer anderen Strategie repariert beides nicht
Eine Strategie wählen: verweigern, teilen oder umnummerieren
Für unbeaufsichtigte Pipelines: dfsReject zum Standard machen und 705 als Ticket für denjenigen behandeln, dem die Quellformulare gehören. Ein Feld stromaufwärts einmal umzubenennen ist billiger, als Monate später zu entdecken, dass ein Export-Mapping still aufgehört hat zu passen, weil ein Merge ein Total_2 erfand. Die automatischen Strategien verdienen ihren Platz, wenn ein Mensch die Formulare angesehen und entschieden hat, was die geteilten Namen bedeuten
dfsMerge behält den geteilten Namen mit Absicht. Bevor irgendetwas angehängt wird, werden Wert und Standardwert des Zielfelds in das eingehende Feld kopiert, also startet die zusammengeführte Datei konsistent, und ein Viewer, der Widgets nach Namen gruppiert, sieht ein logisches Feld mit einem Wert. Die beiden Field-Dictionaries bleiben getrennte Objekte, jedes mit seiner eigenen Seite, seiner Darstellung und seinen Aktionen. Sie in ein Dictionary zu falten würde Formatierung und Verhalten wegwerfen, die zum eingehenden Formular gehören, und diesen Tausch ist eine kosmetische Vereinfachung nicht wert
dfsAutoNumber benennt eingehende Duplikate um, indem es ein numerisches Suffix anhängt, beginnend bei _2, und nimmt die erste freie. Hat das Ziel bereits Shared und Shared_2, wird der Neuankömmling zu Shared_3. Das Ergebnis hängt nur von den vorhandenen Namen ab, nie von Objektnummern, also liefert das zweimalige Mergen derselben Dateien beide Male dieselben Namen — eine Eigenschaft, auf die sich nachgelagerte FDF-Importe und Datenbank-Mappings verlassen
Die Wahl zwischen den beiden automatischen Strategien läuft auf eine Frage hinaus: Soll das Füllen eines Steuerelements das andere mitfüllen? Bei dem Namen des Unterzeichners, der auf jedem Teil eines Pakets wiederkehrt: ja, und dfsMerge passt. Bei einer Summe, die auf jedem Formular anders berechnet wird: nein. Dort dfsAutoNumber wählen, oder besser, das Feld im Quellformular umbenennen, damit das Suffix nie auftaucht
Was enthält das zusammengeführte Formular danach?
Nehmen wir ein Ziel mit einem Top-Level-Textfeld Shared, das "Target value" hält, und eine Quelle mit ihrem eigenen Shared. Nach dfsMerge zählt FormFieldCount zwei Felder, beide betitelt Shared, beide melden "Target value". Nach dfsAutoNumber liefert dieselbe Eingabe Shared und Shared_2, und das eingehende Feld behält, welchen Wert es in der Quelldatei hatte
Das dfsMerge-Ergebnis hat eine scharfe Kante, und die sitzt in Ihrem eigenen Füllcode. FindFormFieldByTitle gibt den ersten Index zurück, dessen Titel passt, und SetFormFieldValue schreibt in genau ein Feld. Eine Routine, die Shared einmal nachschlägt und setzt, aktualisiert die Kopie des Ziels und lässt die eingehende Kopie den Wert halten, den sie zum Merge-Zeitpunkt empfing. Die gespeicherte Datei enthält nun zwei Felder mit einem Namen und zwei unterschiedlichen Werten, und welcher angezeigt wird, entscheidet der Viewer. Jede Übereinstimmung schreiben:
// Setzt jedes Feld, das Title trägt; liefert zurück, wie viele geschrieben wurden.
// Nach einem dfsMerge-Merge kann ein logisches Feld an mehreren Indizes auftauchen
function SetAllFieldsNamed(Lib: TPDFlib; const Title, Value: WideString): Integer;
var
I: Integer;
begin
Result := 0;
for I := 1 to Lib.FormFieldCount do
if Lib.GetFormFieldTitle(I) = Title then
begin
if Lib.SetFormFieldValue(I, Value) = 1 then
Inc(Result)
else
WriteLn(Format('Field %d (%s) not written, error %d',
[I, Title, Lib.LastErrorCode])); // schreibgeschützte Felder landen hier
end;
end;
Bevor ein zusammengeführtes Paket in einen Datenfeed gegabelt wird, ausgeben, was der Merge tatsächlich erzeugt hat. Eine Zwei-Zeilen-Schleife genügt, und sie fängt die umbenannten Eltern und _2-Suffixe ab, bevor es ein Import-Job tut:
for I := 1 to Lib.FormFieldCount do
WriteLn(Format('%3d %-30s %s',
[I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));
Ein Formularpaket in der Praxis zusammenbauen
Ein erfolgreicher Merge konsumiert das Quelldokument. Es wird aus der Dokumentenliste der Bibliothek entfernt, also fällt DocumentCount um eins, und die alte SourceDoc-Kennung darf nicht wieder verwendet werden. Das zusammengeführte Dokument nimmt die höhere der beiden PDF-Versionen an: Ein PDF-2.0-Formular in ein 1.7-Dokument zu mergen ergibt eine 2.0-Datei, was zählt, wenn ein nachgelagerter Archivierungsschritt eine bestimmte Version erwartet
Die Merge-Reihenfolge entscheidet, wessen Namen überleben. Das ausgewählte Dokument behält jeden seiner Namen, und Umbenennungen oder Wertkopien treffen immer nur die eingehenden Felder, also liefern A in B mergen und B in A mergen unterschiedliche auto-nummerierte Ergebnisse. Hat ein Paket ein primäres Formular — dasjenige, dessen Feldnamen Ihr Backoffice bereits kennt —, machen Sie es zum Ziel und mergen die Ergänzungen hinein
Zuletzt signieren. Eine Signatur deckt die Bytes der Revision ab, die sie signierte, und ein Merge schreibt die Datei neu, also trägt ein Teil, das vor der Montage signiert wurde, keine Signatur mehr, die zum Dokument passt. Bauen Sie das Paket, prüfen Sie die Feldliste, dann setzen Sie Signaturen auf die fertige Datei. Geht es im Job nur darum, Seiten aneinanderzunähen, und zählen die Formulare nicht, ist schnelles PDF-Merge mit Byte-Referenz-Verschiebung der schnellere Weg
Planen Sie die Datenseite neben dem Merge. Kommen Feldwerte von einem externen System, das Felder per Name adressiert, klären Sie die Benennung, bevor Sie dfsAutoNumber wählen, denn ein Shared_2 passt nicht auf ein Mapping, das Shared erwartet. Wert-Import- und Export-Formate behandelt FDF-, XFDF- und XFA-Formulardatenaustausch. Berechnungsskripte und Aktionen, die Felder per Name referenzieren, sind von Umbenennungen auf dieselbe Weise betroffen, und interaktive Formularaktionen und JavaScript zeigt, wo diese Referenzen leben
Duplikat-bewusstes Formular-Merging, Feldfüllung und digitale Signatur sind alle Teil derselben Bibliothek für Delphi-, C++Builder- und Free-Pascal-Projekte. Die Produktseite von PDF Library for Delphi listet den Rest der Formular- und Dokumentmontage-API auf