1 | /* |
---|
2 | * Licensed to the Apache Software Foundation (ASF) under one or more |
---|
3 | * contributor license agreements. See the NOTICE file distributed with |
---|
4 | * this work for additional information regarding copyright ownership. |
---|
5 | * The ASF licenses this file to You under the Apache License, Version 2.0 |
---|
6 | * (the "License"); you may not use this file except in compliance with |
---|
7 | * the License. You may obtain a copy of the License at |
---|
8 | * |
---|
9 | * http://www.apache.org/licenses/LICENSE-2.0 |
---|
10 | * |
---|
11 | * Unless required by applicable law or agreed to in writing, software |
---|
12 | * distributed under the License is distributed on an "AS IS" BASIS, |
---|
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
---|
14 | * See the License for the specific language governing permissions and |
---|
15 | * limitations under the License. |
---|
16 | */ |
---|
17 | |
---|
18 | /* |
---|
19 | * $Id: XMLGrammarPool.hpp 568078 2007-08-21 11:43:25Z amassari $ |
---|
20 | */ |
---|
21 | |
---|
22 | #if !defined(XMLGRAMMARPOOL_HPP) |
---|
23 | #define XMLGRAMMARPOOL_HPP |
---|
24 | |
---|
25 | #include <xercesc/util/PlatformUtils.hpp> |
---|
26 | #include <xercesc/util/RefHashTableOf.hpp> |
---|
27 | #include <xercesc/util/XMemory.hpp> |
---|
28 | #include <xercesc/framework/psvi/XSModel.hpp> |
---|
29 | |
---|
30 | |
---|
31 | XERCES_CPP_NAMESPACE_BEGIN |
---|
32 | |
---|
33 | class Grammar; |
---|
34 | class XMLGrammarDescription; |
---|
35 | class DTDGrammar; |
---|
36 | class SchemaGrammar; |
---|
37 | class XMLDTDDescription; |
---|
38 | class XMLSchemaDescription; |
---|
39 | class XMLStringPool; |
---|
40 | class BinInputStream; |
---|
41 | class BinOutputStream; |
---|
42 | |
---|
43 | class XMLPARSER_EXPORT XMLGrammarPool : public XMemory |
---|
44 | { |
---|
45 | public : |
---|
46 | // ----------------------------------------------------------------------- |
---|
47 | /** @name Virtual destructor for derived classes */ |
---|
48 | // ----------------------------------------------------------------------- |
---|
49 | //@{ |
---|
50 | |
---|
51 | /** |
---|
52 | * virtual destructor |
---|
53 | * |
---|
54 | */ |
---|
55 | virtual ~XMLGrammarPool(){}; |
---|
56 | //@} |
---|
57 | |
---|
58 | // ----------------------------------------------------------------------- |
---|
59 | /** @name The Grammar Pool Interface */ |
---|
60 | // ----------------------------------------------------------------------- |
---|
61 | //@{ |
---|
62 | |
---|
63 | /** |
---|
64 | * cacheGrammar |
---|
65 | * |
---|
66 | * Provide the grammar pool with an opportunity |
---|
67 | * to cache the given grammar. If the pool does not choose to do so, |
---|
68 | * it should return false; otherwise, it should return true, so that |
---|
69 | * the caller knows whether the grammar has been adopted. |
---|
70 | * |
---|
71 | * @param gramToCache the Grammar to be cached in the grammar pool |
---|
72 | * @return true if the grammar pool has elected to cache the grammar (in which case |
---|
73 | * it is assumed to have adopted it); false if it does not cache it |
---|
74 | * |
---|
75 | */ |
---|
76 | virtual bool cacheGrammar(Grammar* const gramToCache) = 0; |
---|
77 | |
---|
78 | /** |
---|
79 | * retrieveGrammar |
---|
80 | * |
---|
81 | * @param gramDesc the Grammar Description used to search for grammar |
---|
82 | * cached in the grammar pool |
---|
83 | * |
---|
84 | */ |
---|
85 | virtual Grammar* retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0; |
---|
86 | |
---|
87 | |
---|
88 | /** |
---|
89 | * orphanGrammar |
---|
90 | * |
---|
91 | * grammar removed from the grammar pool and owned by the caller |
---|
92 | * |
---|
93 | * @param nameSpaceKey Key used to search for grammar in the grammar pool |
---|
94 | * @return the grammar that was removed from the pool (0 if none) |
---|
95 | */ |
---|
96 | virtual Grammar* orphanGrammar(const XMLCh* const nameSpaceKey) = 0; |
---|
97 | |
---|
98 | |
---|
99 | /** |
---|
100 | * Get an enumeration of the cached Grammars in the Grammar pool |
---|
101 | * |
---|
102 | * @return enumeration of the cached Grammars in Grammar pool |
---|
103 | */ |
---|
104 | virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0; |
---|
105 | |
---|
106 | /** |
---|
107 | * clear |
---|
108 | * |
---|
109 | * all grammars are removed from the grammar pool and deleted. |
---|
110 | * @return true if the grammar pool was cleared. false if it did not. |
---|
111 | */ |
---|
112 | virtual bool clear() = 0; |
---|
113 | |
---|
114 | /** |
---|
115 | * lockPool |
---|
116 | * |
---|
117 | * When this method is called by the application, the |
---|
118 | * grammar pool should stop adding new grammars to the cache. |
---|
119 | * This should result in the grammar pool being sharable |
---|
120 | * among parsers operating in different threads. |
---|
121 | * |
---|
122 | */ |
---|
123 | virtual void lockPool() = 0; |
---|
124 | |
---|
125 | /** |
---|
126 | * unlockPool |
---|
127 | * |
---|
128 | * After this method has been called, the grammar pool implementation |
---|
129 | * should return to its default behaviour when cacheGrammars(...) is called. |
---|
130 | * One effect, depending on the underlying implementation, is that the grammar pool |
---|
131 | * may no longer be thread-safe (even on read operations). |
---|
132 | * |
---|
133 | * For PSVI support any previous XSModel that was produced will be deleted. |
---|
134 | */ |
---|
135 | virtual void unlockPool() = 0; |
---|
136 | |
---|
137 | //@} |
---|
138 | |
---|
139 | // ----------------------------------------------------------------------- |
---|
140 | /** @name Factory interface */ |
---|
141 | // ----------------------------------------------------------------------- |
---|
142 | //@{ |
---|
143 | |
---|
144 | /** |
---|
145 | * createDTDGrammar |
---|
146 | * |
---|
147 | */ |
---|
148 | virtual DTDGrammar* createDTDGrammar() = 0; |
---|
149 | |
---|
150 | /** |
---|
151 | * createSchemaGrammar |
---|
152 | * |
---|
153 | */ |
---|
154 | virtual SchemaGrammar* createSchemaGrammar() = 0; |
---|
155 | |
---|
156 | /** |
---|
157 | * createDTDDescription |
---|
158 | * |
---|
159 | */ |
---|
160 | virtual XMLDTDDescription* createDTDDescription(const XMLCh* const systemId) = 0; |
---|
161 | /** |
---|
162 | * createSchemaDescription |
---|
163 | * |
---|
164 | */ |
---|
165 | virtual XMLSchemaDescription* createSchemaDescription(const XMLCh* const targetNamespace) = 0; |
---|
166 | |
---|
167 | //@} |
---|
168 | |
---|
169 | // ----------------------------------------------------------------------- |
---|
170 | /** @name schema component model support */ |
---|
171 | // ----------------------------------------------------------------------- |
---|
172 | //@{ |
---|
173 | |
---|
174 | /*** |
---|
175 | * Return an XSModel derived from the components of all SchemaGrammars |
---|
176 | * in the grammar pool. If the pool is locked, this should |
---|
177 | * be a thread-safe operation. It should return null if and only if |
---|
178 | * the pool is empty. |
---|
179 | * |
---|
180 | * Calling getXSModel() on an unlocked grammar pool may result in the |
---|
181 | * creation of a new XSModel with the old XSModel being deleted. The |
---|
182 | * function will return a different address for the XSModel if it has |
---|
183 | * changed. |
---|
184 | * |
---|
185 | * @deprecated (shouldn't use address to determine if XSModel changed) |
---|
186 | */ |
---|
187 | virtual XSModel *getXSModel() = 0; |
---|
188 | |
---|
189 | /*** |
---|
190 | * Return an XSModel derived from the components of all SchemaGrammars |
---|
191 | * in the grammar pool. If the pool is locked, this should |
---|
192 | * be a thread-safe operation. |
---|
193 | * |
---|
194 | * NOTE: The function should NEVER return NULL. If there are no grammars in |
---|
195 | * the pool it should return an XSModel containing the Schema for Schema. |
---|
196 | * |
---|
197 | * Calling getXSModel() on an unlocked grammar pool may result in the |
---|
198 | * creation of a new XSModel with the old XSModel being deleted. |
---|
199 | * The bool parameter will indicate if the XSModel was changed. |
---|
200 | * |
---|
201 | * For source code compatibility, default implementation is to say |
---|
202 | * XSModelWasChanged. |
---|
203 | */ |
---|
204 | virtual XSModel *getXSModel(bool& XSModelWasChanged) |
---|
205 | { |
---|
206 | XSModelWasChanged = true; |
---|
207 | return getXSModel(); |
---|
208 | } |
---|
209 | |
---|
210 | // @} |
---|
211 | |
---|
212 | // ----------------------------------------------------------------------- |
---|
213 | /** @name Getter */ |
---|
214 | // ----------------------------------------------------------------------- |
---|
215 | //@{ |
---|
216 | |
---|
217 | /** |
---|
218 | * getMemoryManager |
---|
219 | * |
---|
220 | */ |
---|
221 | inline MemoryManager* getMemoryManager() |
---|
222 | { |
---|
223 | return fMemMgr; |
---|
224 | } |
---|
225 | |
---|
226 | /** |
---|
227 | * Return an XMLStringPool for use by validation routines. |
---|
228 | * Implementations should not create a string pool on each call to this |
---|
229 | * method, but should maintain one string pool for all grammars |
---|
230 | * for which this pool is responsible. |
---|
231 | */ |
---|
232 | virtual XMLStringPool *getURIStringPool() = 0; |
---|
233 | //@} |
---|
234 | |
---|
235 | // ----------------------------------------------------------------------- |
---|
236 | /** serialization and deserialization support */ |
---|
237 | // ----------------------------------------------------------------------- |
---|
238 | |
---|
239 | /*** |
---|
240 | * |
---|
241 | * 1. Context: Serialize/Deserialize All Grammars In One Session |
---|
242 | * |
---|
243 | * Since it is common that a declaration in one grammar may reference |
---|
244 | * to definitions in other grammars, it is required to serialize those |
---|
245 | * related (or interdependent) grammars in to one persistent data store |
---|
246 | * in one serialization session (storing), and deserialize them from the |
---|
247 | * persistent data store in one deserialization session (loading) back |
---|
248 | * to the grammar pool. |
---|
249 | * |
---|
250 | * 2. Multiple serializations |
---|
251 | * |
---|
252 | * It is acceptable that client application requests more than one |
---|
253 | * grammar serialization on a particular grammar pool, to track the |
---|
254 | * different grammars cached, or for whatever reasons that client |
---|
255 | * application is interested in. |
---|
256 | * |
---|
257 | * 3. Multiple deserializations |
---|
258 | * |
---|
259 | * Request for grammar deserialization either after the grammar pool has |
---|
260 | * its own cached grammars, or request for more than one grammar |
---|
261 | * deserialization, may cause undesired and unpredictable consequence |
---|
262 | * and therefore client application shall be aware that individual |
---|
263 | * implementationis may NOT support this. |
---|
264 | * |
---|
265 | * However it is strongly recommended that the client application requests |
---|
266 | * no more than one grammar deserialization even a particular implementation |
---|
267 | * may allow multiple deserializations. |
---|
268 | * |
---|
269 | * 4. Locking |
---|
270 | * |
---|
271 | * Both serialization and deserialization requires to lock the grammar pool |
---|
272 | * before operation and unlock after operation. In the case the grammar pool |
---|
273 | * is locked by a third party, the request for serialization/deserialization |
---|
274 | * will NOT be entertained. |
---|
275 | * |
---|
276 | * 5. Versioning |
---|
277 | * |
---|
278 | * The Persistent data store has a version tag to be verified during |
---|
279 | * deserialization, thus a grammar pool may decide if it supports |
---|
280 | * a binary data created by a different release of Xerces. |
---|
281 | * |
---|
282 | * 6. Clean up |
---|
283 | * |
---|
284 | * The client application shall be aware that in the event of an exception |
---|
285 | * thrown due to a corrupted data store during deserialization, implementation |
---|
286 | * may not be able to clean up all resources allocated, and therefore it is |
---|
287 | * client application's responsibility to clean up those unreleased resources. |
---|
288 | * |
---|
289 | * |
---|
290 | */ |
---|
291 | virtual void serializeGrammars(BinOutputStream* const) = 0; |
---|
292 | virtual void deserializeGrammars(BinInputStream* const) = 0; |
---|
293 | |
---|
294 | /* |
---|
295 | * Set/get a flag to not create XSAnnotations when deserializing the grammar. |
---|
296 | * Defaults to false (create XSAnnotations when deserializing the grammar). |
---|
297 | */ |
---|
298 | inline void setIgnoreSerializedAnnotations(const bool flag) |
---|
299 | { |
---|
300 | fIgnoreSerializedAnnotations = flag; |
---|
301 | }; |
---|
302 | inline bool getIgnoreSerializedAnnotations() const |
---|
303 | { |
---|
304 | return fIgnoreSerializedAnnotations; |
---|
305 | }; |
---|
306 | |
---|
307 | protected : |
---|
308 | // ----------------------------------------------------------------------- |
---|
309 | /** Hidden Constructors */ |
---|
310 | // ----------------------------------------------------------------------- |
---|
311 | //@{ |
---|
312 | XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager) |
---|
313 | :fMemMgr(memMgr) |
---|
314 | ,fIgnoreSerializedAnnotations(false) |
---|
315 | { |
---|
316 | }; |
---|
317 | //@} |
---|
318 | |
---|
319 | private : |
---|
320 | // ----------------------------------------------------------------------- |
---|
321 | /** name Unimplemented copy constructor and operator= */ |
---|
322 | // ----------------------------------------------------------------------- |
---|
323 | //@{ |
---|
324 | XMLGrammarPool(const XMLGrammarPool& ); |
---|
325 | XMLGrammarPool& operator=(const XMLGrammarPool& ); |
---|
326 | //@} |
---|
327 | |
---|
328 | // ----------------------------------------------------------------------- |
---|
329 | // |
---|
330 | // fMemMgr: plugged-in (or defaulted-in) memory manager |
---|
331 | // not owned |
---|
332 | // no reset after initialization |
---|
333 | // |
---|
334 | // ----------------------------------------------------------------------- |
---|
335 | |
---|
336 | MemoryManager* const fMemMgr; |
---|
337 | bool fIgnoreSerializedAnnotations; |
---|
338 | |
---|
339 | }; |
---|
340 | |
---|
341 | XERCES_CPP_NAMESPACE_END |
---|
342 | |
---|
343 | #endif |
---|