Abstract base class that provides an interface for writing XML messages. More...

#include <rwsf/core/XmlWriter.h>

Inheritance diagram for rwsf::XmlWriter:

Public Member Functions
	XmlWriter ()

void	addNamespace (const rwsf::XmlNamespace &ns)

void	addNamespaceDecl (const rwsf::XmlNamespace &ns)

void	decrementIndent ()

int	getCurrentIndent () const

bool	getIgnoreWhitespace () const

bool	getMustEscapeTextDefault () const

int	getSizeOfIndent () const

void	incrementIndent ()

void	setCurrentIndent (int indent)

void	setIgnoreWhitespace (bool ignore)

void	setMustEscapeTextDefault (bool escape)

int	setSizeOfIndent (int indentSize)

void	write (const std::string &text)

void	write (const std::string &text, bool mustEscapeText)

void	write (const char *textData, size_t textLength, bool mustEscapeText)

void	writeAttribute (const std::string &name, const std::string &value)

void	writeAttribute (const rwsf::XmlName &name, const std::string &value)

void	writeAttribute (const std::string &name, const std::string &value, bool mustEscapeText)

void	writeAttribute (const rwsf::XmlName &name, const std::string &value, bool mustEscapeText)

void	writeAttribute (const std::string &name, const char *valueData, size_t valueLength)

void	writeAttribute (const rwsf::XmlName &name, const char *valueData, size_t valueLength)

void	writeAttribute (const std::string &name, const char *valueData, size_t valueLength, bool mustEscapeText)

void	writeAttribute (const rwsf::XmlName &name, const char *valueData, size_t valueLength, bool mustEscapeText)

void	writeElementEnd (const rwsf::XmlName &name)

void	writeElementStart (const rwsf::XmlName &name, const rwsf::XmlAttributeSet &attributes=rwsf::XmlAttributeSet(), bool emptyElement=false, const rwsf::XmlName &schemaType=rwsf::XmlName())

void	writeIndentChars ()

void	writeNewLine ()

void	writeSimpleElement (const rwsf::XmlName &name, const std::string &value, const rwsf::XmlName &schemaType, bool includeTypeAttribute)

void	writeSimpleElement (const rwsf::XmlName &name, const std::string &value, const std::string &schemaType, bool includeTypeAttribute)

void	writeSimpleElement (const std::string &name, const std::string &value, const std::string &schemaType, bool includeTypeAttribute)

void	writeSimpleElement (const rwsf::XmlName &name, const std::string &value, const std::string &schemaType, bool mustEscapeText, bool includeTypeAttribute)

void	writeSimpleElement (const std::string &name, const std::string &value, const std::string &schemaType, bool mustEscapeText, bool includeTypeAttribute)

void	writeSimpleElement (const rwsf::XmlName &name, const char *valueData, size_t valueLength, const rwsf::XmlName &schemaType, bool includeTypeAttribute)

void	writeSimpleElement (const rwsf::XmlName &name, const char *valueData, size_t valueLength, const std::string &schemaType, bool includeTypeAttribute)

void	writeSimpleElement (const std::string &name, const char *valueData, size_t valueLength, const std::string &schemaType, bool includeTypeAttribute)

void	writeSimpleElement (const rwsf::XmlName &name, const char *valueData, size_t valueLength, const rwsf::XmlName &schemaType, bool mustEscapeText, bool includeTypeAttribute)

void	writeSimpleElement (const rwsf::XmlName &name, const char *valueData, size_t valueLength, const std::string &schemaType, bool mustEscapeText, bool includeTypeAttribute)

void	writeSimpleElement (const std::string &name, const char *valueData, size_t valueLength, const std::string &schemaType, bool mustEscapeText, bool includeTypeAttribute)

Static Public Attributes
static const std::string	Blank

static const std::string	Colon

static const std::string	EndTag

static const std::string	EqualToAndQuotes

static const std::string	FalseValue

static const std::string	MarkupAmpersand

static const std::string	MarkupApos

static const std::string	MarkupCR

static const std::string	MarkupGt

static const std::string	MarkupLt

static const std::string	MarkupQuotes

static const std::string	Newline

static const std::string	Quotes

static const std::string	StartEndTag

static const std::string	StartTag

static const std::string	TrueValue

static const std::string	UnpairedTag

static const std::string	WhiteSpace

static const std::string	XmlNamespaceTag

Protected Member Functions
virtual void	flush ()=0

virtual void	writeToSink (const std::string &text)

virtual void	writeToSink (const char *str, size_t len)=0

virtual void	writeToSink (char c)=0

Detailed Description

Class rwsf::XmlWriter is an abstract base class that provides an interface for writing XML messages. A derived class implements the protected methods to write output to a specific data sink, such as an std::string, a file, or a socket. Applications typically do not use classes derived from rwsf::XmlWriter directly. Instead, the application passes the XmlWriter instance to the marshal() method of the generated XmlBinding classes created by rwsfgen.

This class implements methods for creating and formatting XML elements. rwsf::XmlWriter also manages namespace declarations. The class uses the concept of a namespace scope for determining when to add a namespace declaration. A namespace scope extends from the point at which an element start tag is declared with writeElementStart() until an element end tag is declared with writeElementEnd(). Namespace scopes nest. When creating an element tag, the writer includes namespace declarations for namespaces that are not in scope.

Note that an rwsf::XmlWriter does not automatically produce a namespace declaration for the xsi:type attribute. An application must take care to declare the xsi namespace before producing an element with a schema type attribute. Classes generated by the Agent handle this transparently, so this is only a consideration if an application produces XML output outside of a marshal() method provided in a generated class.

This class is intended to be flexible and suitable for use with streamed output. Therefore, the class does not strictly enforce well-formed XML. For example, there is no requirement that the name passed to writeElementEnd() match the name passed to the most recent call to writeElementStart().

Constructor & Destructor Documentation

rwsf::XmlWriter::XmlWriter ( )

Constructs a blank writer that will ignore whitespace, will not add newlines, will indent two spaces for each scope level, and has no predefined namespace scope.

Member Function Documentation

void rwsf::XmlWriter::addNamespace ( const rwsf::XmlNamespace & ns )

Adds the namespace ns to the current namespace scope. The writer does not declare the namespace for children of the current element.

void rwsf::XmlWriter::addNamespaceDecl ( const rwsf::XmlNamespace & ns )

Adds the namespace ns to the root element declaration. This function has no effect once the root element has been written.

void rwsf::XmlWriter::decrementIndent ( )

Subtracts one from the current indentation level. Has no effect if the current indentation level is 0.

virtual void rwsf::XmlWriter::flush ( )

protectedpure virtual

Pure virtual function. In a derived class, this function flushes the underlying data sink. The behavior of the function depends on the type of the data sink.

Implemented in rwsf::XmlStringWriter, and rwsf::XmlStreamWriter.

int rwsf::XmlWriter::getCurrentIndent ( ) const

Returns the current indentation level.

bool rwsf::XmlWriter::getIgnoreWhitespace ( ) const

Returns true if the writer is set to ignore whitespace (that is, calls to writeIndentChars() and writeNewLine() should not write whitespace); otherwise, false.

bool rwsf::XmlWriter::getMustEscapeTextDefault ( ) const

Returns true if the writer escapes text by default.

When mustEscapeText is true, the writer defaults to escaping all text by replacing the characters <, &, and > with equivalent entity declarations.
When mustEscapeText is false, the writer does not escape text by default. This value is initialized to true in the default constructor.

Note: The default value can be overridden in the write() functions that take the mustEscapeText parameter.

int rwsf::XmlWriter::getSizeOfIndent ( ) const

Returns the current indentation size. The indentation size sets the number of space characters the writer produces for each level of indentation. The indentation size defaults to 2.

void rwsf::XmlWriter::incrementIndent ( )

Adds one to the current indentation level.

void rwsf::XmlWriter::setCurrentIndent ( int indent )

Sets the current indentation level to indent.

void rwsf::XmlWriter::setIgnoreWhitespace ( bool ignore )

Sets the ignore whitespace attribute to the bool value ignore. This value is false by default.

void rwsf::XmlWriter::setMustEscapeTextDefault ( bool escape )

Sets the bool value for escape to define whether or not XML content is escaped by default. This value defaults to true.

Note: The default value can be overridden by parameters to the functions that use this feature.

int rwsf::XmlWriter::setSizeOfIndent ( int indentSize )

Sets the indentation size to indentSize, and returns the previous indentation size. The indentation size sets the number of space characters the writer produces for each level of indentation.

void rwsf::XmlWriter::write ( const std::string & text )

Writes text. Unless setMustEscapeTextDefault() has been called and set to false, the writer escapes text by replacing the characters <, &, >, `, and " with equivalent entity declarations.

void rwsf::XmlWriter::write	(	const std::string &	text,
		bool	mustEscapeText
	)

Writes text.

When mustEscapeText is true, the writer escapes text by replacing the special XML characters (such as <, &, and >) with equivalent entity declarations. When mustEscapeText is false, the writer does not escape text.

void rwsf::XmlWriter::write	(	const char *	textData,
		size_t	textLength,
		bool	mustEscapeText
	)

Writes out the character data specified by textData with the length textLength.

When mustEscapeText is true, the writer escapes text by replacing the special XML characters (such as <, &, and >) with equivalent entity declarations. When mustEscapeText is false, the writer does not escape text.

void rwsf::XmlWriter::writeAttribute	(	const std::string &	name,
		const std::string &	value
	)

Adds an attribute to the current element, using name for the name of the attribute and value for its value. Unless setMustEscapeTextDefault() has been called and set to false, the writer escapes value by replacing the characters <, &, >, `, and " with equivalent entity declarations.

Note: For a qualified name, this method prints out the prefix:name, but will not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined, or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const rwsf::XmlName &	name,
		const std::string &	value
	)

Adds an attribute to the current element, using name for the name of the attribute and value for its value. Unless setMustEscapeTextDefault() has been called and set to false, the writer escapes value by replacing the characters <, &, >, `, and " with equivalent entity declarations.

Note: For a qualified name, this method prints out the prefix:name, but will not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined, or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const std::string &	name,
		const std::string &	value,
		bool	mustEscapeText
	)

Adds an attribute to the current element, using name for the name of the attribute and value for its value.

When mustEscapeText is true, the writer escapes value by replacing the characters <, &, >, `, and " with equivalent entity declarations. When mustEscapeText is false, the writer does not escape value.

Note: For a qualified name, this will print out the prefix:name, but will e\ not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const rwsf::XmlName &	name,
		const std::string &	value,
		bool	mustEscapeText
	)

Adds an attribute to the current element, using name for the name of the attribute and value for its value.

When mustEscapeText is true, the writer escapes value by replacing the characters <, &, >, `, and " with equivalent entity declarations. When mustEscapeText is false, the writer does not escape value.

Note: For a qualified name, this will print out the prefix:name, but will e\ not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const std::string &	name,
		const char *	valueData,
		size_t	valueLength
	)

Adds an attribute to the current element, using name for the name of the attribute. For the value of the attribute, creates a string from the character array valueData and its length valueLength.

Unless setMustEscapeTextDefault() has been called and set to false, the writer escapes valueData by replacing the characters <, &, >, `, and " with equivalent entity declarations.

Note: For a qualified name, this will print out the prefix:name, but will not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const rwsf::XmlName &	name,
		const char *	valueData,
		size_t	valueLength
	)

Adds an attribute to the current element, using name for the name of the attribute. For the value of the attribute, creates a string from the character array valueData and its length valueLength.

Unless setMustEscapeTextDefault() has been called and set to false, the writer escapes valueData by replacing the characters <, &, >, `, and " with equivalent entity declarations.

Note: For a qualified name, this will print out the prefix:name, but will not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const std::string &	name,
		const char *	valueData,
		size_t	valueLength,
		bool	mustEscapeText
	)

Adds an attribute to the current element, using name for the name of the attribute. For the value of the attribute, creates a string from the character array valueData and its length valueLength.

When mustEscapeText is true, the writer escapes valueData by replacing the characters <, &, >, `, and " with equivalent entity declarations. When mustEscapeText is false, the writer does not escape valueData.

Note: For a qualified name, this will print out the prefix:name, but will not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeAttribute	(	const rwsf::XmlName &	name,
		const char *	valueData,
		size_t	valueLength,
		bool	mustEscapeText
	)

Adds an attribute to the current element, using name for the name of the attribute. For the value of the attribute, creates a string from the character array valueData and its length valueLength.

When mustEscapeText is true, the writer escapes valueData by replacing the characters <, &, >, `, and " with equivalent entity declarations. When mustEscapeText is false, the writer does not escape valueData.

Note: For a qualified name, this will print out the prefix:name, but will not print out the xmlns:prefix="uri" specifier. So the namespace for the prefix must already be defined or the resulting XML will be invalid.; If a qualified name is required for name, the parameter name must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

void rwsf::XmlWriter::writeElementEnd ( const rwsf::XmlName & name )

Writes the closing tag of an element, removing any namespaces added while writing the element.

void rwsf::XmlWriter::writeElementStart	(	const rwsf::XmlName &	name,
		const rwsf::XmlAttributeSet &	attributes = `rwsf::XmlAttributeSet()`,
		bool	emptyElement = `false`,
		const rwsf::XmlName &	schemaType = `rwsf::XmlName()`
	)

Writes the start tag of an element when emptyElement is false, and writes an empty element tag when emptyElement is true. Uses name for the name of the element and attributes for the attributes on the element. Declares the namespace within name in the element tag unless a namespace in the current scope matches the namespace within name. Uses schemaType to write out the xsi:type attribute if the schemaType is not empty.

void rwsf::XmlWriter::writeIndentChars ( )

Writes indentation for an element. The writer uses space characters to indent. The number of characters produced is the current indentation level multiplied by the current indentation size.

void rwsf::XmlWriter::writeNewLine ( )

Writes a new line.

void rwsf::XmlWriter::writeSimpleElement	(	const rwsf::XmlName &	name,
		const std::string &	value,
		const rwsf::XmlName &	schemaType,
		bool	includeTypeAttribute
	)