| 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  * The Apache Software License, Version 1.1
    00003  *
    00004  * Copyright (c) 1999-2003 The Apache Software Foundation.  All rights
    00005  * reserved.
    00006  *
    00007  * Redistribution and use in source and binary forms, with or without
    00008  * modification, are permitted provided that the following conditions
    00009  * are met:
    00010  *
    00011  * 1. Redistributions of source code must retain the above copyright
    00012  *    notice, this list of conditions and the following disclaimer.
    00013  *
    00014  * 2. Redistributions in binary form must reproduce the above copyright
    00015  *    notice, this list of conditions and the following disclaimer in
    00016  *    the documentation and/or other materials provided with the
    00017  *    distribution.
    00018  *
    00019  * 3. The end-user documentation included with the redistribution,
    00020  *    if any, must include the following acknowledgment:
    00021  *       "This product includes software developed by the
    00022  *        Apache Software Foundation (http://www.apache.org/)."
    00023  *    Alternately, this acknowledgment may appear in the software itself,
    00024  *    if and wherever such third-party acknowledgments normally appear.
    00025  *
    00026  * 4. The names "Xerces" and "Apache Software Foundation" must
    00027  *    not be used to endorse or promote products derived from this
    00028  *    software without prior written permission. For written
    00029  *    permission, please contact apache\@apache.org.
    00030  *
    00031  * 5. Products derived from this software may not be called "Apache",
    00032  *    nor may "Apache" appear in their name, without prior written
    00033  *    permission of the Apache Software Foundation.
    00034  *
    00035  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
    00036  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    00037  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    00038  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
    00039  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    00040  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    00041  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
    00042  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    00043  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    00044  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    00045  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    00046  * SUCH DAMAGE.
    00047  * ====================================================================
    00048  *
    00049  * This software consists of voluntary contributions made by many
    00050  * individuals on behalf of the Apache Software Foundation, and was
    00051  * originally based on software copyright (c) 1999, International
    00052  * Business Machines, Inc., http://www.ibm.com .  For more information
    00053  * on the Apache Software Foundation, please see
    00054  * <http://www.apache.org/>.
    00055  */
    00056
    00057 /*
    00058  * $Log: XMLGrammarPool.hpp,v $
    00059  * Revision 1.11  2003/11/25 15:10:44  jberry
    00060  * Eliminate some compiler warnings concerning comments inside of comments
    00061  *
    00062  * Revision 1.10  2003/11/21 22:34:45  neilg
    00063  * More schema component model implementation, thanks to David Cargill.
    00064  * In particular, this cleans up and completes the XSModel, XSNamespaceItem,
    00065  * XSAttributeDeclaration and XSAttributeGroup implementations.
    00066  *
    00067  * Revision 1.9  2003/11/06 21:53:52  neilg
    00068  * update grammar pool interface so that cacheGrammar(Grammar) can tell the caller whether the grammar was accepted.  Also fix some documentation errors.
    00069  *
    00070  * Revision 1.8  2003/11/06 15:30:06  neilg
    00071  * 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.
    00072  *
    00073  * Revision 1.7  2003/11/05 18:19:09  peiyongz
    00074  * Documentation update
    00075  *
    00076  * Revision 1.6  2003/10/29 16:16:48  peiyongz
    00077  * GrammarPool' serialization/deserialization support
    00078  *
    00079  * Revision 1.5  2003/10/10 18:36:03  neilg
    00080  * update XMLGrammarPool interface to make expected behaviour of locked pools better specified, and to add the capability to generate XSModels
    00081  *
    00082  * Revision 1.4  2003/09/16 18:30:54  neilg
    00083  * 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
    00084  *
    00085  * Revision 1.3  2003/09/02 08:59:02  gareth
    00086  * Added API to get enumerator of grammars.
    00087  *
    00088  * Revision 1.2  2003/07/31 17:02:42  peiyongz
    00089  * Grammar embed GrammarDescription
    00090  *
    00091  * Revision 1.1  2003/06/20 18:37:39  peiyongz
    00092  * Stateless Grammar Pool :: Part I
    00093  *
    00094  * $Id: XMLGrammarPool.hpp,v 1.11 2003/11/25 15:10:44 jberry Exp $
    00095  *
    00096  */
    00097
    00098 #if !defined(XMLGRAMMARPOOL_HPP)
    00099 #define XMLGRAMMARPOOL_HPP
    00100
    00101 #include <xercesc/util/PlatformUtils.hpp>
    00102 #include <xercesc/util/RefHashTableOf.hpp>
    00103 #include <xercesc/util/XMemory.hpp>
    00104 #include <xercesc/framework/psvi/XSModel.hpp>
    00105
    00106
    00107 XERCES_CPP_NAMESPACE_BEGIN
    00108
    00109 class Grammar;
    00110 class XMLGrammarDescription;
    00111 class DTDGrammar;
    00112 class SchemaGrammar;
    00113 class XMLDTDDescription;
    00114 class XMLSchemaDescription;
    00115 class XMLStringPool;
    00116 class BinInputStream;
    00117 class BinOutputStream;
    00118
    00119 class  XMLGrammarPool : public XMemory
    00120 {
    00121 public :
    00122     // -----------------------------------------------------------------------
    00124     // -----------------------------------------------------------------------
    00126
    00131     virtual ~XMLGrammarPool(){};
    00133
    00134     // -----------------------------------------------------------------------
    00136     // -----------------------------------------------------------------------
    00138
    00152     virtual bool           cacheGrammar(Grammar* const               gramToCache) = 0;
    00153
    00161     virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
    00162
    00163
    00172     virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
    00173
    00174
    00180     virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
    00181
    00188     virtual bool           clear() = 0;
    00189
    00199     virtual void           lockPool() = 0;
    00200
    00211     virtual void           unlockPool() = 0;
    00212
    00214
    00215     // -----------------------------------------------------------------------
    00217     // -----------------------------------------------------------------------
    00219
    00224     virtual DTDGrammar*            createDTDGrammar() = 0;
    00225
    00230     virtual SchemaGrammar*         createSchemaGrammar() = 0;
    00231
    00236     virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const rootName) = 0;
    00241     virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace) = 0;
    00242
    00244
    00245     // -----------------------------------------------------------------------
    00247     // -----------------------------------------------------------------------
    00249
    00250     /***
    00251       * Return an XSModel derived from the components of all SchemaGrammars
    00252       * in the grammar pool.  If the pool is locked, this should
    00253       * be a thread-safe operation.  It should return null if and only if
    00254       * the pool is empty.
    00255       *
    00256       * Calling getXSModel() on an unlocked grammar pool may result in the
    00257       * creation of a new XSModel with the old XSModel being deleted.  The
    00258       * function will return a different address for the XSModel if it has
    00259       * changed.
    00260       */
    00261     virtual XSModel *getXSModel() = 0;
    00262
    00263     // @}
    00264
    00265     // -----------------------------------------------------------------------
    00267     // -----------------------------------------------------------------------
    00269
    00274     inline MemoryManager* const    getMemoryManager()
    00275     {
    00276         return fMemMgr;
    00277     }
    00278
    00285     virtual XMLStringPool *getURIStringPool() = 0;
    00287
    00288     // -----------------------------------------------------------------------
    00290     // -----------------------------------------------------------------------
    00291
    00292     /***
    00293       *
    00294       * 1. Context: Serialize/Deserialize All Grammars In One Session
    00295       *
    00296       *    Since it is common that a declaration in one grammar may reference
    00297       *    to definitions in other grammars, it is required to serialize those
    00298       *    related (or interdependent) grammars in to one persistent data store
    00299       *    in one serialization session (storing), and deserialize them from the
    00300       *    persistent data store in one deserialization session (loading) back
    00301       *    to the grammar pool.
    00302       *
    00303       * 2. Multiple serializations
    00304       *
    00305       *    It is acceptable that client application requests more than one
    00306       *    grammar serialization on a particular grammar pool, to track the
    00307       *    different grammars cached, or for whatever reasons that client
    00308       *    application is interested in.
    00309       *
    00310       * 3. Multiple deserializations
    00311       *
    00312       *    Request for grammar deserialization either after the grammar pool has
    00313       *    its own cached grammars, or request for more than one grammar
    00314       *    deserialization, may cause undesired and unpredictable consequence
    00315       *    and therefore client application shall be aware that individual
    00316       *    implementationis may NOT support this.
    00317       *
    00318       *    However it is strongly recommended that the client application requests
    00319       *    no more than one grammar deserialization even a particular implementation
    00320       *    may allow multiple deserializations.
    00321       *
    00322       * 4. Locking
    00323       *
    00324       *    Both serialization and deserialization requires to lock the grammar pool
    00325       *    before operation and unlock after operation. In the case the grammar pool
    00326       *    is locked by a third party, the request for serialization/deserialization
    00327       *    will NOT be entertained.
    00328       *
    00329       * 5. Versioning
    00330       *
    00331       *    The Persistent data store has a version tag to be verified during
    00332       *    deserialization, thus a grammar pool may decide if it supports
    00333       *    a binary data created by a different release of Xerces.
    00334       *
    00335       * 6. Clean up
    00336       *
    00337       *    The client application shall be aware that in the event of an exception
    00338       *    thrown due to a corrupted data store during deserialization, implementation
    00339       *    may not be able to clean up all resources allocated, and therefore it is
    00340       *    client application's responsibility to clean up those unreleased resources.
    00341       *
    00342       *
    00343       */
    00344     virtual void     serializeGrammars(BinOutputStream* const)  = 0;
    00345     virtual void     deserializeGrammars(BinInputStream* const) = 0;
    00346
    00347 protected :
    00348     // -----------------------------------------------------------------------
    00350     // -----------------------------------------------------------------------
    00352     XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
    00353     :fMemMgr(memMgr)
    00354     {
    00355     };
    00357
    00358 private :
    00359     // -----------------------------------------------------------------------
    00361     // -----------------------------------------------------------------------
    00363     XMLGrammarPool(const XMLGrammarPool& );
    00364     XMLGrammarPool& operator=(const XMLGrammarPool& );
    00366
    00367     // -----------------------------------------------------------------------
    00368     //
    00369     // fMemMgr: plugged-in (or defaulted-in) memory manager
    00370     //          not owned
    00371     //          no reset after initialization
    00372     //
    00373     // -----------------------------------------------------------------------
    00374
    00375     MemoryManager* const  fMemMgr;
    00376
    00377 };
    00378
    00379 XERCES_CPP_NAMESPACE_END
    00380
    00381 #endif

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