Xerces-C++ 3.1.3

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

XMLGrammarPool.hpp
Go to the documentation of this file.
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 527149 2007-04-10 14:56:39Z amassari $
20 */
21
22 #if !defined(XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP)
23 #define XERCESC_INCLUDE_GUARD_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 // -----------------------------------------------------------------------
48 // -----------------------------------------------------------------------
50
55 virtual ~XMLGrammarPool(){};
57
58 // -----------------------------------------------------------------------
60 // -----------------------------------------------------------------------
62
76 virtual bool cacheGrammar(Grammar* const gramToCache) = 0;
77
85 virtual Grammar* retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
86
87
96 virtual Grammar* orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
97
98
104 virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
105
112 virtual bool clear() = 0;
113
123 virtual void lockPool() = 0;
124
135 virtual void unlockPool() = 0;
136
138
139 // -----------------------------------------------------------------------
141 // -----------------------------------------------------------------------
143
148 virtual DTDGrammar* createDTDGrammar() = 0;
149
154 virtual SchemaGrammar* createSchemaGrammar() = 0;
155
160 virtual XMLDTDDescription* createDTDDescription(const XMLCh* const systemId) = 0;
165 virtual XMLSchemaDescription* createSchemaDescription(const XMLCh* const targetNamespace) = 0;
166
168
169 // -----------------------------------------------------------------------
171 // -----------------------------------------------------------------------
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.
178 *
179 * NOTE: The function should NEVER return NULL. If there are no grammars in
180 * the pool it should return an XSModel containing the Schema for Schema.
181 *
182 * Calling getXSModel() on an unlocked grammar pool may result in the
183 * creation of a new XSModel with the old XSModel being deleted.
184 * The bool parameter will indicate if the XSModel was changed.
185 *
186 */
187 virtual XSModel *getXSModel(bool& XSModelWasChanged) = 0;
188
189 // @}
190
191 // -----------------------------------------------------------------------
193 // -----------------------------------------------------------------------
195
200 inline MemoryManager* getMemoryManager()
201 {
202 return fMemMgr;
203 }
204
211 virtual XMLStringPool *getURIStringPool() = 0;
213
214 // -----------------------------------------------------------------------
216 // -----------------------------------------------------------------------
217
218 /***
219 *
220 * 1. Context: Serialize/Deserialize All Grammars In One Session
221 *
222 * Since it is common that a declaration in one grammar may reference
223 * to definitions in other grammars, it is required to serialize those
224 * related (or interdependent) grammars in to one persistent data store
225 * in one serialization session (storing), and deserialize them from the
226 * persistent data store in one deserialization session (loading) back
227 * to the grammar pool.
228 *
229 * 2. Multiple serializations
230 *
231 * It is acceptable that client application requests more than one
232 * grammar serialization on a particular grammar pool, to track the
233 * different grammars cached, or for whatever reasons that client
234 * application is interested in.
235 *
236 * 3. Multiple deserializations
237 *
238 * Request for grammar deserialization either after the grammar pool has
239 * its own cached grammars, or request for more than one grammar
240 * deserialization, may cause undesired and unpredictable consequence
241 * and therefore client application shall be aware that individual
242 * implementationis may NOT support this.
243 *
244 * However it is strongly recommended that the client application requests
245 * no more than one grammar deserialization even a particular implementation
246 * may allow multiple deserializations.
247 *
248 * 4. Locking
249 *
250 * Both serialization and deserialization requires to lock the grammar pool
251 * before operation and unlock after operation. In the case the grammar pool
252 * is locked by a third party, the request for serialization/deserialization
253 * will NOT be entertained.
254 *
255 * 5. Versioning
256 *
257 * The Persistent data store has a version tag to be verified during
258 * deserialization, thus a grammar pool may decide if it supports
259 * a binary data created by a different release of Xerces.
260 *
261 * 6. Clean up
262 *
263 * The client application shall be aware that in the event of an exception
264 * thrown due to a corrupted data store during deserialization, implementation
265 * may not be able to clean up all resources allocated, and therefore it is
266 * client application's responsibility to clean up those unreleased resources.
267 *
268 *
269 */
270 virtual void serializeGrammars(BinOutputStream* const) = 0;
271 virtual void deserializeGrammars(BinInputStream* const) = 0;
272
273 /*
274 * Set/get a flag to not create XSAnnotations when deserializing the grammar.
275 * Defaults to false (create XSAnnotations when deserializing the grammar).
276 */
277 inline void setIgnoreSerializedAnnotations(const bool flag)
278 {
279 fIgnoreSerializedAnnotations = flag;
280 };
281 inline bool getIgnoreSerializedAnnotations() const
282 {
283 return fIgnoreSerializedAnnotations;
284 };
285
286 protected :
287 // -----------------------------------------------------------------------
289 // -----------------------------------------------------------------------
291 XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
292 :fMemMgr(memMgr)
293 ,fIgnoreSerializedAnnotations(false)
294 {
295 };
297
298 private :
299 // -----------------------------------------------------------------------
301 // -----------------------------------------------------------------------
303 XMLGrammarPool(const XMLGrammarPool& );
304 XMLGrammarPool& operator=(const XMLGrammarPool& );
306
307 // -----------------------------------------------------------------------
308 //
309 // fMemMgr: plugged-in (or defaulted-in) memory manager
310 // not owned
311 // no reset after initialization
312 //
313 // -----------------------------------------------------------------------
314
315 MemoryManager* const fMemMgr;
316 bool fIgnoreSerializedAnnotations;
317
318 };
319
320 XERCES_CPP_NAMESPACE_END
321
322 #endif