biz.c24.io.api.presentation
Class BinarySource

java.lang.Object
  extended by biz.c24.io.api.presentation.Source
      extended by biz.c24.io.api.presentation.BinarySource
All Implemented Interfaces:
Serializable, Cloneable

public class BinarySource
extends Source

A source for generating data objects from a string formatted with the default presentation properties of a data type hierarchy.

This source attempts to use the presentation properties such as initiators, terminators, delimiters and pad characters defined in the source data model (.dod) file to parse the data. Therefore if this source is used to parse an instance of a data model imported from a schema or the like the parse will fail since the underlying model will have no such syntax cahracters present.

A common usage of this class would be:

 FileInputStream in = new FileInputStream("myfile.csv"); // note: stream clean up code has been ommited for clarity
 BinarySource src = new BinarySource(in);
 ComplexDataObject myObj = src.readObject(myElement); // where my element is the element you are expecting to parse
 

The lookAhead and lookBehind values are used to control how many characters ahead or behind the current offset the parser is allowed to look whilst attempting to locate the end of the current field or rollback an invalid parse. They therefore also respectivley control how much new data is read from the stream and how much is flushed from the buffer. Setting their values too low can result in some long fields failing to parse and / or the stream being queried too often for too small an amount of data. Setting their values too high can cause a drastic reduction in performance when parsing certain data structures since a larger amount of data requires processing to determine the start or end of a field. The default value of these variables is 1024 which is a compromise between being able to parse fields up to (approximately) 1024 characters long, reading an optimum amount of data from the stream on each query and not keeping too much data in memory at any one time.

Note that this implementation is not synchronized. If multiple threads use an instance concurrently, it must be synchronized externally.

See Also:
Source, Serialized Form

Constructor Summary
BinarySource()
          Constructs a new instance.
BinarySource(BinarySource clone)
          Constructs a new instance cloned from clone.
 
Method Summary
 Object clone()
           
 int getLookAhead()
          Returns the maximum number of characters to look ahead.
 int getLookBehind()
          Returns the maximum number of characters to look behind.
 boolean isEndOfDataRequired()
          Returns whether the stream / reader must be emptied for the read to succeed.
 void readObject(ComplexDataObject context)
          Reads an object from the the reader or input stream that has been set (optional operation).
 ComplexDataObject readObject(Element element)
          Reads an object from the the reader or input stream that has been set.
 boolean ready()
          Tests whether the underlying stream or reader contains more data waiting to be parsed.
 void setEndOfDataRequired(boolean required)
          Sets whether the stream / reader must be emptied for the read to succeed.
 void setInputStream(InputStream stream, URI systemId)
          Sets the input stream and system ID (optional operation).
 void setLookAhead(int lookAhead)
          Sets the maximum number of characters to look ahead.
 void setLookBehind(int lookBehind)
          Sets the maximum number of characters to look behind.
 void setReader(Reader reader)
          Sets the reader (optional operation).
 
Methods inherited from class biz.c24.io.api.presentation.Source
checkInit, getEncoding, getInputStream, getMarkableInputStream, getParseListener, getReader, getSystemId, reader, setEncoding, setInputStream, setParseListener, setReader, setSystemId, stream
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BinarySource

public BinarySource()
Constructs a new instance.


BinarySource

public BinarySource(BinarySource clone)
Constructs a new instance cloned from clone.

Parameters:
clone - The instance to clone.
Method Detail

ready

public boolean ready()
Description copied from class: Source
Tests whether the underlying stream or reader contains more data waiting to be parsed.
This method should be called in preference to Reader.ready() and InputStream.available() since it may need to take into account data which has been buffered by the Source implementation.

Overrides:
ready in class Source
Returns:
Whether there is unparsed data available.

isEndOfDataRequired

public boolean isEndOfDataRequired()
Returns whether the stream / reader must be emptied for the read to succeed.

Returns:
Whether an end of data marker is required in the stream / reader.

getLookAhead

public int getLookAhead()
Returns the maximum number of characters to look ahead. This parameter controls the maximum buffer size beyond the current offset.

Returns:
The look ahead value.

setLookAhead

public void setLookAhead(int lookAhead)
Sets the maximum number of characters to look ahead.

Parameters:
lookAhead - The new look ahead value.

getLookBehind

public int getLookBehind()
Returns the maximum number of characters to look behind. This paraemter controls the maximum buffer size upto the current offset.

Returns:
The look behind value.

setLookBehind

public void setLookBehind(int lookBehind)
Sets the maximum number of characters to look behind.

Parameters:
lookBehind - The new look behind value.

setEndOfDataRequired

public void setEndOfDataRequired(boolean required)
Sets whether the stream / reader must be emptied for the read to succeed. This parameter should be set to false (the default) if the readObject method is to be called more than once on the same stream / reader or if the calling code is not concerend about additional data such as blank lines. Set this parameter to true if you are expecting the stream / reader to contain one and only one data instance.

Parameters:
required - Whether an end of data marker is required in the stream / reader.

setInputStream

public void setInputStream(InputStream stream,
                           URI systemId)
Description copied from class: Source
Sets the input stream and system ID (optional operation).

Overrides:
setInputStream in class Source
Parameters:
stream - The new value.
systemId - The system ID identifying the stream.

setReader

public void setReader(Reader reader)
Description copied from class: Source
Sets the reader (optional operation). This method will also clear the system ID.

Overrides:
setReader in class Source
Parameters:
reader - The new value.

readObject

public ComplexDataObject readObject(Element element)
                             throws IOException
Description copied from class: Source
Reads an object from the the reader or input stream that has been set.

Specified by:
readObject in class Source
Parameters:
element - The element declaration to which the input data is expected to adhere.
Returns:
The newly created object.
Throws:
IOException - If the complete object could not be read for any reason.

readObject

public void readObject(ComplexDataObject context)
                throws IOException
Description copied from class: Source
Reads an object from the the reader or input stream that has been set (optional operation).

Specified by:
readObject in class Source
Parameters:
context - The object into which the input data should be parsed.
Throws:
IOException - If the complete object could not be read for any reason.

clone

public Object clone()
Specified by:
clone in class Source


C24 Technologies © 2002-2012: All Rights Reserved.