| API Docs for SAX and DOM |

Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# 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  * $Log: XMLGrammarPool.hpp,v $
    00019  * Revision 1.14  2004/09/29 19:27:07  cargilld
    00020  * Fix for Jira-1217: fixing problems with getXSModel.
    00021  *
    00022  * Revision 1.13  2004/09/08 13:55:59  peiyongz
    00023  * Apache License Version 2.0
    00024  *
    00025  * Revision 1.12  2004/04/07 14:09:22  peiyongz
    00026  * systemId (to replace rootElemName) as DTDGrammar Key
    00027  *
    00028  * Revision 1.11  2003/11/25 15:10:44  jberry
    00029  * Eliminate some compiler warnings concerning comments inside of comments
    00030  *
    00031  * Revision 1.10  2003/11/21 22:34:45  neilg
    00032  * More schema component model implementation, thanks to David Cargill.
    00033  * In particular, this cleans up and completes the XSModel, XSNamespaceItem,
    00034  * XSAttributeDeclaration and XSAttributeGroup implementations.
    00035  *
    00036  * Revision 1.9  2003/11/06 21:53:52  neilg
    00037  * update grammar pool interface so that cacheGrammar(Grammar) can tell the caller whether the grammar was accepted.  Also fix some documentation errors.
    00038  *
    00039  * Revision 1.8  2003/11/06 15:30:06  neilg
    00040  * first part of PSVI/schema component model implementation, thanks to David Cargill.  This covers setting the PSVIHandler on parser objects, as well as implementing XSNotation, XSSimpleTypeDefinition, XSIDCDefinition, and most of XSWildcard, XSComplexTypeDefinition, XSElementDeclaration, XSAttributeDeclaration and XSAttributeUse.
    00041  *
    00042  * Revision 1.7  2003/11/05 18:19:09  peiyongz
    00043  * Documentation update
    00044  *
    00045  * Revision 1.6  2003/10/29 16:16:48  peiyongz
    00046  * GrammarPool' serialization/deserialization support
    00047  *
    00048  * Revision 1.5  2003/10/10 18:36:03  neilg
    00049  * update XMLGrammarPool interface to make expected behaviour of locked pools better specified, and to add the capability to generate XSModels
    00050  *
    00051  * Revision 1.4  2003/09/16 18:30:54  neilg
    00052  * make Grammar pool be responsible for creating and owning URI string pools.  This is one more step towards having grammars be independent of the parsers involved in their creation
    00053  *
    00054  * Revision 1.3  2003/09/02 08:59:02  gareth
    00055  * Added API to get enumerator of grammars.
    00056  *
    00057  * Revision 1.2  2003/07/31 17:02:42  peiyongz
    00058  * Grammar embed GrammarDescription
    00059  *
    00060  * Revision 1.1  2003/06/20 18:37:39  peiyongz
    00061  * Stateless Grammar Pool :: Part I
    00062  *
    00063  * $Id: XMLGrammarPool.hpp,v 1.14 2004/09/29 19:27:07 cargilld Exp $
    00064  *
    00065  */
    00066
    00067 #if !defined(XMLGRAMMARPOOL_HPP)
    00068 #define XMLGRAMMARPOOL_HPP
    00069
    00070 #include <xercesc/util/PlatformUtils.hpp>
    00071 #include <xercesc/util/RefHashTableOf.hpp>
    00072 #include <xercesc/util/XMemory.hpp>
    00073 #include <xercesc/framework/psvi/XSModel.hpp>
    00074
    00075
    00076 XERCES_CPP_NAMESPACE_BEGIN
    00077
    00078 class Grammar;
    00079 class XMLGrammarDescription;
    00080 class DTDGrammar;
    00081 class SchemaGrammar;
    00082 class XMLDTDDescription;
    00083 class XMLSchemaDescription;
    00084 class XMLStringPool;
    00085 class BinInputStream;
    00086 class BinOutputStream;
    00087
    00088 class  XMLGrammarPool : public XMemory
    00089 {
    00090 public :
    00091     // -----------------------------------------------------------------------
    00093     // -----------------------------------------------------------------------
    00095
    00100     virtual ~XMLGrammarPool(){};
    00102
    00103     // -----------------------------------------------------------------------
    00105     // -----------------------------------------------------------------------
    00107
    00121     virtual bool           cacheGrammar(Grammar* const               gramToCache) = 0;
    00122
    00130     virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
    00131
    00132
    00141     virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
    00142
    00143
    00149     virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
    00150
    00157     virtual bool           clear() = 0;
    00158
    00168     virtual void           lockPool() = 0;
    00169
    00180     virtual void           unlockPool() = 0;
    00181
    00183
    00184     // -----------------------------------------------------------------------
    00186     // -----------------------------------------------------------------------
    00188
    00193     virtual DTDGrammar*            createDTDGrammar() = 0;
    00194
    00199     virtual SchemaGrammar*         createSchemaGrammar() = 0;
    00200
    00205     virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const systemId) = 0;
    00210     virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace) = 0;
    00211
    00213
    00214     // -----------------------------------------------------------------------
    00216     // -----------------------------------------------------------------------
    00218
    00219     /***
    00220       * Return an XSModel derived from the components of all SchemaGrammars
    00221       * in the grammar pool.  If the pool is locked, this should
    00222       * be a thread-safe operation.  It should return null if and only if
    00223       * the pool is empty.
    00224       *
    00225       * Calling getXSModel() on an unlocked grammar pool may result in the
    00226       * creation of a new XSModel with the old XSModel being deleted.  The
    00227       * function will return a different address for the XSModel if it has
    00228       * changed.
    00229       *
    00230       * @deprecated (shouldn't use address to determine if XSModel changed)
    00231       */
    00232     virtual XSModel *getXSModel() = 0;
    00233
    00234     /***
    00235       * Return an XSModel derived from the components of all SchemaGrammars
    00236       * in the grammar pool.  If the pool is locked, this should
    00237       * be a thread-safe operation.
    00238       *
    00239       * NOTE: The function should NEVER return NULL.  If there are no grammars in
    00240       *       the pool it should return an XSModel containing the Schema for Schema.
    00241       *
    00242       * Calling getXSModel() on an unlocked grammar pool may result in the
    00243       * creation of a new XSModel with the old XSModel being deleted.
    00244       * The bool parameter will indicate if the XSModel was changed.
    00245       *
    00246       * For source code compatibility, default implementation is to say
    00247       * XSModelWasChanged.
    00248       */
    00249     virtual XSModel *getXSModel(bool& XSModelWasChanged)
    00250     {
    00251         XSModelWasChanged = true;
    00252         return getXSModel();
    00253     }
    00254
    00255     // @}
    00256
    00257     // -----------------------------------------------------------------------
    00259     // -----------------------------------------------------------------------
    00261
    00266     inline MemoryManager* const    getMemoryManager()
    00267     {
    00268         return fMemMgr;
    00269     }
    00270
    00277     virtual XMLStringPool *getURIStringPool() = 0;
    00279
    00280     // -----------------------------------------------------------------------
    00282     // -----------------------------------------------------------------------
    00283
    00284     /***
    00285       *
    00286       * 1. Context: Serialize/Deserialize All Grammars In One Session
    00287       *
    00288       *    Since it is common that a declaration in one grammar may reference
    00289       *    to definitions in other grammars, it is required to serialize those
    00290       *    related (or interdependent) grammars in to one persistent data store
    00291       *    in one serialization session (storing), and deserialize them from the
    00292       *    persistent data store in one deserialization session (loading) back
    00293       *    to the grammar pool.
    00294       *
    00295       * 2. Multiple serializations
    00296       *
    00297       *    It is acceptable that client application requests more than one
    00298       *    grammar serialization on a particular grammar pool, to track the
    00299       *    different grammars cached, or for whatever reasons that client
    00300       *    application is interested in.
    00301       *
    00302       * 3. Multiple deserializations
    00303       *
    00304       *    Request for grammar deserialization either after the grammar pool has
    00305       *    its own cached grammars, or request for more than one grammar
    00306       *    deserialization, may cause undesired and unpredictable consequence
    00307       *    and therefore client application shall be aware that individual
    00308       *    implementationis may NOT support this.
    00309       *
    00310       *    However it is strongly recommended that the client application requests
    00311       *    no more than one grammar deserialization even a particular implementation
    00312       *    may allow multiple deserializations.
    00313       *
    00314       * 4. Locking
    00315       *
    00316       *    Both serialization and deserialization requires to lock the grammar pool
    00317       *    before operation and unlock after operation. In the case the grammar pool
    00318       *    is locked by a third party, the request for serialization/deserialization
    00319       *    will NOT be entertained.
    00320       *
    00321       * 5. Versioning
    00322       *
    00323       *    The Persistent data store has a version tag to be verified during
    00324       *    deserialization, thus a grammar pool may decide if it supports
    00325       *    a binary data created by a different release of Xerces.
    00326       *
    00327       * 6. Clean up
    00328       *
    00329       *    The client application shall be aware that in the event of an exception
    00330       *    thrown due to a corrupted data store during deserialization, implementation
    00331       *    may not be able to clean up all resources allocated, and therefore it is
    00332       *    client application's responsibility to clean up those unreleased resources.
    00333       *
    00334       *
    00335       */
    00336     virtual void     serializeGrammars(BinOutputStream* const)  = 0;
    00337     virtual void     deserializeGrammars(BinInputStream* const) = 0;
    00338
    00339 protected :
    00340     // -----------------------------------------------------------------------
    00342     // -----------------------------------------------------------------------
    00344     XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
    00345     :fMemMgr(memMgr)
    00346     {
    00347     };
    00349
    00350 private :
    00351     // -----------------------------------------------------------------------
    00353     // -----------------------------------------------------------------------
    00355     XMLGrammarPool(const XMLGrammarPool& );
    00356     XMLGrammarPool& operator=(const XMLGrammarPool& );
    00358
    00359     // -----------------------------------------------------------------------
    00360     //
    00361     // fMemMgr: plugged-in (or defaulted-in) memory manager
    00362     //          not owned
    00363     //          no reset after initialization
    00364     //
    00365     // -----------------------------------------------------------------------
    00366
    00367     MemoryManager* const  fMemMgr;
    00368
    00369 };
    00370
    00371 XERCES_CPP_NAMESPACE_END
    00372
    00373 #endif

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