Poco::XML

class XMLWriter

File Information

Library: XML
Package: XML
Header: Poco/XML/XMLWriter.h

Description

This class serializes SAX2 ContentHandler, LexicalHandler and DTDHandler events back into a stream.

Various consistency checks are performed on the written data (i.e. there must be exactly one root element and every startElement() must have a matching endElement()).

The XMLWriter supports optional pretty-printing of the serialized XML. Note, however, that pretty-printing XML data alters the information set of the document being written, since in XML all whitespace is potentially relevant to an application.

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes.

If the client does not provide namespace prefixes (either by specifying them as part of the qualified name given to startElement(), or by calling startPrefixMapping()), the XMLWriter automatically generates namespace prefixes in the form ns1, ns2, etc.

Inheritance

Direct Base Classes: ContentHandler, LexicalHandler, DTDHandler

All Base Classes: ContentHandler, DTDHandler, LexicalHandler

Member Summary

Member Functions: addAttributes, addNamespaceAttributes, characters, closeStartTag, comment, dataElement, declareAttributeNamespaces, declareNamespaces, depth, emptyElement, endCDATA, endDTD, endDocument, endElement, endEntity, endFragment, endPrefixMapping, getIndent, getNewLine, ignorableWhitespace, isNamespaceMapped, nameToString, notationDecl, prettyPrint, processingInstruction, rawCharacters, setDocumentLocator, setIndent, setNewLine, skippedEntity, startCDATA, startDTD, startDocument, startElement, startEntity, startFragment, startPrefixMapping, uniquePrefix, unparsedEntityDecl, writeAttributes, writeCanonicalStartElement, writeEndElement, writeIndent, writeMarkup, writeName, writeNewLine, writeStartElement, writeXML, writeXMLDeclaration

Inherited Functions: characters, comment, endCDATA, endDTD, endDocument, endElement, endEntity, endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, setDocumentLocator, skippedEntity, startCDATA, startDTD, startDocument, startElement, startEntity, startPrefixMapping, unparsedEntityDecl

Types

AttributeMap protected

typedef std::map < XMLString, XMLString > AttributeMap;

CanonicalAttributeMap protected

typedef std::map < XMLString, std::pair < XMLString, XMLString >> CanonicalAttributeMap;

Enumerations

Options

CANONICAL = 0x00

Do not write an XML declaration (default).

CANONICAL_XML = 0x01

Enables basic support for Canonical XML:

  • do not write an XML declaration
  • do not use special empty element syntax
  • set the New Line character to NEWLINE_LF
  • write namespace declarations and attributes in canonical order
  • use default namespace as much as possible

WRITE_XML_DECLARATION = 0x02

Write an XML declaration.

PRETTY_PRINT = 0x04

Pretty-print XML markup.

PRETTY_PRINT_ATTRIBUTES = 0x08

Write each attribute on a separate line. PRETTY_PRINT must be specified as well.

Constructors

XMLWriter

XMLWriter(
    XMLByteOutputStream & str,
    int options
);

Creates the XMLWriter and sets the specified options.

The resulting stream will be UTF-8 encoded.

XMLWriter

XMLWriter(
    XMLByteOutputStream & str,
    int options,
    const std::string & encodingName,
    Poco::TextEncoding & textEncoding
);

Creates the XMLWriter and sets the specified options.

The encoding is reflected in the XML declaration. The caller is responsible for that the given encodingName matches with the given textEncoding.

XMLWriter

XMLWriter(
    XMLByteOutputStream & str,
    int options,
    const std::string & encodingName,
    Poco::TextEncoding * pTextEncoding
);

Creates the XMLWriter and sets the specified options.

The encoding is reflected in the XML declaration. The caller is responsible for that the given encodingName matches with the given textEncoding. If pTextEncoding is null, the given encodingName is ignored and the default UTF-8 encoding is used.

Destructor

~XMLWriter virtual

~XMLWriter();

Destroys the XMLWriter.

Member Functions

characters virtual

void characters(
    const XMLChar ch[],
    int start,
    int length
);

Writes XML character data. Quotes, ampersand's, less-than and greater-than signs are escaped, unless a CDATA section has been opened by calling startCDATA().

The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).

See also: Poco::XML::ContentHandler::characters()

characters

void characters(
    const XMLString & str
);

Writes XML character data. Quotes, ampersand's, less-than and greater-than signs are escaped, unless a CDATA section has been opened by calling startCDATA().

The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).

comment virtual

void comment(
    const XMLChar ch[],
    int start,
    int length
);

Writes a comment.

See also: Poco::XML::LexicalHandler::comment()

dataElement

void dataElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname,
    const XMLString & data,
    const XMLString & attr1 = XMLString (),
    const XMLString & value1 = XMLString (),
    const XMLString & attr2 = XMLString (),
    const XMLString & value2 = XMLString (),
    const XMLString & attr3 = XMLString (),
    const XMLString & value3 = XMLString ()
);

Writes a data element in the form <name attr1="value1"...>data</name>.

depth inline

int depth() const;

Return the number of nested XML elements.

Will be -1 if no document or fragment has been started, 0 if the document or fragment has been started, 1 if the document element has been written and > 1 for every element nested within the document element.

emptyElement

void emptyElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname
);

Writes an empty XML element tag (<elem/>).

emptyElement

void emptyElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname,
    const Attributes & attributes
);

Writes an empty XML element tag with the given attributes (<elem attr1="value1"... />).

endCDATA virtual

void endCDATA();

Writes the ]]> string that ends a CDATA section.

See also: Poco::XML::LexicalHandler::endCDATA()

endDTD virtual

void endDTD();

Writes the closing characters of a DTD declaration.

See also: Poco::XML::LexicalHandler::endDTD()

endDocument virtual

void endDocument();

Checks that all elements are closed and prints a final newline.

See also: Poco::XML::ContentHandler::endDocument()

endElement virtual

void endElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname
);

Writes an XML end element tag.

Throws an exception if the name of doesn't match the one of the most recent startElement().

See also: Poco::XML::ContentHandler::endElement()

endEntity virtual

void endEntity(
    const XMLString & name
);

Does nothing.

See also: Poco::XML::LexicalHandler::endEntity()

endFragment

void endFragment();

Checks that all elements are closed and prints a final newline.

endPrefixMapping virtual

void endPrefixMapping(
    const XMLString & prefix
);

End the scope of a prefix-URI mapping.

See also: Poco::XML::ContentHandler::endPrefixMapping()

getIndent

const std::string & getIndent() const;

Returns the string used for one indentation step.

getNewLine

const std::string & getNewLine() const;

Returns the line ending currently in use.

ignorableWhitespace virtual

void ignorableWhitespace(
    const XMLChar ch[],
    int start,
    int length
);

Writes whitespace characters by simply passing them to characters().

See also: Poco::XML::ContentHandler::ignorableWhitespace()

isNamespaceMapped

bool isNamespaceMapped(
    const XMLString & namespc
) const;

Returns true if the given namespace has been mapped to a prefix in the current element or its ancestors.

notationDecl virtual

void notationDecl(
    const XMLString & name,
    const XMLString * publicId,
    const XMLString * systemId
);

See also: Poco::XML::DTDHandler::notationDecl()

processingInstruction virtual

void processingInstruction(
    const XMLString & target,
    const XMLString & data
);

Writes a processing instruction.

See also: Poco::XML::ContentHandler::processingInstruction()

rawCharacters

void rawCharacters(
    const XMLString & str
);

Writes the characters in the given string as they are. The caller is responsible for escaping characters as necessary to produce valid XML.

The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).

setDocumentLocator virtual

void setDocumentLocator(
    const Locator * loc
);

Currently unused.

See also: Poco::XML::ContentHandler::setDocumentLocator()

setIndent

void setIndent(
    const std::string & indent
);

Sets the string used for one indentation step.

The default is a single TAB character. The given string should only contain TAB or SPACE characters (e.g., a single TAB character, or two to four SPACE characters).

setNewLine

void setNewLine(
    const std::string & newLineCharacters
);

Sets the line ending for the resulting XML file.

Possible values are:

skippedEntity virtual

void skippedEntity(
    const XMLString & name
);

Does nothing.

See also: Poco::XML::ContentHandler::skippedEntity()

startCDATA virtual

void startCDATA();

Writes the [CDATA[ string that begins a CDATA section. Use characters() to write the actual character data.

See also: Poco::XML::LexicalHandler::startCDATA()

startDTD virtual

void startDTD(
    const XMLString & name,
    const XMLString & publicId,
    const XMLString & systemId
);

Writes a DTD declaration.

See also: Poco::XML::LexicalHandler::startDTD()

startDocument virtual

void startDocument();

Writes a generic XML declaration to the stream. If a document type has been set (see SetDocumentType), a DOCTYPE declaration is also written.

See also: Poco::XML::ContentHandler::startDocument()

startElement virtual

void startElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname,
    const Attributes & attributes
);

Writes an XML start element tag.

Namespaces are handled as follows.

  1. If a qname, but no namespaceURI and localName are given, the qname is taken as element name.
  2. If a namespaceURI and a localName, but no qname is given, and the given namespaceURI has been declared earlier, the namespace prefix for the given namespaceURI together with the localName is taken as element name. If the namespace has not been declared, a prefix in the form "ns1", "ns2", etc. is generated and the namespace is declared with the generated prefix.
  3. If all three are given, and the namespace given in namespaceURI has not been declared, it is declared now. Otherwise, see 2.

See also: Poco::XML::ContentHandler::startElement()

startElement

void startElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname
);

Writes an XML start element tag with no attributes. See the other startElement() method for more information.

startEntity virtual

void startEntity(
    const XMLString & name
);

Does nothing.

See also: Poco::XML::LexicalHandler::startEntity()

startFragment

void startFragment();

Use this instead of StartDocument() if you want to write a fragment rather than a document (no XML declaration and more than one "root" element allowed).

startPrefixMapping virtual

void startPrefixMapping(
    const XMLString & prefix,
    const XMLString & namespaceURI
);

Begin the scope of a prefix-URI Namespace mapping. A namespace declaration is written with the next element.

See also: Poco::XML::ContentHandler::startPrefixMapping()

uniquePrefix

XMLString uniquePrefix();

Creates and returns a unique namespace prefix that can be used with startPrefixMapping().

unparsedEntityDecl virtual

void unparsedEntityDecl(
    const XMLString & name,
    const XMLString * publicId,
    const XMLString & systemId,
    const XMLString & notationName
);

See also: Poco::XML::DTDHandler::unparsedEntityDecl()

addAttributes protected

void addAttributes(
    AttributeMap & attributeMap,
    const Attributes & attributes,
    const XMLString & elementNamespaceURI
);

addAttributes protected

void addAttributes(
    CanonicalAttributeMap & attributeMap,
    const Attributes & attributes,
    const XMLString & elementNamespaceURI
);

addNamespaceAttributes protected

void addNamespaceAttributes(
    AttributeMap & attributeMap
);

addNamespaceAttributes protected

void addNamespaceAttributes(
    CanonicalAttributeMap & attributeMap
);

closeStartTag protected

void closeStartTag();

declareAttributeNamespaces protected

void declareAttributeNamespaces(
    const Attributes & attributes
);

declareNamespaces protected

void declareNamespaces(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname,
    const Attributes & attributes
);

nameToString protected static

static std::string nameToString(
    const XMLString & localName,
    const XMLString & qname
);

prettyPrint protected

void prettyPrint() const;

writeAttributes protected

void writeAttributes(
    const AttributeMap & attributeMap
);

writeAttributes protected

void writeAttributes(
    const CanonicalAttributeMap & attributeMap
);

writeCanonicalStartElement protected

void writeCanonicalStartElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname,
    const Attributes & attributes
);

writeEndElement protected

void writeEndElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname
);

writeIndent protected

void writeIndent() const;

writeIndent protected

void writeIndent(
    int indent
) const;

writeMarkup protected

void writeMarkup(
    const std::string & str
) const;

writeName protected

void writeName(
    const XMLString & prefix,
    const XMLString & localName
);

writeNewLine protected

void writeNewLine() const;

writeStartElement protected

void writeStartElement(
    const XMLString & namespaceURI,
    const XMLString & localName,
    const XMLString & qname,
    const Attributes & attributes
);

writeXML protected

void writeXML(
    const XMLString & str
) const;

writeXML protected

void writeXML(
    XMLChar ch
) const;

writeXMLDeclaration protected

void writeXMLDeclaration();

Variables

NEWLINE_CR static

static const std::string NEWLINE_CR;

NEWLINE_CRLF static

static const std::string NEWLINE_CRLF;

NEWLINE_DEFAULT static

static const std::string NEWLINE_DEFAULT;

NEWLINE_LF static

static const std::string NEWLINE_LF;