/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * $Id: XMLGrammarPool.hpp 568078 2007-08-21 11:43:25Z amassari $ */ #if !defined(XMLGRAMMARPOOL_HPP) #define XMLGRAMMARPOOL_HPP #include #include #include #include XERCES_CPP_NAMESPACE_BEGIN class Grammar; class XMLGrammarDescription; class DTDGrammar; class SchemaGrammar; class XMLDTDDescription; class XMLSchemaDescription; class XMLStringPool; class BinInputStream; class BinOutputStream; class XMLPARSER_EXPORT XMLGrammarPool : public XMemory { public : // ----------------------------------------------------------------------- /** @name Virtual destructor for derived classes */ // ----------------------------------------------------------------------- //@{ /** * virtual destructor * */ virtual ~XMLGrammarPool(){}; //@} // ----------------------------------------------------------------------- /** @name The Grammar Pool Interface */ // ----------------------------------------------------------------------- //@{ /** * cacheGrammar * * Provide the grammar pool with an opportunity * to cache the given grammar. If the pool does not choose to do so, * it should return false; otherwise, it should return true, so that * the caller knows whether the grammar has been adopted. * * @param gramToCache the Grammar to be cached in the grammar pool * @return true if the grammar pool has elected to cache the grammar (in which case * it is assumed to have adopted it); false if it does not cache it * */ virtual bool cacheGrammar(Grammar* const gramToCache) = 0; /** * retrieveGrammar * * @param gramDesc the Grammar Description used to search for grammar * cached in the grammar pool * */ virtual Grammar* retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0; /** * orphanGrammar * * grammar removed from the grammar pool and owned by the caller * * @param nameSpaceKey Key used to search for grammar in the grammar pool * @return the grammar that was removed from the pool (0 if none) */ virtual Grammar* orphanGrammar(const XMLCh* const nameSpaceKey) = 0; /** * Get an enumeration of the cached Grammars in the Grammar pool * * @return enumeration of the cached Grammars in Grammar pool */ virtual RefHashTableOfEnumerator getGrammarEnumerator() const = 0; /** * clear * * all grammars are removed from the grammar pool and deleted. * @return true if the grammar pool was cleared. false if it did not. */ virtual bool clear() = 0; /** * lockPool * * When this method is called by the application, the * grammar pool should stop adding new grammars to the cache. * This should result in the grammar pool being sharable * among parsers operating in different threads. * */ virtual void lockPool() = 0; /** * unlockPool * * After this method has been called, the grammar pool implementation * should return to its default behaviour when cacheGrammars(...) is called. * One effect, depending on the underlying implementation, is that the grammar pool * may no longer be thread-safe (even on read operations). * * For PSVI support any previous XSModel that was produced will be deleted. */ virtual void unlockPool() = 0; //@} // ----------------------------------------------------------------------- /** @name Factory interface */ // ----------------------------------------------------------------------- //@{ /** * createDTDGrammar * */ virtual DTDGrammar* createDTDGrammar() = 0; /** * createSchemaGrammar * */ virtual SchemaGrammar* createSchemaGrammar() = 0; /** * createDTDDescription * */ virtual XMLDTDDescription* createDTDDescription(const XMLCh* const systemId) = 0; /** * createSchemaDescription * */ virtual XMLSchemaDescription* createSchemaDescription(const XMLCh* const targetNamespace) = 0; //@} // ----------------------------------------------------------------------- /** @name schema component model support */ // ----------------------------------------------------------------------- //@{ /*** * Return an XSModel derived from the components of all SchemaGrammars * in the grammar pool. If the pool is locked, this should * be a thread-safe operation. It should return null if and only if * the pool is empty. * * Calling getXSModel() on an unlocked grammar pool may result in the * creation of a new XSModel with the old XSModel being deleted. The * function will return a different address for the XSModel if it has * changed. * * @deprecated (shouldn't use address to determine if XSModel changed) */ virtual XSModel *getXSModel() = 0; /*** * Return an XSModel derived from the components of all SchemaGrammars * in the grammar pool. If the pool is locked, this should * be a thread-safe operation. * * NOTE: The function should NEVER return NULL. If there are no grammars in * the pool it should return an XSModel containing the Schema for Schema. * * Calling getXSModel() on an unlocked grammar pool may result in the * creation of a new XSModel with the old XSModel being deleted. * The bool parameter will indicate if the XSModel was changed. * * For source code compatibility, default implementation is to say * XSModelWasChanged. */ virtual XSModel *getXSModel(bool& XSModelWasChanged) { XSModelWasChanged = true; return getXSModel(); } // @} // ----------------------------------------------------------------------- /** @name Getter */ // ----------------------------------------------------------------------- //@{ /** * getMemoryManager * */ inline MemoryManager* getMemoryManager() { return fMemMgr; } /** * Return an XMLStringPool for use by validation routines. * Implementations should not create a string pool on each call to this * method, but should maintain one string pool for all grammars * for which this pool is responsible. */ virtual XMLStringPool *getURIStringPool() = 0; //@} // ----------------------------------------------------------------------- /** serialization and deserialization support */ // ----------------------------------------------------------------------- /*** * * 1. Context: Serialize/Deserialize All Grammars In One Session * * Since it is common that a declaration in one grammar may reference * to definitions in other grammars, it is required to serialize those * related (or interdependent) grammars in to one persistent data store * in one serialization session (storing), and deserialize them from the * persistent data store in one deserialization session (loading) back * to the grammar pool. * * 2. Multiple serializations * * It is acceptable that client application requests more than one * grammar serialization on a particular grammar pool, to track the * different grammars cached, or for whatever reasons that client * application is interested in. * * 3. Multiple deserializations * * Request for grammar deserialization either after the grammar pool has * its own cached grammars, or request for more than one grammar * deserialization, may cause undesired and unpredictable consequence * and therefore client application shall be aware that individual * implementationis may NOT support this. * * However it is strongly recommended that the client application requests * no more than one grammar deserialization even a particular implementation * may allow multiple deserializations. * * 4. Locking * * Both serialization and deserialization requires to lock the grammar pool * before operation and unlock after operation. In the case the grammar pool * is locked by a third party, the request for serialization/deserialization * will NOT be entertained. * * 5. Versioning * * The Persistent data store has a version tag to be verified during * deserialization, thus a grammar pool may decide if it supports * a binary data created by a different release of Xerces. * * 6. Clean up * * The client application shall be aware that in the event of an exception * thrown due to a corrupted data store during deserialization, implementation * may not be able to clean up all resources allocated, and therefore it is * client application's responsibility to clean up those unreleased resources. * * */ virtual void serializeGrammars(BinOutputStream* const) = 0; virtual void deserializeGrammars(BinInputStream* const) = 0; /* * Set/get a flag to not create XSAnnotations when deserializing the grammar. * Defaults to false (create XSAnnotations when deserializing the grammar). */ inline void setIgnoreSerializedAnnotations(const bool flag) { fIgnoreSerializedAnnotations = flag; }; inline bool getIgnoreSerializedAnnotations() const { return fIgnoreSerializedAnnotations; }; protected : // ----------------------------------------------------------------------- /** Hidden Constructors */ // ----------------------------------------------------------------------- //@{ XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager) :fMemMgr(memMgr) ,fIgnoreSerializedAnnotations(false) { }; //@} private : // ----------------------------------------------------------------------- /** name Unimplemented copy constructor and operator= */ // ----------------------------------------------------------------------- //@{ XMLGrammarPool(const XMLGrammarPool& ); XMLGrammarPool& operator=(const XMLGrammarPool& ); //@} // ----------------------------------------------------------------------- // // fMemMgr: plugged-in (or defaulted-in) memory manager // not owned // no reset after initialization // // ----------------------------------------------------------------------- MemoryManager* const fMemMgr; bool fIgnoreSerializedAnnotations; }; XERCES_CPP_NAMESPACE_END #endif