xercesc/framework/XMLGrammarPool.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP)
0023 #define XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP
0024
0025 #include <xercesc/util/PlatformUtils.hpp>
0026 #include <xercesc/util/RefHashTableOf.hpp>
0027 #include <xercesc/util/XMemory.hpp>
0028 #include <xercesc/framework/psvi/XSModel.hpp>
0029
0030
0031 XERCES_CPP_NAMESPACE_BEGIN
0032
0033 class Grammar;
0034 class XMLGrammarDescription;
0035 class DTDGrammar;
0036 class SchemaGrammar;
0037 class XMLDTDDescription;
0038 class XMLSchemaDescription;
0039 class XMLStringPool;
0040 class BinInputStream;
0041 class BinOutputStream;
0042
0043 class XMLPARSER_EXPORT XMLGrammarPool : public XMemory
0044 {
0045 public :
0046     // -----------------------------------------------------------------------
0047     /** @name Virtual destructor for derived classes */
0048     // -----------------------------------------------------------------------
0049     //@{
0050
0051     /**
0052       * virtual destructor
0053       *
0054       */
0055     virtual ~XMLGrammarPool(){};
0056     //@}
0057
0058     // -----------------------------------------------------------------------
0059     /** @name The Grammar Pool Interface */
0060     // -----------------------------------------------------------------------
0061     //@{
0062
0063     /**
0064       * cacheGrammar
0065       *
0066       * Provide the grammar pool with an opportunity
0067       * to cache the given grammar.  If the pool does not choose to do so,
0068       * it should return false; otherwise, it should return true, so that
0069       * the caller knows whether the grammar has been adopted.
0070       *
0071       * @param gramToCache the Grammar to be cached in the grammar pool
0072       * @return true if the grammar pool has elected to cache the grammar (in which case
0073       * it is assumed to have adopted it); false if it does not cache it
0074       *
0075       */
0076     virtual bool           cacheGrammar(Grammar* const               gramToCache) = 0;
0077
0078     /**
0079       * retrieveGrammar
0080       *
0081       * @param gramDesc the Grammar Description used to search for grammar
0082       *                  cached in the grammar pool
0083       *
0084       */
0085     virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
0086
0087
0088     /**
0089       * orphanGrammar
0090       *
0091       * grammar removed from the grammar pool and owned by the caller
0092       *
0093       * @param nameSpaceKey Key used to search for grammar in the grammar pool
0094       * @return the grammar that was removed from the pool (0 if none)
0095       */
0096     virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
0097
0098
0099     /**
0100      * Get an enumeration of the cached Grammars in the Grammar pool
0101      *
0102      * @return enumeration of the cached Grammars in Grammar pool
0103      */
0104     virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
0105
0106     /**
0107       * clear
0108       *
0109       * all grammars are removed from the grammar pool and deleted.
0110       * @return true if the grammar pool was cleared. false if it did not.
0111       */
0112     virtual bool           clear() = 0;
0113
0114     /**
0115       * lockPool
0116       *
0117       * When this method is called by the application, the
0118       * grammar pool should stop adding new grammars to the cache.
0119       * This should result in the grammar pool being sharable
0120       * among parsers operating in different threads.
0121       *
0122       */
0123     virtual void           lockPool() = 0;
0124
0125     /**
0126       * unlockPool
0127       *
0128       * After this method has been called, the grammar pool implementation
0129       * should return to its default behaviour when cacheGrammars(...) is called.
0130       * One effect, depending on the underlying implementation, is that the grammar pool
0131       * may no longer be thread-safe (even on read operations).
0132       *
0133       * For PSVI support any previous XSModel that was produced will be deleted.
0134       */
0135     virtual void           unlockPool() = 0;
0136
0137     //@}
0138
0139     // -----------------------------------------------------------------------
0140     /** @name  Factory interface */
0141     // -----------------------------------------------------------------------
0142     //@{
0143
0144     /**
0145       * createDTDGrammar
0146       *
0147       */
0148     virtual DTDGrammar*            createDTDGrammar() = 0;
0149
0150     /**
0151       * createSchemaGrammar
0152       *
0153       */
0154     virtual SchemaGrammar*         createSchemaGrammar() = 0;
0155
0156     /**
0157       * createDTDDescription
0158       *
0159       */
0160     virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const systemId) = 0;
0161     /**
0162       * createSchemaDescription
0163       *
0164       */
0165     virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace) = 0;
0166
0167     //@}
0168
0169     // -----------------------------------------------------------------------
0170     /** @name  schema component model support */
0171     // -----------------------------------------------------------------------
0172     //@{
0173
0174     /***
0175       * Return an XSModel derived from the components of all SchemaGrammars
0176       * in the grammar pool.  If the pool is locked, this should
0177       * be a thread-safe operation.
0178       *
0179       * NOTE: The function should NEVER return NULL.  If there are no grammars in
0180       *       the pool it should return an XSModel containing the Schema for Schema.
0181       *
0182       * Calling getXSModel() on an unlocked grammar pool may result in the
0183       * creation of a new XSModel with the old XSModel being deleted.
0184       * The bool parameter will indicate if the XSModel was changed.
0185       *
0186       */
0187     virtual XSModel *getXSModel(bool& XSModelWasChanged) = 0;
0188
0189     // @}
0190
0191     // -----------------------------------------------------------------------
0192     /** @name  Getter */
0193     // -----------------------------------------------------------------------
0194     //@{
0195
0196     /**
0197       * getMemoryManager
0198       *
0199       */
0200     inline MemoryManager*    getMemoryManager()
0201     {
0202         return fMemMgr;
0203     }
0204
0205     /**
0206       * Return an XMLStringPool for use by validation routines.
0207       * Implementations should not create a string pool on each call to this
0208       * method, but should maintain one string pool for all grammars
0209       * for which this pool is responsible.
0210       */
0211     virtual XMLStringPool *getURIStringPool() = 0;
0212     //@}
0213
0214     // -----------------------------------------------------------------------
0215     /** serialization and deserialization support */
0216     // -----------------------------------------------------------------------
0217
0218     /***
0219       *
0220       * 1. Context: Serialize/Deserialize All Grammars In One Session
0221       *
0222       *    Since it is common that a declaration in one grammar may reference
0223       *    to definitions in other grammars, it is required to serialize those
0224       *    related (or interdependent) grammars in to one persistent data store
0225       *    in one serialization session (storing), and deserialize them from the
0226       *    persistent data store in one deserialization session (loading) back
0227       *    to the grammar pool.
0228       *
0229       * 2. Multiple serializations
0230       *
0231       *    It is acceptable that client application requests more than one
0232       *    grammar serialization on a particular grammar pool, to track the
0233       *    different grammars cached, or for whatever reasons that client
0234       *    application is interested in.
0235       *
0236       * 3. Multiple deserializations
0237       *
0238       *    Request for grammar deserialization either after the grammar pool has
0239       *    its own cached grammars, or request for more than one grammar
0240       *    deserialization, may cause undesired and unpredictable consequence
0241       *    and therefore client application shall be aware that individual
0242       *    implementationis may NOT support this.
0243       *
0244       *    However it is strongly recommended that the client application requests
0245       *    no more than one grammar deserialization even a particular implementation
0246       *    may allow multiple deserializations.
0247       *
0248       * 4. Locking
0249       *
0250       *    Both serialization and deserialization requires to lock the grammar pool
0251       *    before operation and unlock after operation. In the case the grammar pool
0252       *    is locked by a third party, the request for serialization/deserialization
0253       *    will NOT be entertained.
0254       *
0255       * 5. Versioning
0256       *
0257       *    The Persistent data store has a version tag to be verified during
0258       *    deserialization, thus a grammar pool may decide if it supports
0259       *    a binary data created by a different release of Xerces.
0260       *
0261       * 6. Clean up
0262       *
0263       *    The client application shall be aware that in the event of an exception
0264       *    thrown due to a corrupted data store during deserialization, implementation
0265       *    may not be able to clean up all resources allocated, and therefore it is
0266       *    client application's responsibility to clean up those unreleased resources.
0267       *
0268       *
0269       */
0270     virtual void     serializeGrammars(BinOutputStream* const)  = 0;
0271     virtual void     deserializeGrammars(BinInputStream* const) = 0;
0272
0273     /*
0274      * Set/get a flag to not create XSAnnotations when deserializing the grammar.
0275      * Defaults to false (create XSAnnotations when deserializing the grammar).
0276      */
0277     inline void setIgnoreSerializedAnnotations(const bool flag)
0278     {
0279         fIgnoreSerializedAnnotations = flag;
0280     };
0281     inline bool getIgnoreSerializedAnnotations() const
0282     {
0283         return fIgnoreSerializedAnnotations;
0284     };
0285
0286 protected :
0287     // -----------------------------------------------------------------------
0288     /**  Hidden Constructors */
0289     // -----------------------------------------------------------------------
0290     //@{
0291     XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
0292     :fMemMgr(memMgr)
0293     ,fIgnoreSerializedAnnotations(false)
0294     {
0295     };
0296     //@}
0297
0298 private :
0299     // -----------------------------------------------------------------------
0300     /** name  Unimplemented copy constructor and operator= */
0301     // -----------------------------------------------------------------------
0302     //@{
0303     XMLGrammarPool(const XMLGrammarPool& );
0304     XMLGrammarPool& operator=(const XMLGrammarPool& );
0305     //@}
0306
0307     // -----------------------------------------------------------------------
0308     //
0309     // fMemMgr: plugged-in (or defaulted-in) memory manager
0310     //          not owned
0311     //          no reset after initialization
0312     //
0313     // -----------------------------------------------------------------------
0314
0315     MemoryManager* const  fMemMgr;
0316     bool fIgnoreSerializedAnnotations;
0317
0318 };
0319
0320 XERCES_CPP_NAMESPACE_END
0321
0322 #endif