#include <rw/leif/core/XmlWriter.h>
Class LEIF::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 a LEIF::CString, a file, or a socket. Applications typically do not use classes derived from LEIF::XmlWriter directly. Instead, the application passes the writer to the marshal() method of a class generated by LEIF.
This class implements methods for creating and formatting XML elements. LEIF::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 a LEIF::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 LEIF handle this transparently, so this is only a consideration if an application produces XML output outside of a marshal() method provided in a generate classes.
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().
typedef enum { Start, InProgress } WriteState;
Indicates status of writing a block.
static const LEIF::CString XmlNamespaceTag;
Static constant for the XML namespace prefix, xmlns.
static const LEIF::CString Blank;
Static constant for a space character.
static const LEIF::CString Colon;
Static constant for a colon, :.
static const LEIF::CString Newline;
Static constant for a newline character.
static const LEIF::CString EqualToAndQuotes;
Static constant for an equals sign with a trailing doublequote, =".
static const LEIF::CString Quotes;
Static constant for a doublequote character, ".
static const LEIF::CString TrueValue;
Static constant for a true value, 1.
static const LEIF::CString FalseValue;
Static constant for a false value, 0.
static const LEIF::CString StartTag;
Static constant for the character that starts a tag, <.
static const LEIF::CString EndTag;
Static constant for the character that ends a tag, >.
static const LEIF::CString StartEndTag;
Static constant for the character sequence that starts an end tag, </.
static const LEIF::CString UnpairedTag;
Static constant for the character sequence that ends the tag for an empty element, />.
static const LEIF::CString MarkupGt;
Static constant for the greater-than character entity, >.
static const LEIF::CString MarkupLt;
Static constant for the less-than character entity, <.
static const LEIF::CString MarkupAmpersand;
Static constant for the ampersand character entity, &.
static const LEIF::CString MarkupQuotes;
Static constant for the doublequote character entity, ".
static const LEIF::CString MarkupApos;
Static constant for the apostrophe character entity, '.
static const LEIF::CString MarkupCR;
Static constant for the ISO 10646 hexadecimal character number D, 
XmlWriter();
Default constructor.
virtual ~XmlWriter();
Destructor.
void addNamespace(const LEIF::XmlNamespace& ns);
Adds the namespace ns to the current namespace scope. The writer will not declare the namespace for children of the current element.
void decrementIndent();
Subtracts one from the current indentation level. Has no effect if the current indentation level is 0.
int getCurrentIndent() const;
Returns the current indentation level.
bool getIgnoreWhitespace() const;
Returns true if the writer is ignoring whitespace (that is, calls to writeIndentChars() and writeNewLine() do not write whitespace); otherwise, false.
bool getMustEscapeTextDefault() const;
Returns true if the writer escapes text. When mustEscapeText is true, the writer escapes text by replacing the characters <, &, and > with equivalent entity declarations. When mustEscapeText is false, the writer does not escape text. This value is initialized to false in the default constructor.
int 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 incrementIndent();
Adds one to the current indentation level.
void setCurrentIndent(int indent);
Sets the current indentation level to indent.
void setIgnoreWhitespace(bool ignore);
Sets the ignore whitespace attribute to the bool value ignore. This value is false by default.
void setMustEscapeTextDefault( bool escape );
Sets the bool value to define whether or not XML content is escaped. This value is initialized to false in the default constructor.
int setSizeOfIndent(int indentSize);
Sets the indentation size to indentSize, returns the previous indentation size. The indentation size sets the number of space characters the writer produces for each level of indentation.
void write(const LEIF::CString& text);
Writes text. The write() methods can write content either escaped or not. Because escaping text can be expensive, the default for mustEscapeText is false.
If you know that there are special XML characters in your text you will want to set mustEscapeText to true. When escaped, LEIF checks each character to see whether it is a special XML character and if so, the corresponding entity is substituted.
void
write(const LEIF::CString& 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.
Escaping text can be expensive if you know that the content contains no special characters. For this reason the default for escaping text is false.
void
writeAttribute(const LEIF::CString& name,
const LEIF::CString& value, bool mustEscapeText = true);
void
writeAttribute(const LEIF::XmlName& name,
const LEIF::CString& value, bool mustEscapeText = true);
Adds an attribute to the current element, using name for the name of the attribute and value for the value of the attribute. 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.
void
writeElementStart(const LEIF::XmlName& name,
const LEIF::XmlAttributeSet& attributes =
LEIF::XmlAttributeSet(), bool emptyElement = false);
Writes the start tag of an element when emptyElement is false, 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.
void writeElementEnd(const LEIF::XmlName& name);
Writes the closing tag of an element, removes any namespaces added while writing the element.
void 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 writeNewLine();
Writes a new line.
void
writeSimpleElement(const LEIF::CString& name,
const LEIF::CString& value,
const LEIF::CString& schemaType,
bool includeTypeAttribute = false);
void
writeSimpleElement(const LEIF::XmlName& name,
const LEIF::CString& value,
const LEIF::CString& schemaType,
bool includeTypeAttribute = false);
Writes an element. Uses name as the name of the element and value as the content of the element. If includeTypeAttribute is true, includes a XML Schema type attribute with the value of schemaType.
virtual void writeToSink(const LEIF::CString& text) = 0;
Pure virtual function. In a derived class, this function writes the contents of text to the underlying data sink.
virtual void writeToSink(const char* str, size_t len);
Pure virtual function. In a derived class, this function writes the contents of str limited to the length of len to the underlying data sink.
virtual void writeToSink(char c) = 0;
Pure virtual function. In a derived class, this function writes c to the underlying data sink.
virtual void flush() = 0;
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.
©2003-2005 Copyright Quovadx, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.