Package 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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description 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(boolean value)
Write aboolean
value to the current text selection.void
convert(byte[] value)
Write abyte[]
value to the current text selection using base64Binary encoding.void
convert(double value)
Write adouble
value to the current text selection.void
convert(float value)
Write afloat
value to the current text selection.void
convert(int value)
Write anint
value to the current text selection.void
convert(long value)
Write along
value to the current text selection.void
convert(java.lang.String value)
Write aString
value to the current text selection.void
convert(java.math.BigDecimal value)
Write aBigDecimal
value to the current text selection.void
convert(java.math.BigInteger value)
Write aBigInteger
value to the current text selection.void
convertDate(long value)
Write along
milliseconds time value to the current text selection as an xsd:date.void
convertDateTime(long value)
Write along
milliseconds time value to the current text selection as an xsd:dateTime.void
convertDateTime(long value, int nanos)
Write along
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 along
milliseconds time value to the current text selection as an xsd:time.void
convertTime(long value, int nanos)
Write along
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 istrue
, the double-quote (") character is preferred for attribute values; iffalse
(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 istrue
, numeric values ('0' and '1') are preferred for boolean values; iffalse
(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 callsopenNamespace(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 namevalue
- 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 namevalue
- 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 namevalue
- 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 namevalue
- 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 aString
value to the current text selection.- Parameters:
value
-- Throws:
JiBXException
- on unrecoverable error
-
convert
void convert(int value) throws JiBXException
Write anint
value to the current text selection.- Parameters:
value
-- Throws:
JiBXException
- on unrecoverable error
-
convert
void convert(long value) throws JiBXException
Write along
value to the current text selection.- Parameters:
value
-- Throws:
JiBXException
- on unrecoverable error
-
convert
void convert(float value) throws JiBXException
Write afloat
value to the current text selection.- Parameters:
value
-- Throws:
JiBXException
- on unrecoverable error
-
convert
void convert(double value) throws JiBXException
Write adouble
value to the current text selection.- Parameters:
value
-- Throws:
JiBXException
- on unrecoverable error
-
convert
void convert(boolean value) throws JiBXException
Write aboolean
value to the current text selection.- Parameters:
value
-- Throws:
JiBXException
- on unrecoverable error
-
convert
void convert(byte[] value) throws JiBXException
Write abyte[]
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 along
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 along
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 along
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 along
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 along
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 aBigDecimal
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 aBigInteger
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 textencoding
- text for encoding attribute (unspecified ifnull
)standalone
- text for standalone attribute (unspecified ifnull
)- 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 benull
)- 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 benull
)- 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 benull
)- 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 benull
)- 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 namesys
- 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 benull
)data
- processing instruction data (must not benull
)- 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 usingpushExtensionNamespaces(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 (nonull
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
-
-