xercesc/framework/XMLGrammarPoolImpl.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_XMLGRAMMARPOOLIMPL_HPP)
0023 #define XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOLIMPL_HPP
0024
0025 #include <xercesc/framework/XMLGrammarPool.hpp>
0026
0027 XERCES_CPP_NAMESPACE_BEGIN
0028
0029 class XMLSynchronizedStringPool;
0030
0031 class XMLUTIL_EXPORT XMLGrammarPoolImpl : public XMLGrammarPool
0032 {
0033 public :
0034     // -----------------------------------------------------------------------
0035     /** @name constructor and destructor */
0036     // -----------------------------------------------------------------------
0037     //@{
0038
0039     XMLGrammarPoolImpl(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager);
0040
0041     ~XMLGrammarPoolImpl();
0042     //@}
0043
0044     // -----------------------------------------------------------------------
0045     /** @name Implementation of Grammar Pool Interface */
0046     // -----------------------------------------------------------------------
0047     //@{
0048
0049     /**
0050       * cacheGrammar
0051       *
0052       * Provide the grammar pool with an opportunity
0053       * to cache the given grammar.  If the pool does not choose to do so,
0054       * it should return false; otherwise, it should return true, so that
0055       * the caller knows whether the grammar has been adopted.
0056       *
0057       * @param gramToCache: the Grammar to be cached in the grammar pool
0058       * @return true if the grammar pool has elected to cache the grammar (in which case
0059       * it is assumed to have adopted it); false if it does not cache it
0060       *
0061       */
0062     virtual bool           cacheGrammar(Grammar* const               gramToCache);
0063
0064
0065     /**
0066       * retrieveGrammar
0067       *
0068       * @param gramDesc: the Grammar Description used to search for grammar
0069       *                  cached in the grammar pool
0070       *
0071       */
0072     virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc);
0073
0074
0075     /**
0076       * orphanGrammar
0077       *
0078       * grammar removed from the grammar pool and owned by the caller
0079       *
0080       * @param nameSpaceKey: Key used to search for grammar in the grammar pool
0081       *
0082       */
0083     virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey);
0084
0085
0086     /**
0087      * Get an enumeration of the cached Grammars in the Grammar pool
0088      *
0089      * @return enumeration of the cached Grammars in Grammar pool
0090      */
0091     virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const;
0092
0093     /**
0094       * clear
0095       *
0096       * all grammars are removed from the grammar pool and deleted.
0097       * @return true if the grammar pool was cleared. false if it did not.
0098       */
0099     virtual bool           clear();
0100
0101     /**
0102       * lockPool
0103       *
0104       * When this method is called by the application, the
0105       * grammar pool should stop adding new grammars to the cache.
0106       */
0107     virtual void           lockPool();
0108
0109     /**
0110       * unlockPool
0111       *
0112       * After this method has been called, the grammar pool implementation
0113       * should return to its default behaviour when cacheGrammars(...) is called.
0114       *
0115       * For PSVI support any previous XSModel that was produced will be deleted.
0116       */
0117     virtual void           unlockPool();
0118
0119     //@}
0120
0121     // -----------------------------------------------------------------------
0122     /** @name  Implementation of Factory interface */
0123     // -----------------------------------------------------------------------
0124     //@{
0125
0126     /**
0127       * createDTDGrammar
0128       *
0129       */
0130     virtual DTDGrammar*            createDTDGrammar();
0131
0132     /**
0133       * createSchemaGrammar
0134       *
0135       */
0136     virtual SchemaGrammar*         createSchemaGrammar();
0137
0138     /**
0139       * createDTDDescription
0140       *
0141       */
0142     virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const systemId);
0143     /**
0144       * createSchemaDescription
0145       *
0146       */
0147     virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace);
0148     //@}
0149
0150     // -----------------------------------------------------------------------
0151     /** @name  schema component model support */
0152     // -----------------------------------------------------------------------
0153     //@{
0154
0155     /***
0156       * Return an XSModel derived from the components of all SchemaGrammars
0157       * in the grammar pool.  If the pool is locked, this should
0158       * be a thread-safe operation.
0159       *
0160       * NOTE: The function should NEVER return NULL.  If there are no grammars in
0161       *       the pool it should return an XSModel containing the Schema for Schema.
0162       *
0163       * Calling getXSModel() on an unlocked grammar pool may result in the
0164       * creation of a new XSModel with the old XSModel being deleted.
0165       * The bool parameter will indicate if the XSModel was changed.
0166       *
0167       * In this implementation, when the pool is not locked a new XSModel will be
0168       * computed each this time the pool is called if the pool has changed (and the
0169       * previous one will be destroyed at that time).  When the lockPool()
0170       * method is called, an XSModel will be generated and returned whenever this method is called
0171       * while the pool is in the locked state.  This will be destroyed if the unlockPool()
0172       * operation is called.  The XSModel will not be serialized,
0173       * but will be recreated if a deserialized pool is in the
0174       * locked state.
0175       *
0176       */
0177     virtual XSModel *getXSModel(bool& XSModelWasChanged);
0178
0179     // @}
0180     // -----------------------------------------------------------------------
0181     /** @name  Getter */
0182     // -----------------------------------------------------------------------
0183     //@{
0184
0185     /**
0186       * Return an XMLStringPool for use by validation routines.
0187       * Implementations should not create a string pool on each call to this
0188       * method, but should maintain one string pool for all grammars
0189       * for which this pool is responsible.
0190       */
0191     virtual XMLStringPool *getURIStringPool();
0192
0193     // @}
0194
0195     // -----------------------------------------------------------------------
0196     // serialization and deserialization support
0197     // -----------------------------------------------------------------------
0198
0199     /***
0200       *
0201       * Multiple serializations
0202       *
0203       *    For multiple serializations, if the same file name is given, then the
0204       *    last result will be in the file (overwriting mode), if different file
0205       *    names are given, then there are multiple data stores for each serialization.
0206       *
0207       * Multiple deserializations
0208       *
0209       *    Not supported
0210       *
0211       * Versioning
0212       *
0213       *    Only binary data serialized with the current XercesC Version and
0214       *    SerializationLevel is supported.
0215       *
0216       * Clean up
0217       *
0218       *    In the event of an exception thrown due to a corrupted data store during
0219       *    deserialization, this implementation may not be able to clean up all resources
0220       *    allocated, and therefore it is the client application's responsibility to
0221       *    clean up those unreleased resources.
0222       *
0223       * Coupling of Grammars and StringPool
0224       *
0225       *    This implementation assumes that StringPool shall always be
0226       *    serialized/deserialized together with the grammars. In the case that such a
0227       *    coupling is not desired, client application can modify this behaviour by
0228       *    either derivate from this imlementation and overwrite the serializeGrammars()
0229       *    and/or deserializeGrammars() to decouple grammars and string pool, or
0230       *    Once deserializeGrammars() is done, insert another StringPool through
0231       *    setStringPool().
0232       *
0233       *    Client application shall be aware of the unpredicatable/undefined consequence
0234       *    of this decoupling.
0235       */
0236
0237     virtual void     serializeGrammars(BinOutputStream* const);
0238     virtual void     deserializeGrammars(BinInputStream* const);
0239
0240 private:
0241
0242     virtual void    createXSModel();
0243
0244     void
0245     cleanUp();
0246
0247     // -----------------------------------------------------------------------
0248     /** name  Unimplemented copy constructor and operator= */
0249     // -----------------------------------------------------------------------
0250     //@{
0251     XMLGrammarPoolImpl(const XMLGrammarPoolImpl& );
0252     XMLGrammarPoolImpl& operator=(const XMLGrammarPoolImpl& );
0253     //@}
0254
0255     // -----------------------------------------------------------------------
0256     //
0257     // fGrammarRegistry:
0258     //
0259     //    container
0260     // fStringPool
0261     //    grammars need a string pool for URI -> int mappings
0262     // fSynchronizedStringPool
0263     //      When the grammar pool is locked, provide a string pool
0264     //      that can be updated in a thread-safe manner.
0265     // fLocked
0266     //      whether the pool has been locked
0267     //
0268     // -----------------------------------------------------------------------
0269     RefHashTableOf<Grammar>*            fGrammarRegistry;
0270     XMLStringPool*                      fStringPool;
0271     XMLSynchronizedStringPool*          fSynchronizedStringPool;
0272     XSModel*                            fXSModel;
0273     bool                                fLocked;
0274     bool                                fXSModelIsValid;
0275 };
0276
0277 XERCES_CPP_NAMESPACE_END
0278
0279 #endif