1 | // |
---|
2 | // NamespaceSupport.h |
---|
3 | // |
---|
4 | // $Id: //poco/1.3/XML/include/Poco/SAX/NamespaceSupport.h#1 $ |
---|
5 | // |
---|
6 | // Library: XML |
---|
7 | // Package: SAX |
---|
8 | // Module: SAX |
---|
9 | // |
---|
10 | // Namespace support for SAX2. |
---|
11 | // |
---|
12 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
---|
13 | // and Contributors. |
---|
14 | // |
---|
15 | // Permission is hereby granted, free of charge, to any person or organization |
---|
16 | // obtaining a copy of the software and accompanying documentation covered by |
---|
17 | // this license (the "Software") to use, reproduce, display, distribute, |
---|
18 | // execute, and transmit the Software, and to prepare derivative works of the |
---|
19 | // Software, and to permit third-parties to whom the Software is furnished to |
---|
20 | // do so, all subject to the following: |
---|
21 | // |
---|
22 | // The copyright notices in the Software and this entire statement, including |
---|
23 | // the above license grant, this restriction and the following disclaimer, |
---|
24 | // must be included in all copies of the Software, in whole or in part, and |
---|
25 | // all derivative works of the Software, unless such copies or derivative |
---|
26 | // works are solely in the form of machine-executable object code generated by |
---|
27 | // a source language processor. |
---|
28 | // |
---|
29 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
---|
30 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
---|
31 | // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT |
---|
32 | // SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE |
---|
33 | // FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, |
---|
34 | // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
---|
35 | // DEALINGS IN THE SOFTWARE. |
---|
36 | // |
---|
37 | |
---|
38 | |
---|
39 | #ifndef SAX_NamespaceSupport_INCLUDED |
---|
40 | #define SAX_NamespaceSupport_INCLUDED |
---|
41 | |
---|
42 | |
---|
43 | #include "Poco/XML/XML.h" |
---|
44 | #include "Poco/XML/XMLString.h" |
---|
45 | #include <set> |
---|
46 | #include <map> |
---|
47 | #include <vector> |
---|
48 | |
---|
49 | |
---|
50 | namespace Poco { |
---|
51 | namespace XML { |
---|
52 | |
---|
53 | |
---|
54 | class XML_API NamespaceSupport |
---|
55 | /// Encapsulate Namespace logic for use by SAX drivers. |
---|
56 | /// This class encapsulates the logic of Namespace processing: |
---|
57 | /// it tracks the declarations currently in force for each context and |
---|
58 | /// automatically processes qualified XML 1.0 names into their Namespace |
---|
59 | /// parts; it can also be used in reverse for generating |
---|
60 | /// XML 1.0 from Namespaces. |
---|
61 | /// Namespace support objects are reusable, but the reset method |
---|
62 | /// must be invoked between each session. |
---|
63 | { |
---|
64 | public: |
---|
65 | typedef std::set<XMLString> PrefixSet; |
---|
66 | |
---|
67 | NamespaceSupport(); |
---|
68 | /// Creates a NamespaceSupport object. |
---|
69 | |
---|
70 | ~NamespaceSupport(); |
---|
71 | /// Destroys a NamespaceSupport object. |
---|
72 | |
---|
73 | bool declarePrefix(const XMLString& prefix, const XMLString& namespaceURI); |
---|
74 | /// Declare a Namespace prefix. All prefixes must be declared before they are |
---|
75 | /// referenced. For example, a SAX driver (parser) would scan an element's attributes |
---|
76 | /// in two passes: first for namespace declarations, then a second pass using |
---|
77 | /// processName() to interpret prefixes against (potentially redefined) prefixes. |
---|
78 | /// |
---|
79 | /// This method declares a prefix in the current Namespace context; the prefix |
---|
80 | /// will remain in force until this context is popped, unless it is shadowed |
---|
81 | /// in a descendant context. |
---|
82 | /// |
---|
83 | /// To declare the default element Namespace, use the empty string as the prefix. |
---|
84 | /// |
---|
85 | /// Note that you must not declare a prefix after you've pushed and popped another |
---|
86 | /// Namespace context, or treated the declarations phase as complete by processing |
---|
87 | /// a prefixed name. |
---|
88 | /// |
---|
89 | /// Returns true if the prefix was legal, false otherwise. |
---|
90 | |
---|
91 | bool undeclarePrefix(const XMLString& prefix); |
---|
92 | /// Remove the given namespace prefix. |
---|
93 | |
---|
94 | void getDeclaredPrefixes(PrefixSet& prefixes) const; |
---|
95 | /// Return an enumeration of all prefixes declared in this context. |
---|
96 | /// |
---|
97 | /// The empty (default) prefix will be included in this enumeration; note that |
---|
98 | /// this behaviour differs from that of getPrefix(java.lang.String) and getPrefixes(). |
---|
99 | |
---|
100 | const XMLString& getPrefix(const XMLString& namespaceURI) const; |
---|
101 | /// Return one of the prefixes mapped to a Namespace URI. |
---|
102 | /// |
---|
103 | /// If more than one prefix is currently mapped to the same URI, this method |
---|
104 | /// will make an arbitrary selection; if you want all of the prefixes, use the |
---|
105 | /// getPrefixes() method instead. |
---|
106 | |
---|
107 | bool isMapped(const XMLString& namespaceURI) const; |
---|
108 | /// Returns true if the given namespaceURI has been mapped to a prefix, |
---|
109 | /// false otherwise. |
---|
110 | |
---|
111 | void getPrefixes(PrefixSet& prefixes) const; |
---|
112 | /// Return an enumeration of all prefixes whose declarations are active in the |
---|
113 | /// current context. This includes declarations from parent contexts that have |
---|
114 | /// not been overridden. |
---|
115 | /// |
---|
116 | /// Note: if there is a default prefix, it will not be returned in this enumeration; |
---|
117 | /// check for the default prefix using the getURI with an argument of "". |
---|
118 | |
---|
119 | void getPrefixes(const XMLString& namespaceURI, PrefixSet& prefixes) const; |
---|
120 | /// Return an enumeration of all prefixes for a given URI whose declarations |
---|
121 | /// are active in the current context. This includes declarations from parent |
---|
122 | /// contexts that have not been overridden. |
---|
123 | /// |
---|
124 | /// This method returns prefixes mapped to a specific Namespace URI. The xml: |
---|
125 | /// prefix will be included. If you want only one prefix that's mapped to the |
---|
126 | /// Namespace URI, and you don't care which one you get, use the getPrefix() method |
---|
127 | /// instead. |
---|
128 | /// |
---|
129 | /// Note: the empty (default) prefix is never included in this enumeration; |
---|
130 | /// to check for the presence of a default Namespace, use the getURI() method |
---|
131 | /// with an argument of "". |
---|
132 | |
---|
133 | const XMLString& getURI(const XMLString& prefix) const; |
---|
134 | /// Look up a prefix and get the currently-mapped Namespace URI. |
---|
135 | /// |
---|
136 | /// This method looks up the prefix in the current context. Use the empty string |
---|
137 | /// ("") for the default Namespace. |
---|
138 | |
---|
139 | void pushContext(); |
---|
140 | /// Start a new Namespace context. The new context will automatically inherit |
---|
141 | /// the declarations of its parent context, but it will also keep track of which |
---|
142 | /// declarations were made within this context. |
---|
143 | /// |
---|
144 | /// Event callback code should start a new context once per element. This means |
---|
145 | /// being ready to call this in either of two places. For elements that don't |
---|
146 | /// include namespace declarations, the ContentHandler::startElement() callback |
---|
147 | /// is the right place. For elements with such a declaration, it'd done in the |
---|
148 | /// first ContentHandler::startPrefixMapping() callback. A boolean flag can be |
---|
149 | /// used to track whether a context has been started yet. When either of those |
---|
150 | /// methods is called, it checks the flag to see if a new context needs to be |
---|
151 | /// started. If so, it starts the context and sets the flag. After |
---|
152 | /// ContentHandler::startElement() does that, it always clears the flag. |
---|
153 | /// |
---|
154 | /// Normally, SAX drivers would push a new context at the beginning of each |
---|
155 | /// XML element. Then they perform a first pass over the attributes to process |
---|
156 | /// all namespace declarations, making ContentHandler::startPrefixMapping() callbacks. |
---|
157 | /// Then a second pass is made, to determine the namespace-qualified names for |
---|
158 | /// all attributes and for the element name. Finally all the information for |
---|
159 | /// the ContentHandler::startElement() callback is available, so it can then |
---|
160 | /// be made. |
---|
161 | /// |
---|
162 | /// The Namespace support object always starts with a base context already in |
---|
163 | /// force: in this context, only the "xml" prefix is declared. |
---|
164 | |
---|
165 | void popContext(); |
---|
166 | /// Revert to the previous Namespace context. |
---|
167 | /// |
---|
168 | /// Normally, you should pop the context at the end of each XML element. After |
---|
169 | /// popping the context, all Namespace prefix mappings that were previously |
---|
170 | /// in force are restored. |
---|
171 | /// |
---|
172 | /// You must not attempt to declare additional Namespace prefixes after popping |
---|
173 | /// a context, unless you push another context first. |
---|
174 | |
---|
175 | bool processName(const XMLString& qname, XMLString& namespaceURI, XMLString& localName, bool isAttribute) const; |
---|
176 | /// Process a raw XML 1.0 name. |
---|
177 | /// This method processes a raw XML 1.0 name in the current context |
---|
178 | /// by removing the prefix and looking it up among the |
---|
179 | /// prefixes currently declared. The result will be returned in |
---|
180 | /// namespaceURI and localName. |
---|
181 | /// If the raw name has a prefix that has not been declared, then the return |
---|
182 | /// value will be false, otherwise true. |
---|
183 | /// |
---|
184 | /// Note that attribute names are processed differently than element names: |
---|
185 | /// an unprefixed element name will received the |
---|
186 | /// default Namespace (if any), while an unprefixed element name will not. |
---|
187 | |
---|
188 | void reset(); |
---|
189 | /// Reset this Namespace support object for reuse. |
---|
190 | /// |
---|
191 | /// It is necessary to invoke this method before reusing the Namespace support |
---|
192 | /// object for a new session. If namespace declaration URIs are to be supported, |
---|
193 | /// that flag must also be set to a non-default value. |
---|
194 | /// Reset this Namespace support object for reuse. |
---|
195 | |
---|
196 | static const XMLString XML_NAMESPACE; |
---|
197 | static const XMLString XML_NAMESPACE_PREFIX; |
---|
198 | static const XMLString XMLNS_NAMESPACE; |
---|
199 | static const XMLString XMLNS_NAMESPACE_PREFIX; |
---|
200 | |
---|
201 | private: |
---|
202 | NamespaceSupport(const NamespaceSupport&); |
---|
203 | NamespaceSupport& operator = (const NamespaceSupport&); |
---|
204 | |
---|
205 | typedef std::map<XMLString, XMLString> Context; |
---|
206 | typedef std::vector<Context> ContextVec; |
---|
207 | |
---|
208 | ContextVec _contexts; |
---|
209 | |
---|
210 | static const XMLString EMPTY_STRING; |
---|
211 | }; |
---|
212 | |
---|
213 | |
---|
214 | } } // namespace Poco::XML |
---|
215 | |
---|
216 | |
---|
217 | #endif // SAX_NamespaceSupport_INCLUDED |
---|