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.    

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 zwar 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 der OffsetPDFReader?

Der OffsetPDFReader 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 einen eigenen OffsetPDFReader, kann das nicht auch der normale PDFReader machen?   

Als Multi-Format Anwendung unterstützt jadice sehr viele Formate. Beim Einlesen von Dokumentdaten schaut sich jadice zunächst die ersten Zeichen das Datenstroms an, um zu entscheiden, welcher spezialisierter Format Reader das weitere Einlesen des Dokuments übernimmt.

Der naheliegende Ansatz, einfach eine beliebige Anzahl führender Zeichen vor %PDF-<<Versionsnummer>> im bisherigen PDF Format zu akzeptieren, scheiterte. 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 handelt und welcher spezialisierte Reader den weiteren Lesevorgang übernehmen soll.
Um diese Fälle auszuschließen, reiht sich der OffsetPDFReader am Ende der Formaterkennung ein, nachdem alle anderen Formate die den Datenstrom nicht erkannt 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 findet 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 OffsetPDFReaders, 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 OffsetPDFReader kommt zum Zug, versucht er unabhängig eines möglicherweise gesetzen STRICT-Modus dennoch den Datenstrom zu lesen und ggf. 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 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 auszubremsen, ist die Anzahl der zu untersuchenden führenden Bytes im OffsetPDFReaders auf maximal 8192 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 begrenzt.  

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

oder alternativ

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 OffsetPDFReaders

Ist die Funktion des OffsetPDFReaders 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.