Für das Einlesen von Daten in die jadice® document platform stehen verschiedene Wege zur Verfügung.
Der Ladevorgang kann sowohl ein bereits bestehendes wie auch ein zu diesem Zweck
neu erstelltes jadice® Document befüllen. Zudem muß entschieden werden, ob ein
Ladevorgang synchron oder asynchron ablaufen soll. Synchron geladene Dokumente
stehen erst zur Verfügung, nachdem der gesamte Lesevorgang abgeschlossen ist. Das
Dokument ist dann vollständig in dem Sinn, dass alle angefragten Daten verfügbar
sind. Beim asynchronen Laden werden die Dokumentdaten im Hintergrund eingelesen. Es
wird daher zunächst ein unvollständiges Dokument zurückgegeben mit dem zwar bereits
gearbeitet werden kann, das aber durch den Lade-Thread noch verändert wird.
Ein erstelltes Dokument kann bereits in »unbefülltem« Zustand dem Viewer zur Ansicht übergeben werden. Dieser erkennt automatisch, wenn die erste Seite (beziehungsweise das erste Seitensegment in einer Seite) geladen wurde und zeigt die Inhalte bereits an, obwohl im Hintergrund der Ladevorgang noch nicht abgeschlossen sein muss. Dies ist insbesondere bei langsamen Netzwerkverbindungen und großen Dokumenten von Vorteil.
Für den eigentlichen Lesevorgang stehen zwei unterschiedliche APIs zur Verfügung: Die Reader API, die einen imperativen Ansatz verfolgt, sowie die Fluent Reader API, die konfigurationsbasiert arbeitet. Beide werden in den folgenden Abschnitten vorgestellt.
Die Reader API, rund um deren zentrale Klasse Reader,
bietet die klassische Programmierschnittstelle zum Einlesen von Dokumentdaten in
jadice® Dokumente. Instanzen von Reader können über den parameterlosen
Konstruktor erzeugt werden. Sie bieten die Möglichkeit, Lesevorgänge zu
konfigurieren und zu starten.
Grundsätzlich gilt, dass jeweils ein logisch zusammengehöriger Lesevorgang auf
einer dedizierten Instanz von Reader durchgeführt werden sollte. Als logisch
zusammengehörig wird in diesem Fall ein Lesevorgang bezeichnet, der alle
Datenströme umfasst, die notwendig sind um das gewünschte Dokument vollständig
einzulesen. Dies kann beispielsweise die Datenströme für Seiteninhalte und
Annotationen umfassen.[12]
Der Programmieransatz zur Verwendung der Reader API folgt
dem imperativen Programmierparadigma. Einer Instanz von Reader werden
aufeinanderfolgend Anweisungen erteilt, die entweder interne Statusänderungen
oder einzelne (Teil-)Lesevorgänge zur Folge haben. Auf diese Weise wird ein
jadice®-Dokument nach und nach mit Inhalten befüllt.
Der Reader bietet verschiedene read(…)-Methoden, die
auf unterschiedliche Weisen Datenströme entgegennehmen und einlesen. Die
Lesevorgänge erfolgen jeweils mit den zum Zeitpunkt des Methodenaufrufs
vorliegenden Einstellungen des Readers. Typischerweise sieht der Gesamtablauf
daher so aus, dass abwechselnd Einstellungen auf dem Reader getroffen werden
und darauf basierend Streams eingelesen werden.
Unter anderem stehen folgende Einstellungen auf dem Reader zur Verfügung:
Dokument in das gelesen werden soll. Ist kein Dokument gesetzt, so wird vor dem Lesevorgang ein leeres Dokument erzeugt.
Zielposition (Seitenzahl) der Seite im Dokument. Diese Einstellung wird target index genannt und durch den Reader automatisch inkrementiert falls ein mehrseitiges Dokument aus einem Datenstrom gelesen wird. Zur Vereinfachung existieren zwei Konstanten, die festlegen, dass neue Seiten stets vor der ersten oder nach der letzten vorhandenen Seite eingefügt werden sollen.
LayerMapping das bestimmt, in welche Seitenebene die erzeugten Seitensegmente abgelegt werden sollen.
Dokumentformat, das für den Lesevorgang verwendet werden soll.
Sämtliche Methoden der Klasse Reader arbeiten synchron, sodass mit der
Rückkehr aus dem Methodenaufruf der gesamte Arbeitsschritt abgeschlossen ist.
Ist Nebenläufigkeit gewünscht, wird dies typischerweise realisiert indem die
gesamte Arbeit mit einem Reader-Objekt – also ein logisch zusammengehöriger
Lesevorgang – in eine Instanz von Runnable verpackt und
auf einem eigenen Thread ausgeführt wird.
Häufig (und besonders bei asynchroner Verwendung) besteht in einzelnen
Programmteilen Interesse daran, Informationen über den Fortschritt eines
Dokument-Lesevorgangs zu erhalten. Zu diesem Zweck bietet der Reader die
Möglichkeit, Instanzen von ReaderListener zu registrieren, die über
Änderungen informiert werden.[13]
Naturgemäß arbeiten Instanzen von Reader eng mit den Dokumenten zusammen,
in denen sie gelesene Daten ablegen. Aus diesem Grund wird durch Lesevorgänge
automatisch der Dokumentstatus der aktuell gesetzten Instanz von Document
geändert. Konkret wird bei jedem Aufruf einer
read(…)-Methode der Dokumentstatus auf
Document.BasicState.LOADING gesetzt – falls dieser
Status nicht sowieso schon gesetzt ist. Ist das Lesen eines einzelnen
Datenstroms abgeschlossen, bleibt der Status weiterhin gesetzt. Da der Reader
keine Information darüber besitzt, wann sämtliche logisch zusammengehörenden
Streams eingelesen wurden, ist es Aufgabe des Integrators zum geeigneten
Zeitpunkt das Dokument in den Status
Document.BasicState.READY zu versetzen.[14]
Um die generell empfohlene Vorgehensweise der Verwendung einer dedizierten
Instanz von Reader pro logisch zusammengehörendem Lesevorgang möglichst
einfach zu gestalten, bietet die Klasse eine Komfort-Methode an, um den
Abschluss des Lesevorgangs zu markieren. Es handelt sich um die Methode
complete(). Diese bringt das Dokument, in welches die
Daten gelesen wurden, in den Dokumentstatus
Document.BasicState.READY und benachrichtigt alle
registrierten ReaderListener darüber, dass der logisch zusammengehörende
Lesevorgang abgeschlossen ist. Ein Reader, auf dem die Methode
complete() aufgerufen wurde, kann danach nicht mehr für
weitere Lesevorgänge genutzt werden.
Hinweis: Soll mit einem Dokument bereits während des Ladevorgangs interagiert
werden, sollten notwendige Permissions frühestmöglich gesetzt werden. Dies
kann bereits vor dem Lesevorgang erfolgen da Permissions nur für
User-Interaktionen gelten.
Dieser Abschnitt ist noch in Bearbeitung. Sobald die Änderungen vollständig sind, finden Sie eine aktualisierte Version online unter http://support.levigo.de/products/jadice/documentplatform/5.0/index.html .
Bis dieser Abschnitt zur Verfügung steht, finden sich die relevanten Informationen auch in der New and Noteworthy Übersicht unter „Die Fluent Reader API“.
[12] Die Vorgabe, zusammengehörige Datenströme mit derselben Instanz von
Reader zu lesen, ist besonders für den Umgang mit Annotationen
wichtig. Diese können unter Umständen nicht auf der korrekten Seite
positioniert werden falls Annotations-Datenströme mit einer unabhängigen
Reader-Instanz gelesen werden. Nähere Details sind abhängig vom
Annotations-Format und werden in der Annotations-Dokumentation (Annotations-Dokumentation) gegeben.
[13] Details dazu unter „ReaderListener“
[14] Dieser Status sollte unbedingt gesetzt werden, da manche
jadice®-Komponenten ihre Arbeit nur aufnehmen können, wenn das zugeordnete
Dokument als READY markiert ist.
