1//
2// CDATASection.h
3//
4// Library: XML
5// Package: DOM
6// Module: DOM
7//
8// Definition of the DOM CDATASection class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef DOM_CDATASection_INCLUDED
18#define DOM_CDATASection_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/DOM/Text.h"
23
24
25namespace Poco {
26namespace XML {
27
28
29class XML_API CDATASection: public Text
30 /// CDATA sections are used to escape blocks of text containing characters that
31 /// would otherwise be regarded as markup. The only delimiter that is recognized
32 /// in a CDATA section is the "]]>" string that ends the CDATA section. CDATA
33 /// sections cannot be nested. Their primary purpose is for including material
34 /// such as XML fragments, without needing to escape all the delimiters.
35 ///
36 /// The DOMString attribute of the Text node holds the text that is contained
37 /// by the CDATA section. Note that this may contain characters that need to
38 /// be escaped outside of CDATA sections and that, depending on the character
39 /// encoding ("charset") chosen for serialization, it may be impossible to write
40 /// out some characters as part of a CDATA section.
41 ///
42 /// The CDATASection interface inherits from the CharacterData interface through
43 /// the Text interface. Adjacent CDATASection nodes are not merged by use of
44 /// the normalize method on the Element interface.
45 ///
46 /// Note: Because no markup is recognized within a CDATASection, character numeric
47 /// references cannot be used as an escape mechanism when serializing. Therefore,
48 /// action needs to be taken when serializing a CDATASection with a character
49 /// encoding where some of the contained characters cannot be represented. Failure
50 /// to do so would not produce well-formed XML.
51 /// One potential solution in the serialization process is to end the CDATA
52 /// section before the character, output the character using a character reference
53 /// or entity reference, and open a new CDATA section for any further characters
54 /// in the text node. Note, however, that some code conversion libraries at
55 /// the time of writing do not return an error or exception when a character
56 /// is missing from the encoding, making the task of ensuring that data is not
57 /// corrupted on serialization more difficult.
58{
59public:
60 // Text
61 Text* splitText(unsigned long offset);
62
63 // Node
64 const XMLString& nodeName() const;
65 unsigned short nodeType() const;
66
67protected:
68 CDATASection(Document* pOwnerDocument, const XMLString& data);
69 CDATASection(Document* pOwnerDocument, const CDATASection& sec);
70 ~CDATASection();
71
72 Node* copyNode(bool deep, Document* pOwnerDocument) const;
73
74private:
75 static const XMLString NODE_NAME;
76
77 friend class Document;
78};
79
80
81} } // namespace Poco::XML
82
83
84#endif // DOM_CDATASection_INCLUDED
85