rwsf::XmlWriter

Does not inherit

• Local Index
• Header File
• Description
• Public Constructors
• Public Destructors
• Public Member Functions
• Protected Member Functions

Members

addNamespace() decrementIndent() flush() getCurrentIndent() getIgnoreWhitespace() getMustEscapeTextDefault()

getSizeOfIndent() incrementIndent() setCurrentIndent() setIgnoreWhitespace() setMustEscapeTextDefault() setSizeOfIndent()

write() writeAttribute() writeElementEnd() writeElementStart() writeIndentChars() writeNewLine()

writeSimpleElement() writeToSink() 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 HydraAgent.

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 HydraAgent 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().

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 char * textData,
    size_t textLength,
    bool mustEscapeText);

Writes textData. 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, HydraSCA 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);

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
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 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
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 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
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 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
writeElementEnd(const rwsf::XmlName & name);

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

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
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);

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.

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

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.

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.

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

Pure virtual function. In a derived class, this function writes the contents of text to the underlying data sink.

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

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.

void
writeToSink(char c) = 0;

Pure virtual function. In a derived class, this function writes c to the underlying data sink.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.