source: NonGTP/Xerces/xercesc/framework/XMLGrammarPool.hpp @ 188

Revision 188, 14.6 KB checked in by mattausch, 19 years ago (diff)

added xercesc to support

Line 
1/*
2 * The Apache Software License, Version 1.1
3 *
4 * Copyright (c) 1999-2003 The Apache Software Foundation.  All rights
5 * reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright
12 *    notice, this list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright
15 *    notice, this list of conditions and the following disclaimer in
16 *    the documentation and/or other materials provided with the
17 *    distribution.
18 *
19 * 3. The end-user documentation included with the redistribution,
20 *    if any, must include the following acknowledgment:
21 *       "This product includes software developed by the
22 *        Apache Software Foundation (http://www.apache.org/)."
23 *    Alternately, this acknowledgment may appear in the software itself,
24 *    if and wherever such third-party acknowledgments normally appear.
25 *
26 * 4. The names "Xerces" and "Apache Software Foundation" must
27 *    not be used to endorse or promote products derived from this
28 *    software without prior written permission. For written
29 *    permission, please contact apache\@apache.org.
30 *
31 * 5. Products derived from this software may not be called "Apache",
32 *    nor may "Apache" appear in their name, without prior written
33 *    permission of the Apache Software Foundation.
34 *
35 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46 * SUCH DAMAGE.
47 * ====================================================================
48 *
49 * This software consists of voluntary contributions made by many
50 * individuals on behalf of the Apache Software Foundation, and was
51 * originally based on software copyright (c) 1999, International
52 * Business Machines, Inc., http://www.ibm.com .  For more information
53 * on the Apache Software Foundation, please see
54 * <http://www.apache.org/>.
55 */
56
57/*
58 * $Log: XMLGrammarPool.hpp,v $
59 * Revision 1.11  2003/11/25 15:10:44  jberry
60 * Eliminate some compiler warnings concerning comments inside of comments
61 *
62 * Revision 1.10  2003/11/21 22:34:45  neilg
63 * More schema component model implementation, thanks to David Cargill.
64 * In particular, this cleans up and completes the XSModel, XSNamespaceItem,
65 * XSAttributeDeclaration and XSAttributeGroup implementations.
66 *
67 * Revision 1.9  2003/11/06 21:53:52  neilg
68 * update grammar pool interface so that cacheGrammar(Grammar) can tell the caller whether the grammar was accepted.  Also fix some documentation errors.
69 *
70 * Revision 1.8  2003/11/06 15:30:06  neilg
71 * 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.
72 *
73 * Revision 1.7  2003/11/05 18:19:09  peiyongz
74 * Documentation update
75 *
76 * Revision 1.6  2003/10/29 16:16:48  peiyongz
77 * GrammarPool' serialization/deserialization support
78 *
79 * Revision 1.5  2003/10/10 18:36:03  neilg
80 * update XMLGrammarPool interface to make expected behaviour of locked pools better specified, and to add the capability to generate XSModels
81 *
82 * Revision 1.4  2003/09/16 18:30:54  neilg
83 * 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
84 *
85 * Revision 1.3  2003/09/02 08:59:02  gareth
86 * Added API to get enumerator of grammars.
87 *
88 * Revision 1.2  2003/07/31 17:02:42  peiyongz
89 * Grammar embed GrammarDescription
90 *
91 * Revision 1.1  2003/06/20 18:37:39  peiyongz
92 * Stateless Grammar Pool :: Part I
93 *
94 * $Id: XMLGrammarPool.hpp,v 1.11 2003/11/25 15:10:44 jberry Exp $
95 *
96 */
97
98#if !defined(XMLGRAMMARPOOL_HPP)
99#define XMLGRAMMARPOOL_HPP
100
101#include <xercesc/util/PlatformUtils.hpp>
102#include <xercesc/util/RefHashTableOf.hpp>
103#include <xercesc/util/XMemory.hpp>
104#include <xercesc/framework/psvi/XSModel.hpp>
105
106
107XERCES_CPP_NAMESPACE_BEGIN
108
109class Grammar;
110class XMLGrammarDescription;
111class DTDGrammar;
112class SchemaGrammar;
113class XMLDTDDescription;
114class XMLSchemaDescription;
115class XMLStringPool;
116class BinInputStream;
117class BinOutputStream;
118
119class XMLPARSER_EXPORT XMLGrammarPool : public XMemory
120{
121public :
122    // -----------------------------------------------------------------------
123    /** @name Virtual destructor for derived classes */
124    // -----------------------------------------------------------------------
125    //@{
126
127    /**
128      * virtual destructor
129      *
130      */
131    virtual ~XMLGrammarPool(){};
132    //@}
133
134    // -----------------------------------------------------------------------
135    /** @name The Grammar Pool Interface */
136    // -----------------------------------------------------------------------
137    //@{
138
139    /**
140      * cacheGrammar
141      *
142      * Provide the grammar pool with an opportunity
143      * to cache the given grammar.  If the pool does not choose to do so,
144      * it should return false; otherwise, it should return true, so that
145      * the caller knows whether the grammar has been adopted.
146      *
147      * @param gramToCache: the Grammar to be cached in the grammar pool
148      * @return true if the grammar pool has elected to cache the grammar (in which case
149      * it is assumed to have adopted it); false if it does not cache it
150          *
151      */
152    virtual bool           cacheGrammar(Grammar* const               gramToCache) = 0;
153   
154    /**
155      * retrieveGrammar
156      *
157      * @param gramDesc: the Grammar Description used to search for grammar
158          *                  cached in the grammar pool
159          *
160      */
161    virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
162   
163       
164    /**
165      * orphanGrammar
166      *
167      * grammar removed from the grammar pool and owned by the caller
168      *
169      * @param nameSpaceKey: Key used to search for grammar in the grammar pool
170      * @return the grammar that was removed from the pool (0 if none)
171      */
172    virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey) = 0; 
173
174
175    /**
176     * Get an enumeration of the cached Grammars in the Grammar pool
177     *
178     * @return enumeration of the cached Grammars in Grammar pool
179     */
180    virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
181
182    /**
183      * clear
184      *
185      * all grammars are removed from the grammar pool and deleted.
186      * @return true if the grammar pool was cleared. false if it did not.
187      */
188    virtual bool           clear() = 0;
189       
190    /**
191      * lockPool
192      *
193          * When this method is called by the application, the
194      * grammar pool should stop adding new grammars to the cache.
195      * This should result in the grammar pool being sharable
196      * among parsers operating in different threads.
197      *
198      */
199    virtual void           lockPool() = 0;
200   
201    /**
202      * unlockPool
203      *
204          * After this method has been called, the grammar pool implementation
205      * should return to its default behaviour when cacheGrammars(...) is called.
206      * One effect, depending on the underlying implementation, is that the grammar pool
207      * may no longer be thread-safe (even on read operations).
208      *
209      * For PSVI support any previous XSModel that was produced will be deleted.
210      */
211    virtual void           unlockPool() = 0;
212
213    //@}
214
215    // -----------------------------------------------------------------------
216    /** @name  Factory interface */
217    // -----------------------------------------------------------------------
218    //@{
219
220    /**
221      * createDTDGrammar
222      *
223      */
224    virtual DTDGrammar*            createDTDGrammar() = 0;
225
226    /**
227      * createSchemaGrammar
228      *
229      */
230    virtual SchemaGrammar*         createSchemaGrammar() = 0;
231                   
232    /**
233      * createDTDDescription
234      *
235      */       
236    virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const rootName) = 0;
237    /**
238      * createSchemaDescription
239      *
240      */               
241    virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace) = 0;
242
243    //@}
244
245    // -----------------------------------------------------------------------
246    /** @name  schema component model support */
247    // -----------------------------------------------------------------------                                                       
248    //@{
249
250    /***
251      * Return an XSModel derived from the components of all SchemaGrammars
252      * in the grammar pool.  If the pool is locked, this should
253      * be a thread-safe operation.  It should return null if and only if
254      * the pool is empty.
255      *
256      * Calling getXSModel() on an unlocked grammar pool may result in the
257      * creation of a new XSModel with the old XSModel being deleted.  The
258      * function will return a different address for the XSModel if it has
259      * changed.
260      */
261    virtual XSModel *getXSModel() = 0;
262       
263    // @}
264
265    // -----------------------------------------------------------------------
266    /** @name  Getter */
267    // -----------------------------------------------------------------------                                                       
268    //@{
269
270    /**
271      * getMemoryManager
272      *
273      */   
274        inline MemoryManager* const    getMemoryManager()
275    {
276        return fMemMgr;
277    }
278
279    /**
280      * Return an XMLStringPool for use by validation routines. 
281      * Implementations should not create a string pool on each call to this
282      * method, but should maintain one string pool for all grammars
283      * for which this pool is responsible.
284      */
285    virtual XMLStringPool *getURIStringPool() = 0;
286    //@}
287
288    // -----------------------------------------------------------------------
289    /** serialization and deserialization support */
290    // -----------------------------------------------------------------------                                                       
291
292    /***
293      *
294      * 1. Context: Serialize/Deserialize All Grammars In One Session
295      *
296      *    Since it is common that a declaration in one grammar may reference
297      *    to definitions in other grammars, it is required to serialize those
298      *    related (or interdependent) grammars in to one persistent data store
299      *    in one serialization session (storing), and deserialize them from the
300      *    persistent data store in one deserialization session (loading) back
301      *    to the grammar pool.   
302      *
303      * 2. Multiple serializations
304      *
305      *    It is acceptable that client application requests more than one
306      *    grammar serialization on a particular grammar pool, to track the
307      *    different grammars cached, or for whatever reasons that client
308      *    application is interested in.
309      *
310      * 3. Multiple deserializations
311      *
312      *    Request for grammar deserialization either after the grammar pool has
313      *    its own cached grammars, or request for more than one grammar
314      *    deserialization, may cause undesired and unpredictable consequence
315      *    and therefore client application shall be aware that individual
316      *    implementationis may NOT support this.
317      *
318      *    However it is strongly recommended that the client application requests
319      *    no more than one grammar deserialization even a particular implementation
320      *    may allow multiple deserializations.
321      *
322      * 4. Locking
323      *
324      *    Both serialization and deserialization requires to lock the grammar pool
325      *    before operation and unlock after operation. In the case the grammar pool
326      *    is locked by a third party, the request for serialization/deserialization
327      *    will NOT be entertained.
328      *
329      * 5. Versioning
330      *
331      *    The Persistent data store has a version tag to be verified during
332      *    deserialization, thus a grammar pool may decide if it supports
333      *    a binary data created by a different release of Xerces.
334      *
335      * 6. Clean up
336      *
337      *    The client application shall be aware that in the event of an exception
338      *    thrown due to a corrupted data store during deserialization, implementation
339      *    may not be able to clean up all resources allocated, and therefore it is
340      *    client application's responsibility to clean up those unreleased resources.
341      *
342      *
343      */
344    virtual void     serializeGrammars(BinOutputStream* const)  = 0;
345    virtual void     deserializeGrammars(BinInputStream* const) = 0;       
346           
347protected :
348    // -----------------------------------------------------------------------
349    /**  Hidden Constructors */
350    // -----------------------------------------------------------------------
351    //@{
352    XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
353    :fMemMgr(memMgr)
354    {
355    };
356    //@}
357
358private :
359    // -----------------------------------------------------------------------
360    /** name  Unimplemented copy constructor and operator= */
361    // -----------------------------------------------------------------------
362    //@{
363    XMLGrammarPool(const XMLGrammarPool& );
364    XMLGrammarPool& operator=(const XMLGrammarPool& );
365    //@}
366
367    // -----------------------------------------------------------------------
368    //
369    // fMemMgr: plugged-in (or defaulted-in) memory manager
370    //          not owned
371    //          no reset after initialization
372    //
373    // -----------------------------------------------------------------------
374   
375    MemoryManager* const  fMemMgr;
376
377};
378
379XERCES_CPP_NAMESPACE_END
380
381#endif
Note: See TracBrowser for help on using the repository browser.