TXFADataStructure-Klasse

TXFADataStructure, deklariert in HPDFXFADataStructure, verwaltet begrenzte strukturelle Editierungen an einem bestehenden nativen XFA-Knotenbaum und besitzt alle abgetrennten Elementbäume, die über den Graphen erzeugt, geklont oder entfernt wurden

CreateDataNode dient Data-DOM-Elementen, während CreateElement auch die Model-Element-Konstruktion unterstützt, die TXFAFormStructure verwendet

Der Konstruktor leiht Root und validiert den bestehenden Baum gegen TXFADataStructureLimits, bevor er zurückkehrt; der Graph muss vor dem Besitzer der geliehenen Root zerstört werden

Alle öffentlichen AnsiString-Namen, Namespace-URIs und Textwerte enthalten UTF-8-Bytes

Graph := TXFADataStructure.Create(DatasetsRoot, Limits, OnTick);
try
  Graph.BeginOperation(OnTick);
  try
    Node := Graph.CreateDataNode('dataValue', 'amount');
    Graph.SetValue(Node, '42');
    Graph.Append(RecordNode, Node);
  finally
    Graph.EndOperation;
  end;
finally
  Graph.Free;
end;

Operations-Scope

BeginOperation(OnTick) startet einen Scope und lehnt einen verschachtelten Scope ab; EndOperation gibt den gespeicherten Callback frei und ist beim Aufräumen sicher

Der Konstruktor führt seinen eigenen Preflight-Scope aus und gibt den Konstruktor-Callback vor der Rückkehr frei; nachfolgende Methoden benötigen einen neuen aktiven Scope

OnTick ist eine Delphi-anonyme Prozedur oder eine FPC-verschachtelte Prozedur vom Typ TXFADataStructureTick; sie darf eine Exception werfen, um Arbeit abzubrechen oder eine Aufrufer-Frist oder einen Operationszähler durchzusetzen

Methoden bereiten Allokationen, Ownership-Kapazität und erforderliche Namespace-Deklarationen vor ihrer finalen Abbruchprüfung und strukturellen Mutation vor; eine abgelehnte Einzel-Editierung bewahrt den bestehenden Dokumentgraphen

Eine Serie erfolgreicher direkter Graph-Aufrufe wird nicht automatisch zurückgerollt, wenn ein späterer Aufruf fehlschlägt; die Scripting-Runtime liefert die vollständige Ereignistransaktion und stellt ihr Dokument, den abgetrennten Graphen, Script-Identitäten, lexikalischen State und Journal gemeinsam wieder her

Erzeugung und Klonen

CreateDataNode(ClassName, Name, NamespaceURI = '') akzeptiert dataGroup oder dataValue, erzeugt ein frisches abgetrenntes Element und hält explizite Data-Node-Klassen-Metadaten fest

CreateElement(ClassName, Name, NamespaceURI) erzeugt ein abgetrenntes Model-Element, dessen XML-lokaler Name ClassName ist, mit optionalem XFA-name-Attribut und expliziter Default-Namespace-Deklaration

CreateElement validiert XML-Syntax, skalare Werte, reservierte Namespace-URIs und Graph-Kapazität; die höherstufige Form-Factory validiert das unterstützte XFA-Klassenschema

Name darf ein XML-lokaler Name oder ein qualifizierter Name sein, dessen nichtleerer Präfix die gelieferte nichtleere Namespace-URI hat; reservierte xml- und xmlns-Bindings werden validiert

Ein leerer Name ist für einen abgetrennten Konstruktionsschritt erlaubt; vor dem Anhängen einen gültigen Namen mit Rename setzen

Clone(Node, Recursive = True) erzeugt eine abgetrennte Kopie mit frischen nativen Identitäten; eine shallow Kopie behält den eigenen Wert, die Attribute und Namespace-Deklarationen des Elements und schließt Kindknoten aus

Geerbte Namespace-Deklarationen werden vor einem Klonen oder Verschieben materialisiert, sodass präfixierte Attribute ihren ursprünglichen Namespace außerhalb ihres früheren Ancestor-Scope behalten

Ownership-Editierungen

Append(Parent, Node) verschiebt denselben Knoten ans Ende der geordneten Kinder des Parents; InsertBefore(Parent, Node, Before) verschiebt ihn vor ein bestehendes direktes Kind, wobei Before = nil dem Anhängen entspricht

Remove(Parent, Node) koppelt das bestehende direkte Kind ab und überträgt sein Ownership an den Graphen; Objekt, Nachkommen und native Identitäten bleiben gültig, bis der Graph zerstört wird oder eine abgetrennte Snapshot-Wiederherstellung erfolgt

Fremde Graphen, Zyklen, das Verschieben der geliehenen Root, unbenanntes Anhängen, ungültige Geschwisterreferenzen und Node-/Tiefen-/Byte-Overflow werfen EHPDFXFAError

Wert- und Namenseditierungen

Rename(Node, Name) ändert den lokalen XML-Namen des Elements und behält dabei Präfix, Namespace-URI, Position, Nachkommen und native Identität; ein angehängtes Element verlangt einen nichtleeren gültigen XML-Namen

SetValue(Node, Value) validiert UTF-8- und XML-Skalarwerte, ersetzt gewöhnliche Textkinder und bewahrt Kommentare und Processing Instructions; leerer Text entfernt gewöhnliche Textkinder

SetAttribute(Node, Name, Value) ergänzt oder ersetzt ein Attribut, nachdem seine Qualified-Name-Syntax, sein UTF-8-Wert und sein projiziertes Byte-Budget validiert wurden; ein leerer Wert bleibt ein explizites leeres Attribut

SetNamespace(Node, NamespaceURI) ändert den expandierten Namespace des Elements und aktualisiert die Deklaration für seinen aktuellen Präfix, während reservierte Bindings validiert werden

DeclareNamespace(Node, Prefix, NamespaceURI) ergänzt oder ersetzt eine Namespace-Deklaration, ohne den expandierten Namen des Elements zu ändern; sie lehnt eine kollidierende Deklaration für den eigenen Präfix des Elements ab

Direkte Graph-Aufrufer koordinieren präfixierte Attribute mit ihren Namespace-Deklarationen und halten Compound-Editierungen innerhalb ihrer eigenen Rollback-Transaktion

Die Byte- und Node-Budgets umfassen den aggregierten Wert des Elements und seinen tatsächlich besessenen Textknoten, statt nur eine Repräsentation des Texts zu belasten

XML-Import-Preflight

ValidateImport(Node, Incoming, Overwrite, OnTick) prüft den projizierten aggregierten Graphen, bevor ein Aufrufer eine besessene Liste eingehender XML-Kinder importiert

Wenn Overwrite true ist, schließt die projizierte Größe die ersetzten Kinder und den aggregierten Wert des Ziels aus; sonst bleiben bestehende Kinder im Budget

Die Methode lässt die eingehende Liste und das Dokument unverändert und erzeugt nur dann einen temporären Operations-Scope, wenn kein Scope bereits aktiv ist

Abgetrennte Snapshots

CaptureDetached liefert einen Wert-Snapshot jeder abgetrennten Root und jedes Nachkommen, einschließlich Text, CDATA, Kommentare, Processing Instructions, Attribute und Namespace-Deklarationen

RestoreDetached(Snapshot) validiert und bereitet einen ersetzenden abgetrennten Wald vor, bevor das Ownership getauscht wird; sein zurückgegebenes Knoten-Array folgt der Snapshot-Reihenfolge und enthält frische native Identitäten für das Aufrufer-Remapping

Siehe TXFADataStructureSnapshot für Record-Felder und Identitätsregeln

Inspektion

Root exponiert die geliehene Root, und DetachedRoots exponiert die graph-besessenen Roots zur Inspektion; für Änderungen die Graph-Methoden verwenden, damit Ownership und Budgets kohärent bleiben

Transaktionales Data-DOM-Scripting · Transaktionales Form-Tree-Scripting · TXFANode