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 568078 2007-08-21 11:43:25Z amassari $
00020  */
00021 
00022 #if !defined(XMLGRAMMARPOOL_HPP)
00023 #define 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.  It should return null if and only if
00178       * the pool is empty.
00179       *
00180       * Calling getXSModel() on an unlocked grammar pool may result in the
00181       * creation of a new XSModel with the old XSModel being deleted.  The
00182       * function will return a different address for the XSModel if it has
00183       * changed.
00184       * 
00185       * @deprecated (shouldn't use address to determine if XSModel changed)
00186       */
00187     virtual XSModel *getXSModel() = 0;
00188 
00189     /***
00190       * Return an XSModel derived from the components of all SchemaGrammars
00191       * in the grammar pool.  If the pool is locked, this should
00192       * be a thread-safe operation.
00193       *
00194       * NOTE: The function should NEVER return NULL.  If there are no grammars in
00195       *       the pool it should return an XSModel containing the Schema for Schema.      
00196       *
00197       * Calling getXSModel() on an unlocked grammar pool may result in the
00198       * creation of a new XSModel with the old XSModel being deleted.
00199       * The bool parameter will indicate if the XSModel was changed.
00200       *     
00201       * For source code compatibility, default implementation is to say
00202       * XSModelWasChanged.
00203       */
00204     virtual XSModel *getXSModel(bool& XSModelWasChanged)
00205     {
00206         XSModelWasChanged = true;
00207         return getXSModel();
00208     }
00209     
00210     // @}
00211 
00212     // -----------------------------------------------------------------------
00214     // -----------------------------------------------------------------------                                                        
00216 
00221     inline MemoryManager*    getMemoryManager()
00222     {
00223         return fMemMgr;
00224     }
00225 
00232     virtual XMLStringPool *getURIStringPool() = 0;
00234 
00235     // -----------------------------------------------------------------------
00237     // -----------------------------------------------------------------------                                                        
00238 
00239     /***
00240       *
00241       * 1. Context: Serialize/Deserialize All Grammars In One Session
00242       *
00243       *    Since it is common that a declaration in one grammar may reference 
00244       *    to definitions in other grammars, it is required to serialize those 
00245       *    related (or interdependent) grammars in to one persistent data store 
00246       *    in one serialization session (storing), and deserialize them from the
00247       *    persistent data store in one deserialization session (loading) back
00248       *    to the grammar pool.    
00249       *
00250       * 2. Multiple serializations
00251       *
00252       *    It is acceptable that client application requests more than one 
00253       *    grammar serialization on a particular grammar pool, to track the 
00254       *    different grammars cached, or for whatever reasons that client 
00255       *    application is interested in. 
00256       *
00257       * 3. Multiple deserializations
00258       * 
00259       *    Request for grammar deserialization either after the grammar pool has 
00260       *    its own cached grammars, or request for more than one grammar 
00261       *    deserialization, may cause undesired and unpredictable consequence
00262       *    and therefore client application shall be aware that individual 
00263       *    implementationis may NOT support this.
00264       *
00265       *    However it is strongly recommended that the client application requests 
00266       *    no more than one grammar deserialization even a particular implementation
00267       *    may allow multiple deserializations.
00268       *
00269       * 4. Locking
00270       *
00271       *    Both serialization and deserialization requires to lock the grammar pool
00272       *    before operation and unlock after operation. In the case the grammar pool
00273       *    is locked by a third party, the request for serialization/deserialization
00274       *    will NOT be entertained.
00275       *
00276       * 5. Versioning
00277       *
00278       *    The Persistent data store has a version tag to be verified during 
00279       *    deserialization, thus a grammar pool may decide if it supports
00280       *    a binary data created by a different release of Xerces.
00281       * 
00282       * 6. Clean up
00283       *
00284       *    The client application shall be aware that in the event of an exception
00285       *    thrown due to a corrupted data store during deserialization, implementation
00286       *    may not be able to clean up all resources allocated, and therefore it is 
00287       *    client application's responsibility to clean up those unreleased resources.
00288       *
00289       *
00290       */
00291     virtual void     serializeGrammars(BinOutputStream* const)  = 0; 
00292     virtual void     deserializeGrammars(BinInputStream* const) = 0;       
00293        
00294     /*
00295      * Set/get a flag to not create XSAnnotations when deserializing the grammar.
00296      * Defaults to false (create XSAnnotations when deserializing the grammar).
00297      */
00298     inline void setIgnoreSerializedAnnotations(const bool flag)
00299     {
00300         fIgnoreSerializedAnnotations = flag;
00301     };
00302     inline bool getIgnoreSerializedAnnotations() const
00303     {
00304         return fIgnoreSerializedAnnotations;
00305     };
00306 
00307 protected :
00308     // -----------------------------------------------------------------------
00310     // -----------------------------------------------------------------------
00312     XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
00313     :fMemMgr(memMgr)
00314     ,fIgnoreSerializedAnnotations(false)
00315     {
00316     };
00318 
00319 private :
00320     // -----------------------------------------------------------------------
00322     // -----------------------------------------------------------------------
00324     XMLGrammarPool(const XMLGrammarPool& );
00325     XMLGrammarPool& operator=(const XMLGrammarPool& );
00327 
00328     // -----------------------------------------------------------------------
00329     //
00330     // fMemMgr: plugged-in (or defaulted-in) memory manager
00331     //          not owned 
00332     //          no reset after initialization
00333     //
00334     // -----------------------------------------------------------------------
00335     
00336     MemoryManager* const  fMemMgr;
00337     bool fIgnoreSerializedAnnotations;
00338 
00339 };
00340 
00341 XERCES_CPP_NAMESPACE_END
00342 
00343 #endif

Generated on Thu Feb 19 11:35:44 2009 for Xerces-C++ by  doxygen 1.5.4