org.openexi.proc
Class EXIDecoder

java.lang.Object
  org.openexi.proc.EXIDecoder

public class EXIDecoder
extends java.lang.Object

EXIDecoder provides methods to configure and instantiate a Scanner object you can use to parse the contents of an EXI stream.

Constructor Summary

EXIDecoder()
Creates an instance of EXIDecoder with the default inflator buffer size of 8192 bytes.

EXIDecoder(int inflatorBufSize, boolean useThreadedInflater)
Creates an instance of EXIDecoder with the specified inflator buffer size.

Method Summary

Scanner	processHeader() This method reads and configures any header options present in the EXI stream, then returns a Scanner object you can use to parse the values from the EXI stream.
void	setAlignmentType(AlignmentType alignmentType) Set the bit alignment style of the stream to be decoded.
void	setBlockSize(int blockSize) Set the size, in number of values, of the information that will be processed as a chunk of the entire EXI stream.
void	setDatatypeRepresentationMap(QName[] dtrm, int n_bindings) Set a datatype representation map (DTRM).
void	setEnableBinaryData(boolean enable) Each binary value will be returned as in a EventDescription of EVENT_BLOB instead of EVENT_CH when enabled.
void	setFragment(boolean isFragment) Set whether the document is a fragment.
void	setGrammarCache(GrammarCache grammarCache) Set the GrammarCache used in decoding EXI streams.
void	setInitialBinaryDataBufferSize(int initialSize)
void	setInputStream(java.io.InputStream istream) Set an input stream from which the encoded stream is read.
void	setPreserveLexicalValues(boolean preserveLexicalValues) Set to true to preserve the original string values from the EXI stream.
void	setValueMaxLength(int valueMaxLength) Set the maximum length of a string that will be stored for reuse in the String Table.
void	setValuePartitionCapacity(int valuePartitionCapacity) Set the maximum number of values in the String Table.

Methods inherited from class java.lang.Object

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

Constructor Detail

EXIDecoder

public EXIDecoder()

Creates an instance of EXIDecoder with the default inflator buffer size of 8192 bytes. Buffer size is only used when the EXI stream is encoded with EXI compression.

EXIDecoder

public EXIDecoder(int inflatorBufSize,
                  boolean useThreadedInflater)

Creates an instance of EXIDecoder with the specified inflator buffer size. When dynamic memory is limited on the target device, reducing the buffer size can improve performance and avoid runtime errors. Buffer size is only used when the EXI stream is encoded with EXI compression.

Parameters:

inflatorBufSize - size of the buffer, in bytes.

useThreadedInflater - Inflater will be run in its own thread if true

Method Detail

setInputStream

public final void setInputStream(java.io.InputStream istream)

Set an input stream from which the encoded stream is read.

Parameters:

istream - InputSream to be read.

setAlignmentType

public final void setAlignmentType(AlignmentType alignmentType)
                            throws org.openexi.proc.common.EXIOptionsException

Set the bit alignment style of the stream to be decoded.

Parameters:

alignmentType - AlignmentType object

Throws:

org.openexi.proc.common.EXIOptionsException

setFragment

public final void setFragment(boolean isFragment)

Set whether the document is a fragment. Fragments are nonstandard XML documents with multiple root elements. Default is false.

Parameters:

isFragment - true if the stream is an XML fragment

setGrammarCache

public final void setGrammarCache(GrammarCache grammarCache)
                           throws org.openexi.proc.common.EXIOptionsException

Set the GrammarCache used in decoding EXI streams.

Parameters:

grammarCache - GrammarCache

Throws:

org.openexi.proc.common.EXIOptionsException

setBlockSize

public final void setBlockSize(int blockSize)
                        throws org.openexi.proc.common.EXIOptionsException

Set the size, in number of values, of the information that will be processed as a chunk of the entire EXI stream. Reducing the block size can improve performance for devices with limited dynamic memory. Default is 1,000,000 items (not 1MB, but 1,000,000 complete Attribute and Element values). Block size is only used when the EXI stream is encoded with EXI-compression.

Parameters:

blockSize - number of values in each processing block. Default is 1,000,000.

Throws:

org.openexi.proc.common.EXIOptionsException

setValueMaxLength

public final void setValueMaxLength(int valueMaxLength)

Set the maximum length of a string that will be stored for reuse in the String Table. By default, there is no maximum length. However, in data sets that have long, unique strings of information, you can improve performance by limiting the size to the length of strings that are more likely to appear more than once.

Parameters:

valueMaxLength - maximum length of entries in the String Table.

setValuePartitionCapacity

public final void setValuePartitionCapacity(int valuePartitionCapacity)

Set the maximum number of values in the String Table. By default, there is no limit. If the target device has limited dynamic memory, limiting the number of entries in the String Table can improve performance and reduce the likelihood that you will exceed memory capacity.

Parameters:

valuePartitionCapacity - maximum number of entries in the String Table

setPreserveLexicalValues

public final void setPreserveLexicalValues(boolean preserveLexicalValues)
                                    throws org.openexi.proc.common.EXIOptionsException

Set to true to preserve the original string values from the EXI stream. For example, a date string might be converted to a different format when interpreted by the EXIDecoder. Preserving the lexical values ensures that the identical strings are restored, and not just their logical values.

Parameters:

preserveLexicalValues - true to keep original strings intact

Throws:

org.openexi.proc.common.EXIOptionsException

setDatatypeRepresentationMap

public final void setDatatypeRepresentationMap(QName[] dtrm,
                                               int n_bindings)
                                        throws org.openexi.proc.common.EXIOptionsException

Set a datatype representation map (DTRM). The DTRM allows you to remap XMLSchema datatypes to EXI datatypes other than their default equivalents. The map is created using a sequence of Qualified Name pairs that identify a datatype definition in the XMLSchema namespace followed by the new corresponding datatype mapping in the EXI namespace.

For example, the following lines map the boolean datatype from XMLSchema to the integer datatype in EXI.

   QName q1 = new QName("xsd:boolean","http://www.w3.org/2001/XMLSchema");
   QName q2 = new QName("exi:integer","http://www.w3.org/2009/exi");
   QName[] dtrm = new QName[2];
   dtrm = {q1, q2}; // Each mapping requires 2 qualified names.
   decoderInstance.setDatatypeRepresentationMap(dtrm, 1); // The array, and the number of pairs (1).
 

Parameters:

dtrm - a sequence of pairs of datatype QName and datatype representation QName

n_bindings - the number of QName pairs

Throws:

org.openexi.proc.common.EXIOptionsException

setEnableBinaryData

public final void setEnableBinaryData(boolean enable)

Each binary value will be returned as in a EventDescription of EVENT_BLOB instead of EVENT_CH when enabled.

Parameters:

enable -

setInitialBinaryDataBufferSize

public final void setInitialBinaryDataBufferSize(int initialSize)

processHeader

public Scanner processHeader()
                      throws java.io.IOException,
                             org.openexi.proc.common.EXIOptionsException

This method reads and configures any header options present in the EXI stream, then returns a Scanner object you can use to parse the values from the EXI stream.

Returns:

Scanner parsable object with header options applied.

Throws:

java.io.IOException

org.openexi.proc.common.EXIOptionsException