Package com.yahoo.text

Class XMLWriter

java.lang.Object

java.io.Writer

com.yahoo.text.GenericWriter

com.yahoo.text.ForwardWriter

com.yahoo.text.XMLWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

public class XMLWriter
extends ForwardWriter

A stream wrapper which contains utility methods for writing xml. All methods return this for convenience.

The methods of this writer can be used in conjunction with writing tags in raw form directly to the writer if some care is taken to close start tags and insert line breaks explicitly. If all content is written using these methods, start tags are closed and newlines inserted automatically as appropriate.

Author:

bratseth, baldersheim

Field Summary

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

Constructor	Description
XMLWriter(java.io.Writer writer)	Creates an XML wrapper of a writer having maxIndentLevel=10 and maxLineSeparatorLevel=1
XMLWriter(java.io.Writer writer, boolean markupIsAscii)	Creates an XML wrapper of a writer having maxIndentLevel=10 and maxLineSeparatorLevel=1
XMLWriter(java.io.Writer writer, int maxIndentLevel)	Creates an XML wrapper of a writer having maxLineSeparatorLevel=1
XMLWriter(java.io.Writer writer, int maxIndentLevel, boolean markupIsAscii)	Creates an XML wrapper of a writer having maxLineSeparatorLevel=1
XMLWriter(java.io.Writer writer, int maxIndentLevel, int maxLineSeparatorLevel)	Creates an XML wrapper of a writer
XMLWriter(java.io.Writer writer, int maxIndentLevel, int maxLineSeparatorLevel, boolean markupIsAscii)	Creates an XML wrapper of a writer

Method Summary

Modifier and Type	Method	Description
XMLWriter	attribute(Utf8String name, boolean value)	Writes an attribute by its utf8 value
XMLWriter	attribute(Utf8String name, double value)	Writes an attribute by its utf8 value
XMLWriter	attribute(Utf8String name, long value)	Writes an attribute by its utf8 value
XMLWriter	attribute(Utf8String name, AbstractUtf8Array value)	Writes an attribute by its utf8 value
XMLWriter	attribute(Utf8String name, java.lang.Number value)	Writes an attribute by its utf8 value
XMLWriter	attribute(Utf8String name, java.lang.String value)	Writes an attribute by XML.xmlEscape(value.toString(),false)
XMLWriter	attribute(java.lang.String name, java.lang.Object value)
XMLWriter	closeStartTag()	Closes the start tag.
XMLWriter	closeTag()
XMLWriter	content(java.lang.Object content, boolean multiline)	XML escapes and writes the content.toString().
XMLWriter	escapedAsciiContent(java.lang.String content, boolean multiline)	Writes the given US-ASCII only string as-is.
XMLWriter	escapedContent(java.lang.String content, boolean multiline)	Writes the given string as-is.
XMLWriter	forceAttribute(Utf8String name, java.lang.Object value)	Writes an attribute by XML.xmlEscape(value.toString(),false)
XMLWriter	forceAttribute(java.lang.String name, java.lang.Object value)
static XMLWriter	from(java.io.Writer writer)	Returns the input writer as-is if it is an XMLWriter instance.
static XMLWriter	from(java.io.Writer writer, int maxIndentLevel, int maxLineSeparatorLevel)	Returns the input writer as-is if it is an XMLWriter instance.
java.io.Writer	getWrapped()
boolean	isIn(Utf8String containingTag)	Returns true if the immediate parent (i.e the last element in openTags) is the tag with the given name
boolean	isIn(java.lang.String containingTag)
XMLWriter	openTag(Utf8String tag)
XMLWriter	openTag(java.lang.String s)
java.util.List<Utf8String>	openTags()	Returns a read only view of the currently open tags we are within, sorted by highest to lowest in the hierarchy Only used for testing.
void	xmlHeader(java.lang.String encoding)	Writes the first line of an XML file

Methods inherited from class com.yahoo.text.ForwardWriter

close, flush, getWriter, write, write, write, write, write, write, write, write, write, write, write, write

Methods inherited from class java.io.Writer

append, append, append, nullWriter, write, write

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLWriter

public XMLWriter(java.io.Writer writer)

Creates an XML wrapper of a writer having maxIndentLevel=10 and maxLineSeparatorLevel=1

Parameters:

writer - the writer to which this writers (accessible from this by getWrapped)

XMLWriter

public XMLWriter(java.io.Writer writer,
                 boolean markupIsAscii)

Creates an XML wrapper of a writer having maxIndentLevel=10 and maxLineSeparatorLevel=1

Parameters:

writer - the writer to which this writers (accessible from this by getWrapped)

markupIsAscii - set to false to make this encode markup (tags, attributes). By default encoding is skipped if the underlying stream uses utf encoding for performance (yes, this matters)

XMLWriter

public XMLWriter(java.io.Writer writer,
                 int maxIndentLevel)

Creates an XML wrapper of a writer having maxLineSeparatorLevel=1

Parameters:

writer - the writer to which this writers (accessible from this by getWrapped)

maxIndentLevel - the max number of tag levels for which we'll continue to indent, or -1 to never indent. The top level tag is level 0, etc.

XMLWriter

public XMLWriter(java.io.Writer writer,
                 int maxIndentLevel,
                 boolean markupIsAscii)

Creates an XML wrapper of a writer having maxLineSeparatorLevel=1

Parameters:

writer - the writer to which this writers (accessible from this by getWrapped)

maxIndentLevel - the max number of tag levels for which we'll continue to indent, or -1 to never indent. The top level tag is level 0, etc.

markupIsAscii - set to false to make this encode markup (tags, attributes). By default encoding is skipped if the underlying stream uses utf encoding for performance (yes, this matters)

XMLWriter

public XMLWriter(java.io.Writer writer,
                 int maxIndentLevel,
                 int maxLineSeparatorLevel)

Creates an XML wrapper of a writer

Parameters:

writer - the writer to which this writers (accessible from this by getWrapped)

maxIndentLevel - the max number of tag levels for which we'll continue to indent, or -1 to never indent. The top level tag is level 0, etc.

maxLineSeparatorLevel - the max number of tag levels for which we'll add a blank line separator, or -1 to never add line separators. The top level tag is level 0, etc.

XMLWriter

public XMLWriter(java.io.Writer writer,
                 int maxIndentLevel,
                 int maxLineSeparatorLevel,
                 boolean markupIsAscii)

Creates an XML wrapper of a writer

Parameters:

writer - the writer to which this writers (accessible from this by getWrapped)

maxIndentLevel - the max number of tag levels for which we'll continue to indent, or -1 to never indent. The top level tag is level 0, etc.

maxLineSeparatorLevel - the max number of tag levels for which we'll add a blank line separator, or -1 to never add line separators. The top level tag is level 0, etc.

markupIsAscii - set to false to make this encode markup (tags, attributes). By default encoding is skipped if the underlying stream uses utf encoding for performance (yes, this matters)

Method Detail

from

public static XMLWriter from(java.io.Writer writer,
                             int maxIndentLevel,
                             int maxLineSeparatorLevel)

Returns the input writer as-is if it is an XMLWriter instance. Returns new XMLWriter(writer) otherwise

from

public static XMLWriter from(java.io.Writer writer)

Returns the input writer as-is if it is an XMLWriter instance. Returns new XMLWriter(writer) otherwise

getWrapped

public java.io.Writer getWrapped()

xmlHeader

public void xmlHeader(java.lang.String encoding)

Writes the first line of an XML file

openTag

public XMLWriter openTag(java.lang.String s)

openTag

public XMLWriter openTag(Utf8String tag)

closeTag

public XMLWriter closeTag()

closeStartTag

public XMLWriter closeStartTag()

Closes the start tag. Usually, it is not necessary to call this, as the other methods in this will do the right thing as needed. However, this can be called explicitly to allow content or subtags to be written by a regular write call which bypasses the logic in this. If a start tag is not currently open this has no effect.

forceAttribute

public XMLWriter forceAttribute(Utf8String name,
                                java.lang.Object value)

Writes an attribute by XML.xmlEscape(value.toString(),false)

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute. The empty string if the attribute is null or empty

forceAttribute

public XMLWriter forceAttribute(java.lang.String name,
                                java.lang.Object value)

attribute

public XMLWriter attribute(Utf8String name,
                           AbstractUtf8Array value)

Writes an attribute by its utf8 value

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute. This method does nothing if the value is null or empty

attribute

public XMLWriter attribute(Utf8String name,
                           java.lang.Number value)

Writes an attribute by its utf8 value

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute. This method does nothing if the value is null.

attribute

public XMLWriter attribute(Utf8String name,
                           long value)

Writes an attribute by its utf8 value

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute.

attribute

public XMLWriter attribute(Utf8String name,
                           double value)

Writes an attribute by its utf8 value

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute.

attribute

public XMLWriter attribute(Utf8String name,
                           boolean value)

Writes an attribute by its utf8 value

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute. This method does nothing if the value is null or empty

attribute

public XMLWriter attribute(Utf8String name,
                           java.lang.String value)

Writes an attribute by XML.xmlEscape(value.toString(),false)

Parameters:

name - the name of the attribute. An exception is thrown if this is null

value - the value of the attribute. This method does nothing if the value is null or empty

attribute

public XMLWriter attribute(java.lang.String name,
                           java.lang.Object value)

content

public XMLWriter content(java.lang.Object content,
                         boolean multiline)

XML escapes and writes the content.toString(). If the content is null this does nothing but closing the start tag.

Parameters:

content - the content - output by XML.xmlEscape(content.toString())

multiline - whether the content should be treated as multiline, such that the following end tag should appear on a new line

escapedContent

public XMLWriter escapedContent(java.lang.String content,
                                boolean multiline)

Writes the given string as-is. The content string must be XML escaped before calling this. If the content is null this does nothing but closing the start tag.

Parameters:

content - the content - output by XML.xmlEscape(content.toString())

multiline - whether the content should be treated as multiline, such that the following end tag should appear on a new line

escapedAsciiContent

public XMLWriter escapedAsciiContent(java.lang.String content,
                                     boolean multiline)

Writes the given US-ASCII only string as-is. If the content is not US-ASCII only this may cause incorrectly encoded content to be written. This is faster than using escapedContent as transcoding is skipped.

The content string must be XML escaped before calling this. If the content is null this does nothing but closing the start tag.

Parameters:

content - the content - output by XML.xmlEscape(content.toString())

multiline - whether the content should be treated as multiline, such that the following end tag should appear on a new line

openTags

public java.util.List<Utf8String> openTags()

Returns a read only view of the currently open tags we are within, sorted by highest to lowest in the hierarchy Only used for testing.

isIn

public boolean isIn(Utf8String containingTag)

Returns true if the immediate parent (i.e the last element in openTags) is the tag with the given name

isIn

public boolean isIn(java.lang.String containingTag)