Kapitel 4. XFDF Annotationen

XFDF ist eine vereinfachte XML-Version des Forms Data Format (FDF). Eine XFDF Datei enthält daher auch Elemente, die im FDF Format beschrieben sind. Neben den eigentlichen Annotationsdaten, betrifft dies insbesondere zwei Elemente, die zusammengefasst als XFDFAnnotationElements in der jadice documentplatform bezeichnet werden.

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
<annots>...</annots>
<f href="testDocs/TEST.pdf"/>
<ids original="012345679abcdefghijABCDEFGHIJ" modified="abcdefghijABCDEFGHIJ012345679" custom-attribute="lalelu"/>
</xfdf>

Obiges Beispiel skizziert einen vereinfachten Aufbau eine XFDF Datei. Sie setzt sich aus drei untergeordneten Elementen des xfdf-Tags zusammen.

Das annots-Tag beinhaltet Annotationsdaten.

Das f-Tag entspricht dem Schlüssel F im FDF-Wörterbuch. Es gibt das PDF-Dokument an, aus dem diese XFDF-Datei exportiert wurde oder in das sie importiert werden soll. Wenn man die XFDF Annotationsdatei im Adobe Reader öffnet wird bei vorhandenem f-Tag auch die entsprechende PDF Datei geöffnet falls diese im angegeben Verzeichnis vorhanden ist.

Das ids-Tag entspricht dem ID-Schlüssel im FDF-Wörterbuch. Die ersten beiden Attribute sind Dateikennungen für die durch das f-Tag bezeichnete Quell- oder Zieldatei, die dem ID-Eintrag im Trailer-Dictionary der PDF-Datei entnommen werden.

Das Attribute orignal entspricht einem permanenten Bezeichner, der auf dem Inhalt der Datei zum Zeitpunkt ihrer ursprünglichen Erstellung basiert. Ein üblicher Wert hierfür ist eine MD5-Prüfsumme des Dokuments.

Das Attribut modified enthält eine eindeutige Kennung für die geänderte Version des PDF- und des zugehörigen XFDF-Dokuments. Ein üblicher Wert hierfür ist ebenfalls eine MD5-Prüfsumme.

Das ids-Tag kann weitere frei definierbare Attribute beinhalten.

In jadice beinhaltet die Klasse XFDFAnnotationElements die f-Tag und ids-Tag Angaben einer XFDF Datei.

jadice liest und schreibt, sofern vorhanden, die Angaben der XFDFAnnotationElements. Integratoren können diese Angaben für ihre Anwendungszwecke nutzen oder Anpassen vor einem Schreibvorgang.

Im folgenden Codebeispiel wird gezeigt, wie via API ein XFDFAnnotationElements Objekt vor dem Speichern für ein neu annotiertes Dokument erstellt und gesetzt wird.

Document document = <<Document-Instanz>>

XFDFAnnotationElements elements = new XFDFAnnotationElements();
// setze href Attribut
elements.getFile().put("href", "testDocs/TEST.pdf");
// setze selbstdefiniertes Attribut
elements.getFile().put("my-attribute", "1234");

// setze original Attribut
elements.getIdentifiers().put("original", "012345679abcdefghijABCDEFGHIJ");
// setze modified Attribut
elements.getIdentifiers().put("modified", "abcdefghijABCDEFGHIJ012345679");
// setze selbstdefiniertes Attribut
elements.getIdentifiers().put("my-attribute", "1234");

// XFDFAnnotationElements der Dokument-Instanz setzen
document.getProperties().put(XFDFAnnotationElements.class.getSimpleName(), elements);

Im folgenden Codebeispiel wird gezeigt, wie via API ein bereits vorhandenes XFDFAnnotationElements Objekt aus einem Dokument geholt wird.

Document document = <<Document-Instanz>>
XFDFAnnotationElements elements = document.getProperties().get(XFDFAnnotationElements.class.getSimpleName());
// Das XFDFAnnotationElements Objekt kann jetzt angepasst werden

Ein XFDFAnnotationElements Objekt kann auch beim Ladevorgang in der XFDFAnnotationReaderSettings Klasse gesetzt werden, dieses wird dann beim Laden befüllt und in der Dokument-Instanz abgelegt, siehe auch „Laden von XFDF Annotationen“.

Beim Speichervorgang kann ein vordefiniertes XFDFAnnotationElements Objekt in der XFDFAnnotationWriterSettings Klasse gesetzt werden, dieses wird dann beim Speichern verwendet und hat Vorrang vor dem in der Dokument-Instanz abgelegten Objekt. Siehe auch „Speichern von XFDF Annotationen“

Alle XFDF Annotationen eines Dokumentes sind in einem XML-basierenden XFDF Datenobjekt zusammengefasst.

Im folgenden ist ein Codebeispiel für einen Ladevorgang von XFDF Annotationen.

// XFDF Profil laden
final URL profileUrl = XFDFAnnotationReader.class.getResource("/xfdf-annotation-profile.xml");
final AnnotationProfile profile = AnnotationProfile.load(profileUrl);
      
// Vordefiniertes Profil im Document setzen
<<Document-Instanz>>.getProperties().put(AnnotationProfile.class.getName(), profile);

final DefaultReaderControls controls = new DefaultReaderControls();
controls.getSettings(XFDFAnnotationReaderSettings.class).setAnnotationProfile(profile);

// Ladevorgang
Reader reader = new Reader();
// Document-Instanz setzen
reader.setDocument(<<Document-Instanz>>);
// ReaderControls setzen
reader.setReaderControls(controls);
// Startseitenindex setzen
reader.setTargetIndex(0);
// XFDF Annotation Format setzen
reader.setFormat(new XFDFAnnotationFormat());

// XFDF Annotationen laden
reader.read(<<Annotation-Inputstream>>);
reader.complete();

XFDFAnnotationReaderSettings

XFDFAnnotationReaderSettings begleiten einen XFDF Annotationsladevorgang. Die wichtigsten Methoden der Settings sind in der folgenden Aufzählung beschrieben.

Es werden alle Annotationen des Dokuments in ein XML-basierenden XFDF Datenobjekt geschrieben.

Im Folgenden ist ein Codebeispiel für einen Ladevorgang von XFDF Annotationen.

Codebeispiel:

DefaultWriterControls controls = new DefaultWriterControls();
XFDFAnnotationWriterSettings settings = controls.getSettings(XFDFAnnotationWriterSettings.class);

// XFDF Writer erstellen          
XFDFAnnotationWriter writer = new XFDFAnnotationWriter();
// XFDF Annotationen schreiben
writer.write(<<Document-Instanz>>, <<Outputstream>>, controls);
// gespeicherte Annotationen zurücksetzen
Annotations.clearModified(document);

XFDFAnnotationWriterSettings

XFDFAnnotationWriterSettings begleiten einen XFDF Annotationsspeichervorgang. Die wichtigsten Methoden der Settings sind in der folgenden Aufzählung beschrieben.

Im annot-Tag können unter Umständen nicht XFDF spezifikationskonforme unbekannte XML-Attribute vorkommen, das kommt in der Regel vor, wenn XFDF Daten von Fremdherstellern geschrieben / erzeugt werden. Auch kann es hilfreich sein zusätzliche XML-Attribute in einer Annotationsstruktur zu verwalten / speichern.

Beim Laden werden die unbekannten annot-Attribute gesammelt und in einer AttributesXML Klasse gespeichert, die in den Properties des entsprechenden Annotationobjekts abgelegt wird.

Bei einer neu erstellten Annotation kann eine AttributesXML Klasse mit gewünschten Definitionen erstellt und mit einer AnnotationCustomizer Implementierung bei der Erzeugung dem Annotationsobjekt gesetzt werden.

Codebeispiel Zugriff auf AttributesXML Objekt:

XFDFAnnotation a = <<Annotation-Instanz>>
AttributesXML attributesXML = (AttributesXML) a.getProperties().get(AttributesXML.class.getSimpleName());
// Map mit allen unbekannten XML Attributen in dem entsprechenden annot-Element
Map<String, String> attributes = attributesXML.getAttributes();

Codebeispiel zum Setzen eines AttributesXML Objekt:

XFDFAnnotation a = <<Annotation-Instanz>>
AttributesXML attributesXML = new AttributesXML();
a.getProperties().put(AttributesXML.class.getSimpleName(), attributesXML);

Zu beachten ist, das bei der Verwendung von Fremdhersteller Software selbstdefinierte XML-Attribute beim Laden und Speichern verloren gehen können.

Mit der Klasse ElementXML können zusätzliche XML-Elemente innerhalb einer annot-Tag Elementstruktur verwaltet werden.

Beim Laden werden unbekannte XML-Elemente gesammelt und in einer ElementXML Klasse gespeichert, die in den Properties des entsprechenden Annotationobjekts abgelegt wird.

Codebeispiel Zugriff auf ElementXML Objekt:

XFDFAnnotation a = <<Annotation-Instanz>>
ElementXML elementXML = (ElementXML) a.getProperties().get(ElementXML.class.getSimpleName());

Codebeispiel zum Setzen eines ElementXML Objekt:

XFDFAnnotation a = <<Annotation-Instanz>>
ElementXML elementXML = new ElementXML();
a.getProperties().put(ElementXML.class.getSimpleName(), elementXML);

Zu beachten ist, das bei der Verwendung von Fremdhersteller Software selbstdefinierte XML-Elementstrukturen beim Laden und Speichern verloren gehen können.