org.jibx.v2
Interface XmlWriter

public interface XmlWriter

XML writer interface used for output of marshalled document. This interface allows easy substitution of different output formats, including parse event stream equivalents. This makes heavy use of state information, so each method call defined is only valid in certain states.

Author:

Dennis M. Sosnoski

Method Summary

void	addOptionalTextAttribute(java.lang.String name, java.lang.String value) Add optional no-namespace text attribute to current open start tag.
void	addOptionalTextAttribute(java.lang.String ns, java.lang.String name, java.lang.String value) Add optional text attribute to current open start tag.
void	addText(java.lang.String value) Write a text value as the content of the current element.
void	addTextAttribute(java.lang.String name, java.lang.String value) Add no-namespace text attribute to current open start tag.
void	addTextAttribute(java.lang.String ns, java.lang.String name, java.lang.String value) Add text attribute to current open start tag.
void	close() Close document output.
void	convert(java.math.BigDecimal value) Write a BigDecimal value to the current text selection.
void	convert(java.math.BigInteger value) Write a BigInteger value to the current text selection.
void	convert(boolean value) Write a boolean value to the current text selection.
void	convert(byte[] value) Write a byte[] value to the current text selection using base64Binary encoding.
void	convert(double value) Write a double value to the current text selection.
void	convert(float value) Write a float value to the current text selection.
void	convert(int value) Write an int value to the current text selection.
void	convert(long value) Write a long value to the current text selection.
void	convert(java.lang.String value) Write a String value to the current text selection.
void	convertDate(long value) Write a long milliseconds time value to the current text selection as an xsd:date.
void	convertDateTime(long value) Write a long milliseconds time value to the current text selection as an xsd:dateTime.
void	convertDateTime(long value, int nanos) Write a long milliseconds time value and associated nanosecond count to the current text selection as an xsd:dateTime.
void	convertQName(java.lang.String ns, java.lang.String name) Write a qualified name value to the current text selection.
void	convertTime(long value) Write a long milliseconds time value to the current text selection as an xsd:time.
void	convertTime(long value, int nanos) Write a long milliseconds time value and associated nanosecond count to the current text selection as an xsd:time.
void	endTag() Write end tag for current open element.
void	flush() Flush document output.
MarshallingContext	getContext() Get the marshalling context associated with this writer.
java.lang.String[][]	getExtensionNamespaces() Get extension namespace URIs added to those in mapping.
int	getNamespaceCount() Get the number of namespaces currently defined.
java.lang.String	getNamespacePrefix(int index) Get current prefix defined for namespace.
java.lang.String[]	getNamespaces() Get namespace URIs for mapping.
java.lang.String	getNamespaceUri(int index) Get URI for namespace.
int	getNestingDepth() Get the current element nesting depth.
int	getPrefixIndex(java.lang.String prefix) Get index of namespace mapped to prefix.
ValidationContext	getValidationContext() Get the current validation context for this writer.
void	handleMissingAttribute(java.lang.String name) Handle a missing required attribute value from the implicit namespace in the generated document.
void	handleMissingAttribute(java.lang.String ns, java.lang.String name) Handle a missing required attribute value in the generated document.
void	handleMissingElement(java.lang.String name) Handle a missing required element value from the implicit namespace in the generated document.
void	handleMissingElement(java.lang.String ns, java.lang.String name) Handle a missing required element value in the generated document.
void	indent() Request output indent.
void	openNamespace(java.lang.String ns, java.lang.String prefix) Add a namespace declaration to the next element start tag.
int[]	openNamespaces(int[] nums, java.lang.String[] prefs) Open the specified namespaces for use.
void	popExtensionNamespaces() Remove extension namespace URIs.
void	pushExtensionNamespaces(java.lang.String[] uris) Append extension namespace URIs to those in mapping.
void	reset() Reset to initial state for reuse.
void	selectAttribute(java.lang.String name) Select a no-namespace attribute as the destination for a conversion.
void	selectAttribute(java.lang.String ns, java.lang.String name) Select an attribute as the destination for a conversion.
void	selectContent() Select text content as the destination for a conversion.
void	selectContent(java.lang.String name) Select a child element in the implicit namespace as the destination for a conversion.
void	selectContent(java.lang.String ns, java.lang.String name) Select a child element as the destination for a conversion.
void	setAttributeDoubleQuote(boolean prefdbl) Set attribute double-quote character usage.
void	setBooleanNumeric(boolean prefnum) Set boolean numeric value usage.
java.lang.String	setImplicitNamespace(java.lang.String ns) Set the implicit namespace used for elements unless otherwise specified.
void	setIndent(int count, java.lang.String newline, char indent) Set nesting indentation.
void	startTag(java.lang.String name) Write the start tag for an element in the implicit namespace.
void	startTag(java.lang.String ns, java.lang.String name) Write the start tag for an element.
void	startTagImplicit(java.lang.String ns, java.lang.String prefix, java.lang.String name) Declare a namespace, make it the implicit namespace, and write the start tag for an element in that namespace.
void	writeCData(java.lang.String text) Write CDATA text to document.
void	writeComment(java.lang.String text) Write comment to document.
void	writeDocType(java.lang.String name, java.lang.String sys, java.lang.String pub, java.lang.String subset) Write DOCTYPE declaration to document.
void	writeEntityRef(java.lang.String name) Write entity reference to document.
void	writePI(java.lang.String target, java.lang.String data) Write processing instruction to document.
void	writeTextContent(java.lang.String text) Write ordinary character data text content to document.
void	writeXMLDecl(java.lang.String version, java.lang.String encoding, java.lang.String standalone) Write XML declaration to document.

Method Detail

getContext

MarshallingContext getContext()

Get the marshalling context associated with this writer. The marshalling context tracks higher-level information about the conversion of XML into a Java object structure.

Returns:

context

getValidationContext

ValidationContext getValidationContext()

Get the current validation context for this writer. The validation context is used both for tracking problems, and to determine the appropriate handling when a problem occurs.

Returns:

context

getNestingDepth

int getNestingDepth()

Get the current element nesting depth. Elements are only counted in the depth returned when they're officially open - after the start tag has been output and before the end tag has been output.

Returns:

number of nested elements at current point in output

getNamespaceCount

int getNamespaceCount()

Get the number of namespaces currently defined. This is equivalent to the index of the next extension namespace added.

Returns:

namespace count

setIndent

void setIndent(int count,
               java.lang.String newline,
               char indent)

Set nesting indentation. This is advisory only, and implementations of this interface are free to ignore it. The intent is to indicate that the generated output should use indenting to illustrate element nesting.

Parameters:

count - number of character to indent per level, or disable indentation if negative (zero means new line only)

newline - sequence of characters used for a line ending (null means use the single character '\n')

indent - whitespace character used for indentation

setAttributeDoubleQuote

void setAttributeDoubleQuote(boolean prefdbl)

Set attribute double-quote character usage. If this is true, the double-quote (") character is preferred for attribute values; if false (the default), the single-quote (') character is preferred. This setting is advisory only, and implementations of this interface are free to ignore it.

Parameters:

prefdbl - prefer double-quote flag

setBooleanNumeric

void setBooleanNumeric(boolean prefnum)

Set boolean numeric value usage. If this is true, numeric values ('0' and '1') are preferred for boolean values; if false (the default), text values ('false' and 'true') are preferred. This setting is advisory only, and implementations of this interface are free to ignore it.

Parameters:

prefnum - prefer numeric boolean value flag

setImplicitNamespace

java.lang.String setImplicitNamespace(java.lang.String ns)

Set the implicit namespace used for elements unless otherwise specified. The namespace must have been opened prior to this call.

Parameters:

ns - namespace URI for element (may be the empty string for the no-namespace namespace)

Returns:

prior implicit namespace

startTag

void startTag(java.lang.String name)
              throws JiBXException

Write the start tag for an element in the implicit namespace.

Parameters:

name - element name

Throws:

JiBXException - on unrecoverable error

startTag

void startTag(java.lang.String ns,
              java.lang.String name)
              throws JiBXException

Write the start tag for an element.

Parameters:

ns - namespace URI for element (may be the empty string for the no-namespace namespace)

name - unqualified element name

Throws:

JiBXException - on unrecoverable error

startTagImplicit

void startTagImplicit(java.lang.String ns,
                      java.lang.String prefix,
                      java.lang.String name)
                      throws JiBXException

Declare a namespace, make it the implicit namespace, and write the start tag for an element in that namespace. This is just a shortcut for the sequence of calls openNamespace(String, String), setImplicitNamespace(String), startTag(String).

Parameters:

ns - namespace URI for element (may be the empty string for the no-namespace namespace)

prefix - prefix to be used for the namespace (use "" for default namespace declaration)

name - unqualified element name

Throws:

JiBXException - on unrecoverable error

openNamespace

void openNamespace(java.lang.String ns,
                   java.lang.String prefix)
                   throws JiBXException

Add a namespace declaration to the next element start tag. If the namespace is already open this call does nothing.

Parameters:

ns - namespace URI (may be the empty string for the no-namespace namespace)

prefix - prefix to be used for the namespace (use "" for default namespace declaration)

Throws:

JiBXException - on unrecoverable error

addTextAttribute

void addTextAttribute(java.lang.String name,
                      java.lang.String value)
                      throws JiBXException

Add no-namespace text attribute to current open start tag. This is only valid with an open start tag.

Parameters:

name - unqualified attribute name

value - text value for attribute

Throws:

JiBXException - on unrecoverable error

addTextAttribute

void addTextAttribute(java.lang.String ns,
                      java.lang.String name,
                      java.lang.String value)
                      throws JiBXException

Add text attribute to current open start tag. This is only valid with an open start tag.

Parameters:

ns - namespace URI (may be the empty string for the no-namespace namespace)

name - unqualified attribute name

value - text value for attribute

Throws:

JiBXException - on unrecoverable error

addOptionalTextAttribute

void addOptionalTextAttribute(java.lang.String name,
                              java.lang.String value)
                              throws JiBXException

Add optional no-namespace text attribute to current open start tag. This is only valid with an open start tag.

Parameters:

name - unqualified attribute name

value - text value for attribute (null if no value)

Throws:

JiBXException - on unrecoverable error

addOptionalTextAttribute

void addOptionalTextAttribute(java.lang.String ns,
                              java.lang.String name,
                              java.lang.String value)
                              throws JiBXException

Add optional text attribute to current open start tag. This is only valid with an open start tag.

Parameters:

ns - namespace URI (may be the empty string for the no-namespace namespace)

name - unqualified attribute name

value - text value for attribute (null if no value)

Throws:

JiBXException - on unrecoverable error

selectContent

void selectContent()
                   throws JiBXException

Select text content as the destination for a conversion.

Throws:

JiBXException - on unrecoverable error

selectContent

void selectContent(java.lang.String name)
                   throws JiBXException

Select a child element in the implicit namespace as the destination for a conversion.

Parameters:

name - element name

Throws:

JiBXException - on unrecoverable error

selectContent

void selectContent(java.lang.String ns,
                   java.lang.String name)
                   throws JiBXException

Select a child element as the destination for a conversion.

Parameters:

ns - namespace URI (may be the empty string for the no-namespace namespace)

name - element name

Throws:

JiBXException - on unrecoverable error

selectAttribute

void selectAttribute(java.lang.String name)
                     throws JiBXException

Select a no-namespace attribute as the destination for a conversion. This is only valid with an open start tag.

Parameters:

name - unqualified attribute name

Throws:

JiBXException - on unrecoverable error

selectAttribute

void selectAttribute(java.lang.String ns,
                     java.lang.String name)
                     throws JiBXException

Select an attribute as the destination for a conversion. This is only valid with an open start tag.

Parameters:

ns - namespace URI (may be the empty string for the no-namespace namespace)

name - unqualified attribute name

Throws:

JiBXException - on unrecoverable error

convert

void convert(java.lang.String value)
             throws JiBXException

Write a String value to the current text selection.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convert

void convert(int value)
             throws JiBXException

Write an int value to the current text selection.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convert

void convert(long value)
             throws JiBXException

Write a long value to the current text selection.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convert

void convert(float value)
             throws JiBXException

Write a float value to the current text selection.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convert

void convert(double value)
             throws JiBXException

Write a double value to the current text selection.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convert

void convert(boolean value)
             throws JiBXException

Write a boolean value to the current text selection.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convert

void convert(byte[] value)
             throws JiBXException

Write a byte[] value to the current text selection using base64Binary encoding.

Parameters:

value - attribute value

Throws:

JiBXException - on unrecoverable error

convertDateTime

void convertDateTime(long value)
                     throws JiBXException

Write a long milliseconds time value to the current text selection as an xsd:dateTime.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convertDateTime

void convertDateTime(long value,
                     int nanos)
                     throws JiBXException

Write a long milliseconds time value and associated nanosecond count to the current text selection as an xsd:dateTime.

Parameters:

value -

nanos -

Throws:

JiBXException - on unrecoverable error

convertDate

void convertDate(long value)
                 throws JiBXException

Write a long milliseconds time value to the current text selection as an xsd:date.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convertTime

void convertTime(long value)
                 throws JiBXException

Write a long milliseconds time value to the current text selection as an xsd:time.

Parameters:

value -

Throws:

JiBXException - on unrecoverable error

convertTime

void convertTime(long value,
                 int nanos)
                 throws JiBXException

Write a long milliseconds time value and associated nanosecond count to the current text selection as an xsd:time.

Parameters:

value -

nanos -

Throws:

JiBXException - on unrecoverable error

convertQName

void convertQName(java.lang.String ns,
                  java.lang.String name)
                  throws JiBXException

Write a qualified name value to the current text selection. The qualified name is presented as a pair consisting of namespace URI and local name in order to allow flexible use.

Parameters:

ns - namespace URI (empty string if no-namespace namespace)

name - local name

Throws:

JiBXException - on unrecoverable error

convert

void convert(java.math.BigDecimal value)
             throws JiBXException

Write a BigDecimal value to the current text selection.

Parameters:

value - (non-null)

Throws:

JiBXException - on unrecoverable error

convert

void convert(java.math.BigInteger value)
             throws JiBXException

Write a BigInteger value to the current text selection.

Parameters:

value - (non-null)

Throws:

JiBXException - on unrecoverable error

addText

void addText(java.lang.String value)
             throws JiBXException

Write a text value as the content of the current element. This writes the corresponding end tag after writing the value.

Parameters:

value - content value

Throws:

JiBXException - on unrecoverable error

endTag

void endTag()
            throws JiBXException

Write end tag for current open element.

Throws:

JiBXException - on unrecoverable error

handleMissingElement

void handleMissingElement(java.lang.String name)
                          throws JiBXException

Handle a missing required element value from the implicit namespace in the generated document.

Parameters:

name -

Throws:

JiBXException - on unrecoverable error

handleMissingElement

void handleMissingElement(java.lang.String ns,
                          java.lang.String name)
                          throws JiBXException

Handle a missing required element value in the generated document.

Parameters:

ns -

name -

Throws:

JiBXException - on unrecoverable error

handleMissingAttribute

void handleMissingAttribute(java.lang.String name)
                            throws JiBXException

Handle a missing required attribute value from the implicit namespace in the generated document.

Parameters:

name -

Throws:

JiBXException - on unrecoverable error

handleMissingAttribute

void handleMissingAttribute(java.lang.String ns,
                            java.lang.String name)
                            throws JiBXException

Handle a missing required attribute value in the generated document.

Parameters:

ns -

name -

Throws:

JiBXException - on unrecoverable error

writeXMLDecl

void writeXMLDecl(java.lang.String version,
                  java.lang.String encoding,
                  java.lang.String standalone)
                  throws JiBXException

Write XML declaration to document. This can only be called before any other methods in the interface are called.

Parameters:

version - XML version text

encoding - text for encoding attribute (unspecified if null)

standalone - text for standalone attribute (unspecified if null)

Throws:

JiBXException - on error writing to document

writeTextContent

void writeTextContent(java.lang.String text)
                      throws JiBXException

Write ordinary character data text content to document.

Parameters:

text - content value text (must not be null)

Throws:

JiBXException - on error writing to document

writeCData

void writeCData(java.lang.String text)
                throws JiBXException

Write CDATA text to document.

Parameters:

text - content value text (must not be null)

Throws:

JiBXException - on error writing to document

writeComment

void writeComment(java.lang.String text)
                  throws JiBXException

Write comment to document.

Parameters:

text - comment text (must not be null)

Throws:

JiBXException - on error writing to document

writeEntityRef

void writeEntityRef(java.lang.String name)
                    throws JiBXException

Write entity reference to document.

Parameters:

name - entity name (must not be null)

Throws:

JiBXException - on error writing to document

writeDocType

void writeDocType(java.lang.String name,
                  java.lang.String sys,
                  java.lang.String pub,
                  java.lang.String subset)
                  throws JiBXException

Write DOCTYPE declaration to document.

Parameters:

name - root element name

sys - system ID (null if none, must be non-null for ID to be used)

pub - ID (null if none)

subset - internal subset (null if none)

Throws:

JiBXException - on error writing to document

writePI

void writePI(java.lang.String target,
             java.lang.String data)
             throws JiBXException

Write processing instruction to document.

Parameters:

target - processing instruction target name (must not be null)

data - processing instruction data (must not be null)

Throws:

JiBXException - on error writing to document

indent

void indent()
            throws JiBXException

Request output indent. The writer implementation should normally indent output as appropriate. This method can be used to request indenting of output that might otherwise not be indented. The normal effect when used with a text-oriented writer should be to output the appropriate line end sequence followed by the appropriate number of indent characters for the current nesting level.

Throws:

JiBXException - on error writing to document

flush

void flush()
           throws JiBXException

Flush document output. Writes any buffered data to the output medium. This does not flush the output medium itself, only any internal buffering within the writer.

Throws:

JiBXException - on error writing to document

close

void close()
           throws JiBXException

Close document output. Completes writing of document output, including flushing and closing the output medium.

Throws:

JiBXException - on error writing to document

reset

void reset()

Reset to initial state for reuse. The context is serially reusable, as long as this method is called to clear any retained state information between uses. It is automatically called when output is set.

getNamespaces

java.lang.String[] getNamespaces()

Get namespace URIs for mapping. This gets the full ordered array of namespaces known in the binding used for this marshalling, where the index number of each namespace URI is the namespace index used to lookup the prefix when marshalling a name in that namespace. The returned array must not be modified.

Returns:

array of namespaces

getNamespaceUri

java.lang.String getNamespaceUri(int index)

Get URI for namespace.

Parameters:

index - namespace URI index number

Returns:

namespace URI text, or null if the namespace index is invalid

getNamespacePrefix

java.lang.String getNamespacePrefix(int index)

Get current prefix defined for namespace.

Parameters:

index - namespace URI index number

Returns:

current prefix text, or null if the namespace is not currently mapped

getPrefixIndex

int getPrefixIndex(java.lang.String prefix)

Get index of namespace mapped to prefix. This can be an expensive operation with time proportional to the number of namespaces defined, so it should be used with care.

Parameters:

prefix - text to match (non-null, use "" for default prefix)

Returns:

index namespace URI index number mapped to prefix

pushExtensionNamespaces

void pushExtensionNamespaces(java.lang.String[] uris)

Append extension namespace URIs to those in mapping.

Parameters:

uris - namespace URIs to extend those in mapping

popExtensionNamespaces

void popExtensionNamespaces()

Remove extension namespace URIs. This removes the last set of extension namespaces pushed using pushExtensionNamespaces(java.lang.String[]).

getExtensionNamespaces

java.lang.String[][] getExtensionNamespaces()

Get extension namespace URIs added to those in mapping. This gets the current set of extension definitions. The returned arrays must not be modified.

Returns:

array of arrays of extension namespaces (null if none)

openNamespaces

int[] openNamespaces(int[] nums,
                     java.lang.String[] prefs)
                     throws JiBXException

Open the specified namespaces for use. This method is normally only called internally, when namespace declarations are actually written to output. It is exposed as part of this interface to allow for special circumstances where namespaces are being written outside the usual processing. The namespaces will remain open for use until the current element is closed.

Parameters:

nums - array of namespace indexes defined by this element (must be constant, reference is kept until namespaces are closed)

prefs - array of namespace prefixes mapped by this element (no null values, use "" for default namespace declaration)

Returns:

array of indexes for namespaces not previously active (the ones actually needing to be declared, in the case of text output)

Throws:

JiBXException - on error writing to document