Einleitung

Eine gültige PDF Datei beginnt mit den Zeichen %PDF-<<Versionsnummer>>, wobei die Versionsnummer der PDF Version des zugehörigen PDF Dokuments entspricht. Gültige PDF Versionen sind 1.0 bis 1.7 und 2.0. 

Wenn ein Dokumentbetrachter ein Datenstrom einliest, werden zunächst die ersten Bytes betrachtet. Anhand dieser Bytes erkennt die Anwendung, welches Format (als Beispiel GIF, JPEG, PDF usw.) das Dokument hat und kann so entscheiden, ob und wie die Anwendung mit diesen Dokument umgehen kann.

Beginnt ein Dokumentdatenstrom mit %PDF-<<Versionsnummer>>,  wird der Datenstrom als PDF Dokument erkannt.

Was passiert, wenn eine PDF Datei nicht mit %PDF-<<Versionsnummer>> beginnt, sondern andere Zeichen sich davor befinden?

Dieser Umstand kann gewollt oder ungewollt eintreten. Der ungewollte Fall kann sich durch fehlerhafte Kopier- oder Verschiebeprozesse ergeben, die Schmutzbytes vor den eigentlichen PDF Daten einschleichen lassen. Im gewollten Fall können in Ausnahmefällen spezielle Angaben zur Workflow Steuerung dem PDF Dokument vorangestellt werden. Beide Fälle sind eher selten, können aber eintreten.

In früheren Versionen des PDF Standards wurden PDF Dokumente, die nicht mit %PDF-<<Versionsnummer>> beginnen, per Spezifikation als fehlerhaft angesehen. Bei diesen Dokumenten konnte nicht davon ausgegangen werden, dass PDF Viewer damit umgehen und das Dokument korrekt anzeigen können.

Es galt daher die Empfehlung, Dokumente dieser Art zu korrigieren, in dem die führenden Schmutzbytes entfernt werden.

PDF 2.0   

Mit PDF 2.0 ist diese strenge Vorgabe gelockert worden. Für bestimmte Arbeitsabläufe oder Anwendungsfälle erlaubt nun PDF 2.0* Spezifikation, beliebige Daten in eine PDF-Datei zu schreiben, zusätzlich zu und vor den eigentlichen PDF-Daten. Dieses Verhalten wird aus Kompabilitätsgründen ausdrücklich nicht empfohlen, aber es wird auch nicht negiert.

*Siehe dazu auch ISO 32000-2 Document management — Portable document format — Part 2: PDF 2.0, Kapitel 7.5.2 File header

Was macht das OffsetPDFFormat?

Der OffsetPDFFormat wird der Lockerung des PDF-2.0 Standards gerecht und erfüllt die Anforderung auch PDF Dateien zu erkennen und zu akzeptieren, die zusätzliche Daten vor den eigentlichen PDF-Daten in ihrem Datenstrom beinhalten.

Warum braucht es dazu ein eigenes OffsetPDFFormat, kann das nicht auch das normale PDFFormat machen?   

Als Multi-Format Anwendung unterstützt jadice sehr viele Formate. Beim Einlesen von Dokumentdaten findet zunächst eine Formaterkennung statt. Dieser Prozess schaut sich die ersten Zeichen des Datenstroms an und entscheidet anhand derer eindeutig, welcher spezialisierter Format Reader das weitere Einlesen des Dokuments übernimmt.

Der naheliegende Ansatz, eine beliebige Anzahl führender Zeichen vor %PDF-<<Versionsnummer>> im bisherigen PDF Format zu akzeptieren, liefert keine eindeutige Formaterkennung. Es gibt andere Dokumentformate, die es erlauben PDF Dateien einzubinden und manchmal kann es auch einfach vorkommen, dass zufällig %PDF in dem Datenstrom eines anderen Formats zu finden ist. In diesen Fällen ist es für Formaterkennung nicht mehr eindeutig, um welches Format es sich handelt und welcher spezialisierte Reader den weiteren Lesevorgang übernehmen soll.
Um diese Fälle auszuschließen, reiht sich der OffsetPDFFormat am Ende der Formaterkennung ein und kommt erst zum Zug nachdem alle anderen Formate nach dem Datenstrom befragt worden sind und diesen abgelehnt haben..    

Abgrenzung zu PDF-Struktur Lesestrategien 

PDF Dokumente können unterschiedliche Strukturfehler aufweisen, die ein korrektes Einlesen und Darstellung des Dokuments verhindern. jadice ermöglicht über die Angabe einer PDF-Lesestrategie Heuristiken zu aktivieren, um gewisse Strukturfehler automatisch zu korrigieren und somit eine Anzeige des defekten Dokuments ermöglichen. Detailierte Angaben zu PDF-Lesestrategien finden sich hier. In dieser Beschreibung wird insbesondere der Modus PDFStructureReaderSettings.PDFStructureReadStrategy.STRICT vorgestellt, der einen strengen Lesemodus sicherstellt und zu Fehlermeldung und Abbruch des Lesevorgangs bei formal nicht korrekten oder defekten PDF Dokumenten führt.

Diese Einstellung steht in gewisser Weise in Widerspruch zu der Aufgabe des OffsetPDFFormats, da a priori nicht sichergestellt werden kann, welche Auswirkungen führende Bytes auf die nachfolgende Interpretation des PDF Datenstroms haben kann. Sollten alle anderen Formate den Dokumentdatenstrom während der Formaterkennung ablehnen und der OffsetPDFFormat kommt zum Zug, versucht er unabhängig eines möglicherweise gesetzen STRICT-Modus dennoch den Datenstrom zu lesen und gegebenenfalls sich aus den führenden Bytes ergebende Strukturfehler auszugleichen.
Wenn dieses Verhalten nicht gewünscht ist, kann die Wirkungsweise des OffsetPDFFormats deaktiviert werden. 

Konfigurationsmöglichkeiten

Die Analyse, ob und an welcher Stelle %PDF-<<Versionsnummer>> in einem Datenstrom zu finden ist, erzeugt einen gewissen Aufwand. Um insbesondere bei großen Dateien relativ schnell zu einem Ergebnis zu kommen, und den Ladevorgang nicht unnötig in der Formaterkennung auszubremsen, ist die Anzahl der zu untersuchenden Bytes im OffsetPDFFormats auf maximal 8192 führende Zeichen begrenzt. Standardmäßig werden als Default 2048 Zeichen als Offset betrachtet. Der Default Offset Wert kann per Konfiguration angepasst werden. Dazu stehen zwei Wege zur Verfügung.    

Als System Property 

Die Offset Größe kann via System Property vorgeben werden. In diesem Beispiel wird das zu betrachtene Offset auf 1024 Zeichen gesetzt.  

java -Dcom.levigo.jadice.format.pdf.OffsetPDFFormat.offsetSize=1024 <<application_launcher_class>>

oder alternativ initial nach dem Start der Anwendung und vor dem ersten Ladevorgang

System.setProperty("com.levigo.jadice.format.pdf.OffsetPDFFormat.offsetSize", "1024");

Via OffsetPDFFormat

 Hier als Code Beispiel.

 for (Format f : FormatRegistry.getFormatInformation()) {
      if (f instanceof OffsetPDFFormat) {
        ((OffsetPDFFormat) f).setOffsetBufferSize(1024);
        break;
      }
  } 

Deaktivierung des OffsetPDFFormats

Ist die Funktion des OffsetPDFFormats nicht erwünscht, kann er deaktiviert werden. Dies geschieht in dem die Offset Größe auf 1 gesetzt wird. Dies kann sowohl als System Property oder OffsetPDFFormat vollzogen werden.