class Poco::XML::XMLWriter

Overview

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

#include <XMLWriter.h>

class XMLWriter:
    public Poco::XML::ContentHandler,
    public Poco::XML::LexicalHandler,
    public Poco::XML::DTDHandler
{
public:
    // enums

    enum Options;

    // structs

    struct Namespace;

    // fields

    static const std::string NEWLINE_DEFAULT;
    static const std::string NEWLINE_CR;
    static const std::string NEWLINE_CRLF;
    static const std::string NEWLINE_LF;

    // construction

    XMLWriter(
        XMLByteOutputStream& str,
        int options
        );

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

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

    // methods

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

    const std::string&
    getNewLine() const;

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

    const std::string&
    getIndent() const;

    virtual
    void
    setDocumentLocator(const Locator* loc);

    virtual
    void
    startDocument();

    virtual
    void
    endDocument();

    void
    startFragment();

    void
    endFragment();

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

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

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

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

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

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

    void
    characters(const XMLString& str);

    void
    rawCharacters(const XMLString& str);

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

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

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

    virtual
    void
    endPrefixMapping(const XMLString& prefix);

    virtual
    void
    skippedEntity(const XMLString& name);

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

    virtual
    void
    startCDATA();

    virtual
    void
    endCDATA();

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

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

    virtual
    void
    endDTD();

    virtual
    void
    startEntity(const XMLString& name);

    virtual
    void
    endEntity(const XMLString& name);

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

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

    XMLString
    uniquePrefix();

    bool
    isNamespaceMapped(const XMLString& namespc) const;

    int
    depth() const;

protected:
    // typedefs

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

    // methods

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

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

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

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

    void
    writeXML(const XMLString& str) const;

    void
    writeXML(XMLChar ch) const;

    void
    writeNewLine() const;

    void
    writeIndent() const;

    void
    writeIndent(int indent) const;

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

    void
    writeXMLDeclaration();

    void
    closeStartTag();

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

    void
    declareAttributeNamespaces(const Attributes& attributes);

    void
    addNamespaceAttributes(AttributeMap& attributeMap);

    void
    addNamespaceAttributes(CanonicalAttributeMap& attributeMap);

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

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

    void
    writeAttributes(const AttributeMap& attributeMap);

    void
    writeAttributes(const CanonicalAttributeMap& attributeMap);

    void
    prettyPrint() const;

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

Inherited Members

public:
    // methods

    virtual
    void
    setDocumentLocator(const Locator* loc) = 0;

    virtual
    void
    startDocument() = 0;

    virtual
    void
    endDocument() = 0;

    virtual
    void
    startElement(
        const XMLString& uri,
        const XMLString& localName,
        const XMLString& qname,
        const Attributes& attrList
        ) = 0;

    virtual
    void
    endElement(
        const XMLString& uri,
        const XMLString& localName,
        const XMLString& qname
        ) = 0;

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

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

    virtual
    void
    processingInstruction(
        const XMLString& target,
        const XMLString& data
        ) = 0;

    virtual
    void
    startPrefixMapping(
        const XMLString& prefix,
        const XMLString& uri
        ) = 0;

    virtual
    void
    endPrefixMapping(const XMLString& prefix) = 0;

    virtual
    void
    skippedEntity(const XMLString& name) = 0;

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

    virtual
    void
    endDTD() = 0;

    virtual
    void
    startEntity(const XMLString& name) = 0;

    virtual
    void
    endEntity(const XMLString& name) = 0;

    virtual
    void
    startCDATA() = 0;

    virtual
    void
    endCDATA() = 0;

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

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

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

Detailed Documentation

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.

Construction

XMLWriter(
    XMLByteOutputStream& str,
    int options
    )

Creates the XMLWriter and sets the specified options.

The resulting stream will be UTF-8 encoded.

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

Methods

void
setNewLine(const std::string& newLineCharacters)

Sets the line ending for the resulting XML file.

Possible values are:

* NEWLINE_DEFAULT (whatever is appropriate for the current platform)
* NEWLINE_CRLF    (Windows),
* NEWLINE_LF      (Unix),
* NEWLINE_CR      (Macintosh)

const std::string&
getNewLine() const

Returns the line ending currently in use.

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

const std::string&
getIndent() const

Returns the string used for one indentation step.

virtual
void
setDocumentLocator(const Locator* loc)

Currently unused.

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.

virtual
void
endDocument()

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

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

void
endFragment()

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

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.

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.

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

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

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

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”… />).

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

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

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

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

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

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

Writes a processing instruction.

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.

virtual
void
endPrefixMapping(const XMLString& prefix)

End the scope of a prefix-URI mapping.

virtual
void
skippedEntity(const XMLString& name)

Does nothing.

virtual
void
startCDATA()

Writes the <![CDATA[ string that begins a CDATA section.

Use characters() to write the actual character data.

virtual
void
endCDATA()

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

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

Writes a comment.

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

Writes a DTD declaration.

virtual
void
endDTD()

Writes the closing characters of a DTD declaration.

virtual
void
startEntity(const XMLString& name)

Does nothing.

virtual
void
endEntity(const XMLString& name)

Does nothing.

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

Receive notification of a notation declaration event.

It is up to the application to record the notation for later reference, if necessary; notations may appear as attribute values and in unparsed entity declarations, and are sometime used with processing instruction target names.

At least one of publicId and systemId must be non-null. If a system identifier is present, and it is a URL, the SAX parser must resolve it fully before passing it to the application through this event.

There is no guarantee that the notation declaration will be reported before any unparsed entities that use it.

Note that publicId and systemId maybe null, therefore we pass a pointer rather than a reference.

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

Receive notification of an unparsed entity declaration event.

Note that the notation name corresponds to a notation reported by the notationDecl event. It is up to the application to record the entity for later reference, if necessary; unparsed entities may appear as attribute values.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Note that publicId maybe null, therefore we pass a pointer rather than a reference.

XMLString
uniquePrefix()

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

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.

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.