Die Reader API

Die Reader API bietet die Möglichkeit Datenströme in den unterstützen Formaten zu laden. Daraus resultiert eine geladene com.levigo.jadice.document.Document instanz.

Grundlegendes

Ein Reader wird mittels einfacher Instantiierung erstellt. Das resultierende Dokument wird durch aufeinanderfolgende Aufrufe der Methode Reader.read(...) aufgebaut. Abschließend muss zwingend der Ladevorgang als abgeschlossen markiert werden. Dies geschieht mittels der Methode Reader.complete()

// Zugriff auf die Dokumentdaten
InputStream is1 = //...
InputStream is2 = //...
InputStream is3 = //...
 
Reader reader = new Reader();
 
// laden der Dokumentdaten
reader.read(is1);
reader.read(is2);
reader.read(is3);
 
// abschließen des Ladevorgangs
reader.complete();
 
// erfragen des geladenen Dokuments
Document doc = reader.getDocument();

In diesem Beispiel werden drei Datenströme nacheinander geladen. Die daraus resultierenden Seiten werden dem Dokument angehängt.

Verwendung eines Providers

Möchte man die Logik für den Zugriff auf die Dokument-Datenströme kapseln, kann dies mittels einer Provider Implementation geschehen. Eine Implementation muss das Interface Provider<InputStream, IOException> implementieren.

import java.io.IOException;
import java.io.InputStream;
import com.levigo.util.base.Provider;

public final class ArchiveStreamProvider implements Provider<InputStream, IOException> {


	@Override
	public SeekableInputStream get() throws IOException {
		// Zugriff auf die Dokumentdaten
	}
}

Sollten es möglich sein eine SeekableInputStream Implementation direkt zurückzugeben, so sollte dies auch getan werden. Erhält der Reader "nur" einen InputStream, wird dieser mit einer SeekableInputStream Implementation gewrappt.

Laden auf verschiedene Ebenen

Das jadice Dokumentenmodell unterstütz die Verwendung mehrerer Ebenen. Das Dokumentenmodell kann hierbei wie folgt visualisiert werden:

Das Dokumentenmodell wird detailliert beschrieben unter: http://support.levigo.de/products/jadice/documentplatform/current/german/content/bk02ch03s01.html

Jedes Format der jadice Document Platform gibt beim Ladevorgang eine Empfehlung ab, auf welchen Layer ein geladenes PageSegment gelegt werden soll. Dies ist typischerweise DocumentLayer.DEFAULT, bei den Annotations-Formaten wird DocumentLayer.ANNOTATION vorgeschlagen. Soll der Inhalt jedoch gezielt auf einen anderen Layer gelegt werden, so muss hierfür ein entsprechendes Layer-Mapping angegeben werden. Dieses übersetzt dann den Vorschlag des Formats in die gewünschte Ziel-Ebene.

Hierzu folgendes Beispiel. Ein Dokument soll aus zwei Dokument-Datenströmen konstruiert werden:

• isBG: Der Seitenhintergrund
• isDoc: Der Seiteninhalt

InputStream isBG = //...
InputStream isDoc = //...
 
Reader reader = new Reader();
// erstellen eines Layer-Mappings, damit der Inhalt in den Seitenhintergrund kommt.
Map<DocumentLayer, DocumentLayer> layerMapping = new HashMap<DocumentLayer, DocumentLayer>();
layerMapping.put(DocumentLayer.DEFAULT, DocumentLayer.BACKGROUND);
reader.setLayerMapping(layerMapping);
// laden der Hintergrundseite(n)
reader.read(isBG);
 
// laden des Vordergrunds. Hierbei muss der Zielseiten-Index auf 0 
// gesetzt werden, und das Layer-Mapping entfernt werden.
reader.setTargetIndex(0);
reader.setLayerMapping(null);
reader.read(isDoc);
 
// Abschliessen des Ladevorgangs (wichtig!)
reader.complete();

Angeben des Formats für den Ladevorgang

Mache Formate können nicht über eine automatische Formaterkennung erkannt werden. Ein Beispiel sind hierbei die verschiedenen Annotationsformate. In diesem Fall muss das Format für den Ladevorgang explizit angegeben werden.

InputStream isDoc = //...
InputStream isAnno = //...


Reader reader = new Reader();
// laden des Dokuments
reader.read(isDoc);


// laden der Annotationen, mit explizit angegebenem Format
reader.setTargetIndex(0);
reader.setFormat(Jadice.create(JadiceAnnotationFormat.class));
reader.read(isAnno);


// Abschliessen des Ladevorgangs (wichtig!)
reader.complete(); 

Konfiguration des Ladevorgangs (am Beispiel Text-Dateien)

Manche Formate erlauben es eine Konfiguration des Ladevorgangs vorzunehmen. Ein Beispiel hierfür sind Textdateien, bei denen für den Ladevorgang auch ein entsprechendes Encoding mit angegeben werden muss.

InputStream isTxt = //...
 
Reader reader = new Reader();
 
DefaultReaderControls controls = new DefaultReaderControls();


// Erfragen der TextReaderSettings und Parametrisierung mit Charset, 
// Zeichen pro Zeile und Zeilen pro Seite
TextReaderSettings trs = controls.getSettings(TextReaderSettings.class);
trs.setCharset(Charset.forName("UTF-8"));
trs.setCharsPerLine(20);
trs.setLinesPerPage(40);
reader.setReaderControls(controls);


// laden des Dokuments, hier wird das TextFormat explizit gesetzt, welches die genannten Parameter verwendet
reader.setFormat(Jadice.create(TextFormat.class));
reader.read(isTxt);
 
// Abschliessen des Ladevorgangs (wichtig!)
reader.complete();

Die Konfiguration kann einmalig für alle Ladevorgänge konfiguriert werden. Sollten die entsprechenden Einstellungen für einen Ladevorang nicht benötigt werden (z.B. werden TextReaderSettings spezifiziert, aber ein PDF-Dokument geladen - der PDF Ladevorgang wird nicht beeinflusst).