XMLGrammarPool.hpp

Go to the documentation of this file.
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: XMLGrammarPool.hpp 527149 2007-04-10 14:56:39Z amassari $
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

Generated on Wed Sep 24 16:36:33 2008 for Xerces-C++ by  doxygen 1.5.4