org.openexi.sax
Class Transmogrifier

java.lang.Object
  org.openexi.sax.Transmogrifier

public final class Transmogrifier
extends java.lang.Object

The Transmogrifier converts an XML stream to an EXI stream.

Constructor Summary

Transmogrifier()
Create an instance of the Transmogrifier with a default SAX parser.

Transmogrifier(javax.xml.parsers.SAXParserFactory saxParserFactory)
Create an instance of the Transmogrifier, specifying the SAXParserFactory from which to create the SAX parser.

Method Summary

void	encode(org.xml.sax.InputSource is) Parses XML input source and converts it to an EXI stream.
GrammarCache	getGrammarCache() Returns the GrammarCache that was previously set.
SAXTransmogrifier	getSAXTransmogrifier() Returns the SAXTransmogrifier, which implements both the ContentHandler and LexicalHandler.
void	setAlignmentType(AlignmentType alignmentType) Set the bit alignment style for the encoded EXI stream.
void	setBlockSize(int blockSize) Set the size, in number of values, of the information that will be processed as a chunk of the entire XML stream.
void	setDatatypeRepresentationMap(QName[] dtrm, int n_bindings) Set a datatype representation map (DTRM).
void	setEntityResolver(org.xml.sax.EntityResolver entityResolver) Set an external SAX entity resolver.
void	setFragment(boolean isFragment) Set to true if the XML input stream is an XML fragment (a non-compliant XML document with multiple root elements).
void	setGrammarCache(GrammarCache grammarCache) Set the GrammarCache used in transmogrifying XML data to EXI.
void	setGrammarCache(GrammarCache grammarCache, org.openexi.proc.common.SchemaId schemaId) Set the GrammarCache to be used in encoding XML streams into EXI streams by the transmogrifier.
void	setOutputCookie(boolean outputCookie) Tells the encoder whether to or not to start the stream by adding an EXI cookie.
void	setOutputOptions(HeaderOptionsOutputType outputOptions) Set the header output options.
void	setOutputStream(java.io.OutputStream ostream) Set an output stream to which encoded streams are written.
void	setPreserveLexicalValues(boolean preserveLexicalValues) Set to true to preserve the original string values from the XML stream.
void	setPreserveWhitespaces(boolean preserveWhitespaces) Set to true to preserve whitespace (for example, spaces, tabs, and line breaks) in the encoded EXI stream.
void	setResolveExternalGeneralEntities(boolean resolveExternalGeneralEntities) Change the way a Transmogrifier handles external general entities.
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

Transmogrifier

public Transmogrifier()
               throws org.openexi.sax.TransmogrifierRuntimeException

Create an instance of the Transmogrifier with a default SAX parser.

Throws:

TransmogrifierException

org.openexi.sax.TransmogrifierRuntimeException

Transmogrifier

public Transmogrifier(javax.xml.parsers.SAXParserFactory saxParserFactory)
               throws org.openexi.sax.TransmogrifierRuntimeException

Create an instance of the Transmogrifier, specifying the SAXParserFactory from which to create the SAX parser.

Parameters:

saxParserFactory -

Throws:

TransmogrifierException

org.openexi.sax.TransmogrifierRuntimeException

Method Detail

setResolveExternalGeneralEntities

public void setResolveExternalGeneralEntities(boolean resolveExternalGeneralEntities)
                                       throws TransmogrifierException

Change the way a Transmogrifier handles external general entities. When the value of resolveExternalGeneralEntities is set to true, a Transmogrifier will try to resolve external general entities. Otherwise, external general entities will not be resolved.

Parameters:

resolveExternalGeneralEntities -

Throws:

TransmogrifierException - Thrown when the underlying XMLReader does not support the specified behavior.

setOutputStream

public final void setOutputStream(java.io.OutputStream ostream)

Set an output stream to which encoded streams are written.

Parameters:

ostream - output stream

setAlignmentType

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

Set the bit alignment style for the encoded EXI stream.

Parameters:

alignmentType - AlignmentType. Default is bit-packed.

Throws:

org.openexi.proc.common.EXIOptionsException

setFragment

public final void setFragment(boolean isFragment)

Set to true if the XML input stream is an XML fragment (a non-compliant XML document with multiple root elements).

Parameters:

isFragment - true if the XML input stream is an XML fragment.

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 XML 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 XML stream. For example, a date string might be converted to a different format when interpreted by the Transmogrifier. 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

setGrammarCache

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

Set the GrammarCache used in transmogrifying XML data to EXI.

Parameters:

grammarCache - GrammarCache

Throws:

org.openexi.proc.common.EXIOptionsException

setGrammarCache

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

Set the GrammarCache to be used in encoding XML streams into EXI streams by the transmogrifier. The SchemaId contains the string that is written in the header when HeaderOptionsOutputType.all is set.

Parameters:

grammarCache - GrammarCache

schemaId -

Throws:

org.openexi.proc.common.EXIOptionsException

getGrammarCache

public final GrammarCache getGrammarCache()

Returns the GrammarCache that was previously set.

Returns:

a GrammarCache

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.
   transmogrifierInstance.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

setEntityResolver

public final void setEntityResolver(org.xml.sax.EntityResolver entityResolver)

Set an external SAX entity resolver.

Parameters:

entityResolver - EntityResolver

setOutputCookie

public final void setOutputCookie(boolean outputCookie)

Tells the encoder whether to or not to start the stream by adding an EXI cookie.

Parameters:

outputCookie - true to include the EXI cookie

setOutputOptions

public final void setOutputOptions(HeaderOptionsOutputType outputOptions)
                            throws org.openexi.proc.common.EXIOptionsException

Set the header output options. Choices are set using the HeaderOptionsOutputType enumeration. Options are all, lessSchemaID (that is, all values except for the SchemaId), or none.

Parameters:

outputOptions - HeaderOptionsOutputType

Throws:

org.openexi.proc.common.EXIOptionsException

setPreserveWhitespaces

public final void setPreserveWhitespaces(boolean preserveWhitespaces)

Set to true to preserve whitespace (for example, spaces, tabs, and line breaks) in the encoded EXI stream. By default, non-essential whitespace is removed from the encoded stream.

Parameters:

preserveWhitespaces - true to retain whitespace in the encoded EXI stream

encode

public void encode(org.xml.sax.InputSource is)
            throws TransmogrifierException,
                   java.io.IOException

Parses XML input source and converts it to an EXI stream.

Parameters:

is - XML input source

Throws:

TransmogrifierException

java.io.IOException

getSAXTransmogrifier

public SAXTransmogrifier getSAXTransmogrifier()

Returns the SAXTransmogrifier, which implements both the ContentHandler and LexicalHandler. SAX programmers can connect the SAXTransmogrifier to their favorite XML Parser to convert SAX events into an EXI stream.