com.levigo.jadice.document.read

Class Reader

java.lang.Object

com.levigo.jadice.document.read.Reader

All Implemented Interfaces:

MetadataProvider, PropertiesProvider

public class Reader
extends Object
implements PropertiesProvider, MetadataProvider

Reads data from input sources into instances of Document. Instances of this class must be used on one single thread exclusively. They must not be used concurrently.

Reading data

Instances of this class are used to carry out read processes. A read process consists of one or more read calls, that is, invocations of the various read(…) Methods provided by this class. A read process which includes all the data for one logical document (which could consist of several data streams) is called a logically coherent read process.

It is common practice to read multiple data streams using one Reader instance, for example multiple single-page data streams and annotations that form one logical document. It is highly recommended to use a separate Reader instance for every logically coherent read process.

The read process performed by an instance of Reader is uniquely identified by the an identification String called Read ID.

Listening for progress

Using addReaderListener(ReaderListener), interested parties can register themselves to receive information on state changes.

Cancelation

Using getCanceler(), an object can be obtained which allows to issue requests for the cancelation of currently-running read operations. If the FormatReader in use supports cancelation, the format read process will be stopped at an appropriate time. Once cancelation has been requested, any subsequent calls to one of the read(...) methods will have no effect.

Completion

Once all data for a Document is read, users of this class will typically call complete(). This will inform registered listeners.

Subclassing

Although this class is not final, it is not intended for subclassing in integrations. Internal details may change in any release and without prior notice.

Field Summary

Fields

Modifier and Type	Field and Description
static int	AFTER_LAST_PAGE Constant to specify that new pages should be added after the target Document's currently last page.
static int	BEFORE_FIRST_PAGE Constant to specify that new pages should be added before the target Document's first page.
protected boolean	complete

Constructor Summary

Constructors

Constructor and Description
Reader() Create a new instance with a default, unique Read ID.
Reader(String readID) Create a new instance with the given Read ID

Method Summary

Modifier and Type	Method and Description
void	addReaderListener(ReaderListener listener) Add the given ReaderListener to the list of registered listeners.
void	clearSettings(Class<? extends ReaderSettings> c) Restore settings of a given kind to their default values.
void	complete() Signal to the reader that the current read process is complete.
protected com.levigo.jadice.document.internal.read.ReadTask	createTask(Provider<? extends InputStream,IOException> streamProvider)
Canceler	getCanceler() Returns an object which allows to request cancelation of running read processes.
Document	getDocument() Retrieve the Document instance to which subsequent read calls add their resulting document data (PageSegments etc.)
Format	getFormat() Retrieve the Format instance which governs how subsequent read calls interpret the data they read.
Map<DocumentLayer,DocumentLayer>	getLayerMapping() Retrieve the map which specifies where PageSegments resulting from subsequent read calls should be placed within the virtual layers of a Page.
Metadata	getMetadata() Returns the metadata, if any, to be used by subsequent read calls.
Map<String,Object>	getProperties() Return a map of user properties which can be used during the read process, in particular by FormatReaders.
String	getReadID() Retrieve an identifier for the read process that is performed using this Reader instance.
<S extends ReaderSettings> S	getSettings(Class<S> c) Retrieve settings of a given kind.
int	getStreamIndex() Return the index of the last stream read by this reader.
int	getTargetIndex() Get the target page index to be used for page segments read by subsequent read calls
protected void	handleTask(com.levigo.jadice.document.internal.read.ReadTask readTask) Not intended to be overridden in integrations! May change at any time and without prior notice.
boolean	read(File file) Transforms data from the given source into a jadice document model representation.
boolean	read(InputStream is) Transforms data from the given source into a jadice document model representation.
boolean	read(Provider<? extends InputStream,IOException> streamProvider) Transforms data from the given source into a jadice document model representation.
boolean	read(URL url) Transforms data from the given source into a jadice document model representation.
void	removeReaderListener(ReaderListener listener) Remove the given ReaderListener from the list of registered listeners.
void	setDocument(Document document) Replace this instance's target document to be used by subsequent read calls.
void	setFormat(Format format) Specify the Format instance which governs how subsequent read calls interpret the data they read.
void	setLayerMapping(Map<DocumentLayer,DocumentLayer> layerMapping) Replace the entire layer mapping to be used by subsequent read calls.
void	setMetadata(Metadata metadata) Replace the entire metadata to be used by subsequent read calls.
void	setReaderControls(ReaderControls rc) Replace the existing ReaderControls instance with all its ReaderSettings.
void	setTargetIndex(int targetIndex) Set the target page index to be used for page segments read by subsequent read calls

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AFTER_LAST_PAGE

public static final int AFTER_LAST_PAGE

Constant to specify that new pages should be added after the target Document's currently last page.

See Also:

Constant Field Values

BEFORE_FIRST_PAGE

public static final int BEFORE_FIRST_PAGE

Constant to specify that new pages should be added before the target Document's first page.

See Also:

Constant Field Values

complete

protected boolean complete

Constructor Detail

Reader

public Reader()

Create a new instance with a default, unique Read ID.

Reader

public Reader(String readID)

Create a new instance with the given Read ID

Parameters:

readID - A unique ID String which is used to identify the read process performed by the newly created instance. The ID must be unique at run-time and with respect to all other Read IDs. If this parameter is null, a default ID will be generated.

Method Detail

clearSettings

public void clearSettings(Class<? extends ReaderSettings> c)

Restore settings of a given kind to their default values.

Parameters:

c - the kind of settings to be restored

See Also:

ProcessingControls.clearSettings(Class)

getSettings

public <S extends ReaderSettings> S getSettings(Class<S> c)

Retrieve settings of a given kind. These settings are in effect for subsequent read calls, until changed or cleared.

Type Parameters:

S - the kind of settings this method call deals with

Parameters:

c - The kind of settings to be retrieved

Returns:

settings of the given kind

See Also:

ProcessingControls.getSettings(Class)

addReaderListener

public void addReaderListener(ReaderListener listener)

Add the given ReaderListener to the list of registered listeners.

Parameters:

listener - the listener to add

removeReaderListener

public void removeReaderListener(ReaderListener listener)

Remove the given ReaderListener from the list of registered listeners.

Parameters:

listener - the listener to remove

read

public boolean read(URL url)
             throws JadiceException,
                    IOException,
                    IllegalArgumentException

Transforms data from the given source into a jadice document model representation. Once cancelation has been requested, calls to this method will no longer have any effect.

Parameters:

url - the source to be read.

Returns:

true if the read was fully performed (either successfully or with errors); false if cancelation was requested

Throws:

JadiceException

IOException - if an I/O error occurs

IllegalArgumentException - if the given URL is null

IllegalStateException - it an attempt is made to read with an instance that has already been marked as complete().

read

public boolean read(File file)
             throws JadiceException,
                    IOException

Transforms data from the given source into a jadice document model representation. Once cancelation has been requested, calls to this method will no longer have any effect.

Parameters:

file - the source to read from

Returns:

true if the read was fully performed (either successfully or with errors); false if cancelation was requested

Throws:

JadiceException

IOException

IllegalStateException - it an attempt is made to read with an instance that has already been marked as complete().

read

public boolean read(InputStream is)
             throws JadiceException,
                    IOException

Transforms data from the given source into a jadice document model representation. Once cancelation has been requested, calls to this method will no longer have any effect.

Parameters:

is - the source to read from

Returns:

true if the read was fully performed (either successfully or with errors); false if cancelation was requested

Throws:

JadiceException

IOException

IllegalStateException - it an attempt is made to read with an instance that has already been marked as complete().

read

public boolean read(Provider<? extends InputStream,IOException> streamProvider)
             throws JadiceException,
                    IOException

Transforms data from the given source into a jadice document model representation. Once cancelation has been requested, calls to this method will no longer have any effect.

Parameters:

streamProvider - supplies the source to read from

Returns:

true if the read was fully performed (either successfully or with errors); false if cancelation was requested

Throws:

JadiceException

IOException

IllegalStateException - it an attempt is made to read with an instance that has already been marked as complete().

createTask

protected com.levigo.jadice.document.internal.read.ReadTask createTask(Provider<? extends InputStream,IOException> streamProvider)

handleTask

protected void handleTask(com.levigo.jadice.document.internal.read.ReadTask readTask)
                   throws IOException,
                          JadiceException

Not intended to be overridden in integrations! May change at any time and without prior notice.

Throws:

IOException

JadiceException

getDocument

public Document getDocument()

Retrieve the Document instance to which subsequent read calls add their resulting document data (PageSegments etc.)

Returns:

this instance's target document

setDocument

public void setDocument(Document document)

Replace this instance's target document to be used by subsequent read calls.

Parameters:

document - the target document to be used from now on

See Also:

getDocument()

getTargetIndex

public int getTargetIndex()

Get the target page index to be used for page segments read by subsequent read calls

Returns:

the zero-based target index or one of the special cases BEFORE_FIRST_PAGE and AFTER_LAST_PAGE.

See Also:

BEFORE_FIRST_PAGE, AFTER_LAST_PAGE

setTargetIndex

public void setTargetIndex(int targetIndex)

Set the target page index to be used for page segments read by subsequent read calls

Parameters:

targetIndex - the zero-based target index or one of the special cases BEFORE_FIRST_PAGE and AFTER_LAST_PAGE.

See Also:

BEFORE_FIRST_PAGE, AFTER_LAST_PAGE

getMetadata

public Metadata getMetadata()

Returns the metadata, if any, to be used by subsequent read calls.

Specified by:

getMetadata in interface MetadataProvider

Returns:

the metadata for this instance and/or the stream(s) to be read, or null

setMetadata

public void setMetadata(Metadata metadata)

Replace the entire metadata to be used by subsequent read calls.

Parameters:

metadata - the metadata for this instance and/or the stream(s) to be read. May be null.

getProperties

public Map<String,Object> getProperties()

Return a map of user properties which can be used during the read process, in particular by FormatReaders. Whether or not any of these properties end up in the resulting Document's user properties depends on individual FormatReader implementations.

Typically, integrations will not need to add properties to this map.

Specified by:

getProperties in interface PropertiesProvider

Returns:

the Reader's map of user properties

getLayerMapping

public Map<DocumentLayer,DocumentLayer> getLayerMapping()

Retrieve the map which specifies where PageSegments resulting from subsequent read calls should be placed within the virtual layers of a Page. Most formats would typically place the PageSegments they read on the default layer (DocumentLayer.DEFAULT); annotations typically use the annotations layer (DocumentLayer.ANNOTATIONS. Using this map, PageSegments can be re-routed to another (possibly integration-specific) layer.

Returns:

the mapping to be applied during subsequent read calls

setLayerMapping

public void setLayerMapping(Map<DocumentLayer,DocumentLayer> layerMapping)

Replace the entire layer mapping to be used by subsequent read calls.

Parameters:

layerMapping - the mapping to be applied during subsequent read calls

See Also:

getLayerMapping()

getFormat

public Format getFormat()

Retrieve the Format instance which governs how subsequent read calls interpret the data they read.

Returns:

the Format to be used by subsequent read calls, or null in case of auto-detection.

setFormat

public void setFormat(Format format)

Specify the Format instance which governs how subsequent read calls interpret the data they read.

Parameters:

format - the Format to be used by subsequent read calls. Pass null to request format auto-detection.

setReaderControls

public void setReaderControls(ReaderControls rc)

Replace the existing ReaderControls instance with all its ReaderSettings. Passing a null-argument resets the internal controls instance to its initial state.

getReadID

public String getReadID()

Retrieve an identifier for the read process that is performed using this Reader instance.

Returns:

identifier for this read process

getStreamIndex

public int getStreamIndex()

Return the index of the last stream read by this reader. A new, unused reader will return 0. After the first read call, this method will return 1.

Returns:

last read call's stream index

complete

public void complete()

Signal to the reader that the current read process is complete. This information is propagated to the currently active ReaderListeners. Depending on whether or not the read process was canceled, the event's ReaderListener.ReaderEvent.Type is either ReaderListener.ReaderEvent.Type.READ_CANCELED or ReaderListener.ReaderEvent.Type.READ_COMPLETED. Furthermore, on the Document retrieved by a call to getDocument(), the document state is updated if it is still set to Document.BasicState.LOADING. Depending on whether or not the read process was canceled, the new state is Document.BasicState.UNKNOWN or Document.BasicState.READY.

After calling this method, further calls to any of the read(...) methods will result in IllegalStateExceptions.

Using this method is encouraged, but not mandatory.

getCanceler

public Canceler getCanceler()

Returns an object which allows to request cancelation of running read processes. While this class is intended for use on a single thread, the Canceler returned from this method is thread-safe. It may be passed on to other threads and its methods may be invoked on other threads.

Returns:

an object which allows to request read process cancelation