Xerces-C++: XMLGrammarPool.hpp Source File

Xerces-C++ 3.3.0

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$
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
33class Grammar;
34class XMLGrammarDescription;
35class DTDGrammar;
36class SchemaGrammar;
37class XMLDTDDescription;
38class XMLSchemaDescription;
39class XMLStringPool;
40class BinInputStream;
41class BinOutputStream;
42
43 class XMLPARSER_EXPORT XMLGrammarPool : public XMemory
44{
45public :
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
286protected :
287 // -----------------------------------------------------------------------
289 // -----------------------------------------------------------------------
291 XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
292 :fMemMgr(memMgr)
293 ,fIgnoreSerializedAnnotations(false)
294 {
295 };
297
298private :
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
PlatformUtils.hpp
XMemory.hpp
XSModel.hpp
XMLPARSER_EXPORT
#define XMLPARSER_EXPORT
Definition XercesDefs.hpp:163
XERCES_CPP_NAMESPACE_BEGIN
#define XERCES_CPP_NAMESPACE_BEGIN
Definition XercesDefs.hpp:112
XERCES_CPP_NAMESPACE_END
#define XERCES_CPP_NAMESPACE_END
Definition XercesDefs.hpp:113
XMLCh
char16_t XMLCh
Definition Xerces_autoconf_config.hpp:120
BinInputStream
Definition BinInputStream.hpp:30
BinOutputStream
Definition BinOutputStream.hpp:30
MemoryManager
Configurable memory manager.
Definition MemoryManager.hpp:40
XMLDTDDescription
Definition XMLDTDDescription.hpp:30
XMLGrammarDescription
Definition XMLGrammarDescription.hpp:33
XMLGrammarPool
Definition XMLGrammarPool.hpp:44
XMLGrammarPool::cacheGrammar
virtual bool cacheGrammar(Grammar *const gramToCache)=0
cacheGrammar
XMLGrammarPool::XMLGrammarPool
XMLGrammarPool(MemoryManager *const memMgr=XMLPlatformUtils::fgMemoryManager)
Hidden Constructors.
Definition XMLGrammarPool.hpp:291
XMLGrammarPool::getURIStringPool
virtual XMLStringPool * getURIStringPool()=0
Return an XMLStringPool for use by validation routines.
XMLGrammarPool::lockPool
virtual void lockPool()=0
lockPool
XMLGrammarPool::getIgnoreSerializedAnnotations
bool getIgnoreSerializedAnnotations() const
Definition XMLGrammarPool.hpp:281
XMLGrammarPool::createDTDDescription
virtual XMLDTDDescription * createDTDDescription(const XMLCh *const systemId)=0
createDTDDescription
XMLGrammarPool::deserializeGrammars
virtual void deserializeGrammars(BinInputStream *const)=0
XMLGrammarPool::createSchemaDescription
virtual XMLSchemaDescription * createSchemaDescription(const XMLCh *const targetNamespace)=0
createSchemaDescription
XMLGrammarPool::retrieveGrammar
virtual Grammar * retrieveGrammar(XMLGrammarDescription *const gramDesc)=0
retrieveGrammar
XMLGrammarPool::unlockPool
virtual void unlockPool()=0
unlockPool
XMLGrammarPool::~XMLGrammarPool
virtual ~XMLGrammarPool()
virtual destructor
Definition XMLGrammarPool.hpp:55
XMLGrammarPool::orphanGrammar
virtual Grammar * orphanGrammar(const XMLCh *const nameSpaceKey)=0
orphanGrammar
XMLGrammarPool::serializeGrammars
virtual void serializeGrammars(BinOutputStream *const)=0
serialization and deserialization support
XMLGrammarPool::getMemoryManager
MemoryManager * getMemoryManager()
getMemoryManager
Definition XMLGrammarPool.hpp:200
XMLGrammarPool::clear
virtual bool clear()=0
clear
XMLGrammarPool::createSchemaGrammar
virtual SchemaGrammar * createSchemaGrammar()=0
createSchemaGrammar
XMLGrammarPool::getGrammarEnumerator
virtual RefHashTableOfEnumerator< Grammar > getGrammarEnumerator() const =0
Get an enumeration of the cached Grammars in the Grammar pool.
XMLGrammarPool::createDTDGrammar
virtual DTDGrammar * createDTDGrammar()=0
createDTDGrammar
XMLGrammarPool::setIgnoreSerializedAnnotations
void setIgnoreSerializedAnnotations(const bool flag)
Definition XMLGrammarPool.hpp:277
XMLGrammarPool::getXSModel
virtual XSModel * getXSModel(bool &XSModelWasChanged)=0
XMLPlatformUtils::fgMemoryManager
static MemoryManager * fgMemoryManager
The configurable memory manager.
Definition PlatformUtils.hpp:121
XMLSchemaDescription
Definition XMLSchemaDescription.hpp:33
XMemory
This class makes it possible to override the C++ memory management by adding new/delete operators to ...
Definition XMemory.hpp:41
XSModel
Definition XSModel.hpp:60