Xerces-C++: XMLGrammarPool.hpp Source File

| API Docs for SAX and DOM |
| Main Page Classes Files Related Pages # 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  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

Copyright © 1994-2004 The Apache Software Foundation. All Rights Reserved.