rwsf::XmlWriter

• Local Index
• Header File
• Description
• Public Typedefs
• Static Constants
• Public Constructor
• Public Destructor:
• Public Member Functions:
• Protected Member Functions
• See Also

Members

addNamespace() Blank Colon decrementIndent() EndTag EqualToAndQuotes FalseValue flush() getCurrentIndent() getIgnoreWhitespace() getMustEscapeTextDefault()

getSizeOfIndent() incrementIndent() MarkupAmpersand MarkupApos MarkupCR MarkupGt MarkupLt MarkupQuotes Newline Quotes setCurrentIndent()

setIgnoreWhitespace() setMustEscapeTextDefault() setSizeOfIndent() StartEndTag StartTag TrueValue UnpairedTag write() writeAttribute() writeElementEnd() writeElementStart()

writeIndentChars() writeNewLine() writeSimpleElement() WriteState writeToSink() XmlNamespaceTag XmlWriter() ~XmlWriter()

#include <rwsf/core/XmlWriter.h>

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 writer to the marshal() method of a class generated by Hydra.

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 Hydra 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 std::string XmlNamespaceTag;

Static constant for the XML namespace prefix, xmlns.

static const std::string Blank;

Static constant for a space character.

static const std::string Colon;

Static constant for a colon, :.

static const std::string Newline;

Static constant for a newline character.

static const std::string EqualToAndQuotes;

Static constant for an equals sign with a trailing doublequote, =".

static const std::string Quotes;

Static constant for a doublequote character, ".

static const std::string TrueValue;

Static constant for a true value, 1.

static const std::string FalseValue;

Static constant for a false value, 0.

static const std::string StartTag;

Static constant for the character that starts a tag, <.

static const std::string EndTag;

Static constant for the character that ends a tag, >.

static const std::string StartEndTag;

Static constant for the character sequence that starts an end tag, </.

static const std::string UnpairedTag;

Static constant for the character sequence that ends the tag for an empty element, />.

static const std::string MarkupGt;

Static constant for the greater-than character entity, &gt;.

static const std::string MarkupLt;

Static constant for the less-than character entity, &lt;.

static const std::string MarkupAmpersand;

Static constant for the ampersand character entity, &amp;.

static const std::string MarkupQuotes;

Static constant for the doublequote character entity, &quot;.

static const std::string MarkupApos;

Static constant for the apostrophe character entity, &apos;.

static const std::string        MarkupCR;

Static constant for the ISO 10646 hexadecimal character number D, &#xD;

XmlWriter();

Default constructor.

virtual ~XmlWriter();

Destructor.

void
addNamespace(const rwsf::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 std::string& 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, Hydra checks each character to see whether it is a special XML character and if so, the corresponding entity is substituted.

void
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.

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 std::string& name,
    const std::string& value, bool mustEscapeText = true);
void
writeAttribute(const rwsf::XmlName& name,
    const std::string& 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 rwsf::XmlName& name,
    const rwsf::XmlAttributeSet& attributes =
    rwsf::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 rwsf::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 std::string& name,
    const std::string& value,
    const std::string& schemaType,
    bool includeTypeAttribute = false);
void
writeSimpleElement(const rwsf::XmlName& name,
    const std::string& value,
    const std::string& 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 std::string& 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.

rwsf::XmlStringWriter

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks and HydraSDO is a 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.