org.xbis
Class XBISWriter

java.lang.Object
  org.xbis.XBISWriter

All Implemented Interfaces:

XBISConstants

Direct Known Subclasses:

XBISEventWriter

public abstract class XBISWriter

extends java.lang.Object

implements XBISConstants

XML Binary Information Set output handler. This writes a compact representation of the data in an XML document, with the advantages of reduced document size and lower processing overhead as compared to the standard text document representation.

This class provides basic output handling, but the driver methods for walking a document representation and writing the corresponding serial form must be implemented by a subclass specific to the model used. The generated serial form is independent of the original model, and may be read by the input handlers for models other than the one from which it was generated.

Version:

0.8

Author:

Dennis M. Sosnoski

Nested Class Summary

protected static class

XBISWriter.OutputNamespace Extended namespace information for output processing.

Field Summary

static int	DEFAULT_BUFFER_SIZE Default size of output buffer.
static int	INITIAL_NAMESPACE_COUNT Number of namespace declarations allowed for in default allocation.
static int	MINIMUM_BUFFER_SIZE Minimum size for output buffer.
static int	SHORT_STRING_LIMIT Limit for accessing String data a byte at a time.
static int	STRING_ARRAY_SIZE Size of String character buffer (must be larger than short limit, but less than one third of the buffer size).

Fields inherited from interface org.xbis.XBISConstants

ATTRIBUTE_HANDLE_MASK, ATTRIBUTE_NEWREF_FLAG, ATTRIBUTE_NOTEND_FLAG, ATTRIBUTE_VALUEREF_FLAG, DOM_SOURCE_ID, DOM4J_SOURCE_ID, ELEMENT_HANDLE_MASK, ELEMENT_HASATTRIBUTES_FLAG, ELEMENT_HASCHILDREN_FLAG, HEADER_VERSION_ID, JDOM_SOURCE_ID, NAME_LENGTH_MASK, NAME_NS_MASK, NAME_NS_SHIFT, NAMESPACEDECL_HANDLE_MASK, NO_NAMESPACE, NODE_ELEMENT_FLAG, NODE_NAMESPACEDECL_FLAG, NODE_PLAINTEXT_FLAG, NODE_TEXTREF_FLAG, NODE_TYPE_ATTRIBUTEDECL, NODE_TYPE_CDATA, NODE_TYPE_COMMENT, NODE_TYPE_DOCTYPE, NODE_TYPE_DOCUMENT, NODE_TYPE_ELEMENTDECL, NODE_TYPE_END, NODE_TYPE_EXTERNALENTITYDECL, NODE_TYPE_MASK, NODE_TYPE_NOTATION, NODE_TYPE_PI, NODE_TYPE_SKIPPEDENTITY, NODE_TYPE_UNPARSEDENTITY, NS_HANDLE_NONE, NS_HANDLE_XML, NSDEF_PRELENGTH_MASK, NSDEF_URIHANDLE_MASK, NSDEF_URIHANDLE_SHIFT, PLAINTEXT_LENGTH_MASK, SAX2_SOURCE_ID, TEXTREF_HANDLE_MASK, XML_NAMESPACE

Constructor Summary

XBISWriter(int size)
Constructor.

Method Summary

protected void	clearMark() Clear buffer mark.
protected void	clearReset() Clear reset state.
void	closeNamespaces(int count) Close some number of active namespace declarations.
protected abstract void	defineAttribute(java.lang.Object obj) Add attribute definition.
void	flush() Write buffer to output stream.
protected abstract int	getAttributeHandle(java.lang.Object obj) Get handle for attribute.
XBISWriter.OutputNamespace	getNamespace(java.lang.String prefix, java.lang.String uri) Get namespace declaration.
protected abstract void	initState() Initialize state information used during the serialization process.
protected boolean	isReset() Check reset state.
protected int	readMarked() Read marked byte.
void	reset() Reset state information used during the serialization process.
protected void	setMark() Set buffer mark for later access.
void	setSharedAttributes(int limit) Set shared attribute text parameter.
void	setSharedContent(int limit) Set shared content text limit.
protected void	setStream(java.io.OutputStream os, int id) Set output stream.
protected void	writeAttribute(java.lang.Object obj, java.lang.String value) Write attribute to stream.
protected void	writeByte(int value) Write byte to buffer.
protected void	writeChars(char[] buff, int offset, int length) Write string of characters to stream.
protected void	writeMarked(int value) Write marked byte.
protected void	writeNameDef(java.lang.String local, XBISWriter.OutputNamespace ns) Write name definition to stream.
void	writeNamespaceDecl(XBISWriter.OutputNamespace ns) Write namespace declaration to stream.
void	writeNamespaceDef(XBISWriter.OutputNamespace ns) Write namespace definition to stream.
protected void	writeQuickValue(int value, int initial, int mask) Write non-negative integer value with partial lead byte to stream.
protected void	writeString(java.lang.String text) Write String directly to stream.
protected void	writeStringChars(char[] buff, int offset, int length) Write character string directly to stream.
protected void	writeStringData(java.lang.String text) Write String data to stream.
protected void	writeText(char[] buff, int offset, int length) Write content text to stream.
protected void	writeText(java.lang.String text) Write content text to stream.
protected void	writeValue(int value) Write non-negative integer value to stream.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

Default size of output buffer.

See Also:

Constant Field Values

SHORT_STRING_LIMIT

public static final int SHORT_STRING_LIMIT

Limit for accessing String data a byte at a time.

See Also:

Constant Field Values

STRING_ARRAY_SIZE

public static final int STRING_ARRAY_SIZE

Size of String character buffer (must be larger than short limit, but less than one third of the buffer size).

See Also:

Constant Field Values

MINIMUM_BUFFER_SIZE

public static final int MINIMUM_BUFFER_SIZE

Minimum size for output buffer.

See Also:

Constant Field Values

INITIAL_NAMESPACE_COUNT

public static final int INITIAL_NAMESPACE_COUNT

Number of namespace declarations allowed for in default allocation.

See Also:

Constant Field Values

Constructor Detail

XBISWriter

public XBISWriter(int size)

Constructor. Allocates and initializes instances of the data tables used for storing state information during the serialization process.

Parameters:

size - output buffer size

Method Detail

setStream

protected final void setStream(java.io.OutputStream os,
                               int id)
                        throws java.io.IOException

Set output stream. This first resets the state to clear any data intended for another stream, then sets the new output stream and writes the XML Serial Format header information.

Parameters:

os - serialization output stream

id - output adapter identifier

Throws:

java.io.IOException - on error writing to stream

setSharedContent

public final void setSharedContent(int limit)

Set shared content text limit. This method enables or disables content text sharing, with associated control information. If enabled, text content Strings of no more than the limit length are assigned handles and checked for duplication so the same content will only be sent once.

Parameters:

limit - maximum number of characters for sharing (zero to disable)

setSharedAttributes

public final void setSharedAttributes(int limit)

Set shared attribute text parameter. This method enables or disables attribute value text sharing, with associated control information. If enabled, attribute value Strings of no more than the limit length are assigned handles and checked for duplication so the same value will only be sent once.

Parameters:

limit - maximum number of characters for sharing (zero to disable)

setMark

protected final void setMark()
                      throws java.io.IOException

Set buffer mark for later access. Marks the current byte position (next byte to be written), allowing it to be read and/or written later. It is an error to call this method while a mark is set.

Throws:

java.io.IOException - on error writing to stream

readMarked

protected final int readMarked()

Read marked byte. Reads the previously marked byte. It is an error to call this method if a mark is not set, or before the marked byte has been written normally.

Returns:

current value of marked byte

writeMarked

protected final void writeMarked(int value)

Write marked byte. Writes the previously marked byte. It is an error to call this method if a mark is not set, or before the marked byte has been written normally.

Parameters:

value - value to be written to byte

clearMark

protected final void clearMark()

Clear buffer mark. It is an error to call this method if a mark is not set.

flush

public void flush()
           throws java.io.IOException

Write buffer to output stream. Writes any data currently in the buffer to the output stream, setting the buffer to the empty state. It is an error to call this method while a mark is set.

Throws:

java.io.IOException - on error writing to stream

writeByte

protected final void writeByte(int value)
                        throws java.io.IOException

Write byte to buffer. Writes the block of data to the output stream if the buffer is full.

Parameters:

value - byte to be stored to buffer

Throws:

java.io.IOException - on error writing to stream

writeValue

protected void writeValue(int value)
                   throws java.io.IOException

Write non-negative integer value to stream. This handles encoding of the variable-length representation used in the serial form, which gives seven bits of value per serialized byte by using the high-order bit of each byte as a continuation flag.

Parameters:

value - value to be written to stream

Throws:

java.io.IOException - on error writing to stream

writeQuickValue

protected final void writeQuickValue(int value,
                                     int initial,
                                     int mask)
                              throws java.io.IOException

Write non-negative integer value with partial lead byte to stream. This handles encoding of the variable-length representation used in the serial form, with a partial leading byte. This format is used when a handle value is combined with flags. If the value cannot fit in the initial byte a zero value is used to indicate a continuation and the standard encoding is used in the following byte(s).

Parameters:

value - value to be written to stream

initial - byte containing high bits of value

mask - value mask within first byte (right justified)

Throws:

java.io.IOException - on error writing to stream

writeChars

protected final void writeChars(char[] buff,
                                int offset,
                                int length)
                         throws java.io.IOException

Write string of characters to stream. This method just encodes the characters in chunks guaranteed to fit in the buffer.

Parameters:

buff - array containing characters to be written

offset - starting offset in buffer

length - number of characters in string

Throws:

java.io.IOException - on error writing to stream

writeStringData

protected final void writeStringData(java.lang.String text)
                              throws java.io.IOException

Write String data to stream. This method uses a dual approach to retrieving the array of characters in the String, depending on the number of characters. If the count is low, the code first makes sure there's enough space in the buffer to hold all the encoded characters and then accesses them one at a time for conversion. If the count is high, we retrieve the entire array of characters and then encode them in chunks guaranteed to fit in the buffer. This approach creates some duplicate code, but gives the best performance.

Parameters:

text - String to be written

Throws:

java.io.IOException - on error writing to stream

writeStringChars

protected final void writeStringChars(char[] buff,
                                      int offset,
                                      int length)
                               throws java.io.IOException

Write character string directly to stream. This handles encoding of the character string value representation used in the serial form. The character count plus one is first encoded in the standard integer value format, followed by the specified number of characters.

Parameters:

buff - array containing characters to be written (non-null)

offset - starting offset in buffer

length - number of characters in string

Throws:

java.io.IOException - on error writing to stream

See Also:

writeChars(char[], int, int)

writeString

protected final void writeString(java.lang.String text)
                          throws java.io.IOException

Write String directly to stream. This handles encoding of the String value representation used in the serial form. The character count plus one is first encoded in the standard integer value format (with the value zero reserved for use with null Strings), followed by the specified number of characters.

Parameters:

text - String to be written (may be null)

Throws:

java.io.IOException - on error writing to stream

See Also:

writeStringData(java.lang.String)

writeText

protected final void writeText(char[] buff,
                               int offset,
                               int length)
                        throws java.io.IOException

Write content text to stream. If shared content text is enabled and this text meets the qualifications for sharing, this first checks if the text has previously been output. If so, the existing handle is used to reference the text; if not, the value is output and assigned the next consecutive handle value. If shared content text is not enabled or this text does not qualify, the text is output as a plain text value.

Parameters:

buff - array containing characters to be written

offset - starting offset in buffer

length - number of characters in string

Throws:

java.io.IOException - on error writing to stream

writeText

protected final void writeText(java.lang.String text)
                        throws java.io.IOException

Write content text to stream. If shared content text is enabled and this text meets the qualifications for sharing, this first checks if the text has previously been output. If so, the existing handle is used to reference the text; if not, the value is output and assigned the next consecutive handle value. If shared content text is not enabled or this text does not qualify, the text is output as a plain text value.

Parameters:

text - content text to be written

Throws:

java.io.IOException - on error writing to stream

writeNamespaceDef

public void writeNamespaceDef(XBISWriter.OutputNamespace ns)
                       throws java.io.IOException

Write namespace definition to stream. This is used to define a new namespace (prefix+URI pair). The format is a single byte with a handle value for the namespace URI and a quick length field for the prefix.

Parameters:

ns - namespace to be declared

Throws:

java.io.IOException - on error writing to stream

writeNamespaceDecl

public void writeNamespaceDecl(XBISWriter.OutputNamespace ns)
                        throws java.io.IOException

Write namespace declaration to stream. This allows the reuse of a previously defined namespace without the need to write the component information to the stream again, but can also be used to define a new namespace. The format is a single byte with a handle value for the namespace reference to be reused (extended to multiple bytes, if needed). The scope of the namespace is the whole of the following element.

Parameters:

ns - namespace to be declared

Throws:

java.io.IOException - on error writing to stream

writeNameDef

protected final void writeNameDef(java.lang.String local,
                                  XBISWriter.OutputNamespace ns)
                           throws java.io.IOException

Write name definition to stream. This encodes the namespace definition and local name, with a leading byte specifying the format.

Parameters:

local - local name to be written

ns - namespace object for name

Throws:

java.io.IOException - on error writing to stream

writeAttribute

protected final void writeAttribute(java.lang.Object obj,
                                    java.lang.String value)
                             throws java.io.IOException

Write attribute to stream. The attribute format uses a lead byte with flags for shared attribute value and value definition combined with the attribute handle. The lead byte is followed by the continuation of the attribute handle or the attribute name definition, if necessary, and then by the attribute value, value handle, or value definition.

Parameters:

obj - attribute to be written

value - text of value to be written

Throws:

java.io.IOException - on error writing to stream

getNamespace

public XBISWriter.OutputNamespace getNamespace(java.lang.String prefix,
                                               java.lang.String uri)
                                        throws XBISException

Get namespace declaration. This finds the requested namespace, creating it if it does not already exist.

Parameters:

prefix - element namespace prefix

uri - element namespace URI

Throws:

XBISException - on namespace error

closeNamespaces

public void closeNamespaces(int count)

Close some number of active namespace declarations. Since namespaces always have element scope, this can be used to close all namespace declarations present on an element at the end of that element.

Parameters:

count - number of active namespace declarations to be closed

clearReset

protected void clearReset()

Clear reset state. This method must be called before beginning any operations which write to the output stream.

isReset

protected boolean isReset()

Check reset state.

Returns:

true if reset, false if not

reset

public void reset()

Reset state information used during the serialization process. This reinitializes the serialization state so that an instance of this class can be reused to serialize multiple independent documents. Subclasses overriding this method to perform their own reinitialization must call the base class method before returning to the caller.

initState

protected abstract void initState()

Initialize state information used during the serialization process. This abstract method must be implemented by each subclass to set up predefined state information in the tables.

getAttributeHandle

protected abstract int getAttributeHandle(java.lang.Object obj)

Get handle for attribute. This abstract method must be implemented by each subclass to return the handle for an attribute.

Parameters:

obj - attribute object for which handle is to be found

Returns:

handle value if defined (always strictly positive), negative value if not defined

defineAttribute

protected abstract void defineAttribute(java.lang.Object obj)
                                 throws java.io.IOException

Add attribute definition. This abstract method must be implemented by each subclass to write an attribute definition to the output stream and add it as a handle.

Parameters:

obj - attribute object to be defined

Throws:

java.io.IOException - on error writing to stream