00001 /* 00002 * Licensed to the Apache Software Foundation (ASF) under one or more 00003 * contributor license agreements. See the NOTICE file distributed with 00004 * this work for additional information regarding copyright ownership. 00005 * The ASF licenses this file to You under the Apache License, Version 2.0 00006 * (the "License"); you may not use this file except in compliance with 00007 * the License. You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 00018 /* 00019 * $Id$ 00020 */ 00021 00022 #if !defined(XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP) 00023 #define XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP 00024 00025 #include <xercesc/util/PlatformUtils.hpp> 00026 #include <xercesc/util/RefHashTableOf.hpp> 00027 #include <xercesc/util/XMemory.hpp> 00028 #include <xercesc/framework/psvi/XSModel.hpp> 00029 00030 00031 XERCES_CPP_NAMESPACE_BEGIN 00032 00033 class Grammar; 00034 class XMLGrammarDescription; 00035 class DTDGrammar; 00036 class SchemaGrammar; 00037 class XMLDTDDescription; 00038 class XMLSchemaDescription; 00039 class XMLStringPool; 00040 class BinInputStream; 00041 class BinOutputStream; 00042 00043 class XMLPARSER_EXPORT XMLGrammarPool : public XMemory 00044 { 00045 public : 00046 // ----------------------------------------------------------------------- 00048 // ----------------------------------------------------------------------- 00050 00055 virtual ~XMLGrammarPool(){}; 00057 00058 // ----------------------------------------------------------------------- 00060 // ----------------------------------------------------------------------- 00062 00076 virtual bool cacheGrammar(Grammar* const gramToCache) = 0; 00077 00085 virtual Grammar* retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0; 00086 00087 00096 virtual Grammar* orphanGrammar(const XMLCh* const nameSpaceKey) = 0; 00097 00098 00104 virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0; 00105 00112 virtual bool clear() = 0; 00113 00123 virtual void lockPool() = 0; 00124 00135 virtual void unlockPool() = 0; 00136 00138 00139 // ----------------------------------------------------------------------- 00141 // ----------------------------------------------------------------------- 00143 00148 virtual DTDGrammar* createDTDGrammar() = 0; 00149 00154 virtual SchemaGrammar* createSchemaGrammar() = 0; 00155 00160 virtual XMLDTDDescription* createDTDDescription(const XMLCh* const systemId) = 0; 00165 virtual XMLSchemaDescription* createSchemaDescription(const XMLCh* const targetNamespace) = 0; 00166 00168 00169 // ----------------------------------------------------------------------- 00171 // ----------------------------------------------------------------------- 00173 00174 /*** 00175 * Return an XSModel derived from the components of all SchemaGrammars 00176 * in the grammar pool. If the pool is locked, this should 00177 * be a thread-safe operation. 00178 * 00179 * NOTE: The function should NEVER return NULL. If there are no grammars in 00180 * the pool it should return an XSModel containing the Schema for Schema. 00181 * 00182 * Calling getXSModel() on an unlocked grammar pool may result in the 00183 * creation of a new XSModel with the old XSModel being deleted. 00184 * The bool parameter will indicate if the XSModel was changed. 00185 * 00186 */ 00187 virtual XSModel *getXSModel(bool& XSModelWasChanged) = 0; 00188 00189 // @} 00190 00191 // ----------------------------------------------------------------------- 00193 // ----------------------------------------------------------------------- 00195 00200 inline MemoryManager* getMemoryManager() 00201 { 00202 return fMemMgr; 00203 } 00204 00211 virtual XMLStringPool *getURIStringPool() = 0; 00213 00214 // ----------------------------------------------------------------------- 00216 // ----------------------------------------------------------------------- 00217 00218 /*** 00219 * 00220 * 1. Context: Serialize/Deserialize All Grammars In One Session 00221 * 00222 * Since it is common that a declaration in one grammar may reference 00223 * to definitions in other grammars, it is required to serialize those 00224 * related (or interdependent) grammars in to one persistent data store 00225 * in one serialization session (storing), and deserialize them from the 00226 * persistent data store in one deserialization session (loading) back 00227 * to the grammar pool. 00228 * 00229 * 2. Multiple serializations 00230 * 00231 * It is acceptable that client application requests more than one 00232 * grammar serialization on a particular grammar pool, to track the 00233 * different grammars cached, or for whatever reasons that client 00234 * application is interested in. 00235 * 00236 * 3. Multiple deserializations 00237 * 00238 * Request for grammar deserialization either after the grammar pool has 00239 * its own cached grammars, or request for more than one grammar 00240 * deserialization, may cause undesired and unpredictable consequence 00241 * and therefore client application shall be aware that individual 00242 * implementationis may NOT support this. 00243 * 00244 * However it is strongly recommended that the client application requests 00245 * no more than one grammar deserialization even a particular implementation 00246 * may allow multiple deserializations. 00247 * 00248 * 4. Locking 00249 * 00250 * Both serialization and deserialization requires to lock the grammar pool 00251 * before operation and unlock after operation. In the case the grammar pool 00252 * is locked by a third party, the request for serialization/deserialization 00253 * will NOT be entertained. 00254 * 00255 * 5. Versioning 00256 * 00257 * The Persistent data store has a version tag to be verified during 00258 * deserialization, thus a grammar pool may decide if it supports 00259 * a binary data created by a different release of Xerces. 00260 * 00261 * 6. Clean up 00262 * 00263 * The client application shall be aware that in the event of an exception 00264 * thrown due to a corrupted data store during deserialization, implementation 00265 * may not be able to clean up all resources allocated, and therefore it is 00266 * client application's responsibility to clean up those unreleased resources. 00267 * 00268 * 00269 */ 00270 virtual void serializeGrammars(BinOutputStream* const) = 0; 00271 virtual void deserializeGrammars(BinInputStream* const) = 0; 00272 00273 /* 00274 * Set/get a flag to not create XSAnnotations when deserializing the grammar. 00275 * Defaults to false (create XSAnnotations when deserializing the grammar). 00276 */ 00277 inline void setIgnoreSerializedAnnotations(const bool flag) 00278 { 00279 fIgnoreSerializedAnnotations = flag; 00280 }; 00281 inline bool getIgnoreSerializedAnnotations() const 00282 { 00283 return fIgnoreSerializedAnnotations; 00284 }; 00285 00286 protected : 00287 // ----------------------------------------------------------------------- 00289 // ----------------------------------------------------------------------- 00291 XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager) 00292 :fMemMgr(memMgr) 00293 ,fIgnoreSerializedAnnotations(false) 00294 { 00295 }; 00297 00298 private : 00299 // ----------------------------------------------------------------------- 00301 // ----------------------------------------------------------------------- 00303 XMLGrammarPool(const XMLGrammarPool& ); 00304 XMLGrammarPool& operator=(const XMLGrammarPool& ); 00306 00307 // ----------------------------------------------------------------------- 00308 // 00309 // fMemMgr: plugged-in (or defaulted-in) memory manager 00310 // not owned 00311 // no reset after initialization 00312 // 00313 // ----------------------------------------------------------------------- 00314 00315 MemoryManager* const fMemMgr; 00316 bool fIgnoreSerializedAnnotations; 00317 00318 }; 00319 00320 XERCES_CPP_NAMESPACE_END 00321 00322 #endif