| API Docs for SAX and DOM |

Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

# XMLGrammarPool.hpp

Go to the documentation of this file.

    00001 /*
    00002  * Copyright 1999-2004 The Apache Software Foundation.
    00003  *
    00004  * Licensed under the Apache License, Version 2.0 (the "License");
    00005  * you may not use this file except in compliance with the License.
    00006  * You may obtain a copy of the License at
    00007  *
    00008  *      http://www.apache.org/licenses/LICENSE-2.0
    00009  *
    00010  * Unless required by applicable law or agreed to in writing, software
    00011  * distributed under the License is distributed on an "AS IS" BASIS,
    00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    00013  * See the License for the specific language governing permissions and
    00014  * limitations under the License.
    00015  */
    00016
    00017 /*
    00018  * $Id: XMLGrammarPool.hpp 191054 2005-06-17 02:56:35Z jberry $
    00019  */
    00020
    00021 #if !defined(XMLGRAMMARPOOL_HPP)
    00022 #define XMLGRAMMARPOOL_HPP
    00023
    00024 #include <xercesc/util/PlatformUtils.hpp>
    00025 #include <xercesc/util/RefHashTableOf.hpp>
    00026 #include <xercesc/util/XMemory.hpp>
    00027 #include <xercesc/framework/psvi/XSModel.hpp>
    00028
    00029
    00030 XERCES_CPP_NAMESPACE_BEGIN
    00031
    00032 class Grammar;
    00033 class XMLGrammarDescription;
    00034 class DTDGrammar;
    00035 class SchemaGrammar;
    00036 class XMLDTDDescription;
    00037 class XMLSchemaDescription;
    00038 class XMLStringPool;
    00039 class BinInputStream;
    00040 class BinOutputStream;
    00041
    00042 class  XMLGrammarPool : public XMemory
    00043 {
    00044 public :
    00045     // -----------------------------------------------------------------------
    00047     // -----------------------------------------------------------------------
    00049
    00054     virtual ~XMLGrammarPool(){};
    00056
    00057     // -----------------------------------------------------------------------
    00059     // -----------------------------------------------------------------------
    00061
    00075     virtual bool           cacheGrammar(Grammar* const               gramToCache) = 0;
    00076
    00084     virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
    00085
    00086
    00095     virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
    00096
    00097
    00103     virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
    00104
    00111     virtual bool           clear() = 0;
    00112
    00122     virtual void           lockPool() = 0;
    00123
    00134     virtual void           unlockPool() = 0;
    00135
    00137
    00138     // -----------------------------------------------------------------------
    00140     // -----------------------------------------------------------------------
    00142
    00147     virtual DTDGrammar*            createDTDGrammar() = 0;
    00148
    00153     virtual SchemaGrammar*         createSchemaGrammar() = 0;
    00154
    00159     virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const systemId) = 0;
    00164     virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace) = 0;
    00165
    00167
    00168     // -----------------------------------------------------------------------
    00170     // -----------------------------------------------------------------------
    00172
    00173     /***
    00174       * Return an XSModel derived from the components of all SchemaGrammars
    00175       * in the grammar pool.  If the pool is locked, this should
    00176       * be a thread-safe operation.  It should return null if and only if
    00177       * the pool is empty.
    00178       *
    00179       * Calling getXSModel() on an unlocked grammar pool may result in the
    00180       * creation of a new XSModel with the old XSModel being deleted.  The
    00181       * function will return a different address for the XSModel if it has
    00182       * changed.
    00183       *
    00184       * @deprecated (shouldn't use address to determine if XSModel changed)
    00185       */
    00186     virtual XSModel *getXSModel() = 0;
    00187
    00188     /***
    00189       * Return an XSModel derived from the components of all SchemaGrammars
    00190       * in the grammar pool.  If the pool is locked, this should
    00191       * be a thread-safe operation.
    00192       *
    00193       * NOTE: The function should NEVER return NULL.  If there are no grammars in
    00194       *       the pool it should return an XSModel containing the Schema for Schema.
    00195       *
    00196       * Calling getXSModel() on an unlocked grammar pool may result in the
    00197       * creation of a new XSModel with the old XSModel being deleted.
    00198       * The bool parameter will indicate if the XSModel was changed.
    00199       *
    00200       * For source code compatibility, default implementation is to say
    00201       * XSModelWasChanged.
    00202       */
    00203     virtual XSModel *getXSModel(bool& XSModelWasChanged)
    00204     {
    00205         XSModelWasChanged = true;
    00206         return getXSModel();
    00207     }
    00208
    00209     // @}
    00210
    00211     // -----------------------------------------------------------------------
    00213     // -----------------------------------------------------------------------
    00215
    00220     inline MemoryManager*    getMemoryManager()
    00221     {
    00222         return fMemMgr;
    00223     }
    00224
    00231     virtual XMLStringPool *getURIStringPool() = 0;
    00233
    00234     // -----------------------------------------------------------------------
    00236     // -----------------------------------------------------------------------
    00237
    00238     /***
    00239       *
    00240       * 1. Context: Serialize/Deserialize All Grammars In One Session
    00241       *
    00242       *    Since it is common that a declaration in one grammar may reference
    00243       *    to definitions in other grammars, it is required to serialize those
    00244       *    related (or interdependent) grammars in to one persistent data store
    00245       *    in one serialization session (storing), and deserialize them from the
    00246       *    persistent data store in one deserialization session (loading) back
    00247       *    to the grammar pool.
    00248       *
    00249       * 2. Multiple serializations
    00250       *
    00251       *    It is acceptable that client application requests more than one
    00252       *    grammar serialization on a particular grammar pool, to track the
    00253       *    different grammars cached, or for whatever reasons that client
    00254       *    application is interested in.
    00255       *
    00256       * 3. Multiple deserializations
    00257       *
    00258       *    Request for grammar deserialization either after the grammar pool has
    00259       *    its own cached grammars, or request for more than one grammar
    00260       *    deserialization, may cause undesired and unpredictable consequence
    00261       *    and therefore client application shall be aware that individual
    00262       *    implementationis may NOT support this.
    00263       *
    00264       *    However it is strongly recommended that the client application requests
    00265       *    no more than one grammar deserialization even a particular implementation
    00266       *    may allow multiple deserializations.
    00267       *
    00268       * 4. Locking
    00269       *
    00270       *    Both serialization and deserialization requires to lock the grammar pool
    00271       *    before operation and unlock after operation. In the case the grammar pool
    00272       *    is locked by a third party, the request for serialization/deserialization
    00273       *    will NOT be entertained.
    00274       *
    00275       * 5. Versioning
    00276       *
    00277       *    The Persistent data store has a version tag to be verified during
    00278       *    deserialization, thus a grammar pool may decide if it supports
    00279       *    a binary data created by a different release of Xerces.
    00280       *
    00281       * 6. Clean up
    00282       *
    00283       *    The client application shall be aware that in the event of an exception
    00284       *    thrown due to a corrupted data store during deserialization, implementation
    00285       *    may not be able to clean up all resources allocated, and therefore it is
    00286       *    client application's responsibility to clean up those unreleased resources.
    00287       *
    00288       *
    00289       */
    00290     virtual void     serializeGrammars(BinOutputStream* const)  = 0;
    00291     virtual void     deserializeGrammars(BinInputStream* const) = 0;
    00292
    00293     /*
    00294      * Set/get a flag to not create XSAnnotations when deserializing the grammar.
    00295      * Defaults to false (create XSAnnotations when deserializing the grammar).
    00296      */
    00297     inline void setIgnoreSerializedAnnotations(const bool flag)
    00298     {
    00299         fIgnoreSerializedAnnotations = flag;
    00300     };
    00301     inline bool getIgnoreSerializedAnnotations() const
    00302     {
    00303         return fIgnoreSerializedAnnotations;
    00304     };
    00305
    00306 protected :
    00307     // -----------------------------------------------------------------------
    00309     // -----------------------------------------------------------------------
    00311     XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
    00312     :fMemMgr(memMgr)
    00313     ,fIgnoreSerializedAnnotations(false)
    00314     {
    00315     };
    00317
    00318 private :
    00319     // -----------------------------------------------------------------------
    00321     // -----------------------------------------------------------------------
    00323     XMLGrammarPool(const XMLGrammarPool& );
    00324     XMLGrammarPool& operator=(const XMLGrammarPool& );
    00326
    00327     // -----------------------------------------------------------------------
    00328     //
    00329     // fMemMgr: plugged-in (or defaulted-in) memory manager
    00330     //          not owned
    00331     //          no reset after initialization
    00332     //
    00333     // -----------------------------------------------------------------------
    00334
    00335     MemoryManager* const  fMemMgr;
    00336     bool fIgnoreSerializedAnnotations;
    00337
    00338 };
    00339
    00340 XERCES_CPP_NAMESPACE_END
    00341
    00342 #endif

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