# 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