source: icXML/icXML-devel/src/icxercesc/framework/XMLGrammarPool.hpp @ 2720

Last change on this file since 2720 was 2720, checked in by cameron, 6 years ago

Initial check-in of icXML 0.8 source files

File size: 9.8 KB
Line 
1/*
2 * Unless required by applicable law or agreed to in writing, software
3 * distributed under the License is distributed on an "AS IS" BASIS,
4 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
5 * See the License for the specific language governing permissions and
6 * limitations under the License.
7 */
8
9/*
10 * $Id: XMLGrammarPool.hpp 527149 2007-04-10 14:56:39Z amassari $
11 */
12
13#if !defined(XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP)
14#define XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP
15
16#include <xercesc/util/PlatformUtils.hpp>
17#include <xercesc/util/RefHashTableOf.hpp>
18#include <xercesc/util/XMemory.hpp>
19#include <xercesc/framework/psvi/XSModel.hpp>
20#include <icxmlc/XMLConfig.hpp>
21#ifdef TEST_NAMESPACE_RESOLVER
22#include <icxmlc/XMLNamespaceResolver.hpp>
23#endif
24
25XERCES_CPP_NAMESPACE_BEGIN
26
27class Grammar;
28class XMLGrammarDescription;
29class DTDGrammar;
30class SchemaGrammar;
31class XMLDTDDescription;
32class XMLSchemaDescription;
33class XMLStringPool;
34class BinInputStream;
35class BinOutputStream;
36
37class XMLPARSER_EXPORT XMLGrammarPool : public XMemory
38{
39public :
40        // -----------------------------------------------------------------------
41        /** @name Virtual destructor for derived classes */
42        // -----------------------------------------------------------------------
43        //@{
44
45        /**
46          * virtual destructor
47          *
48          */
49        virtual ~XMLGrammarPool(){};
50        //@}
51
52        // -----------------------------------------------------------------------
53        /** @name The Grammar Pool Interface */
54        // -----------------------------------------------------------------------
55        //@{
56
57        /**
58          * cacheGrammar
59          *
60          * Provide the grammar pool with an opportunity
61          * to cache the given grammar.  If the pool does not choose to do so,
62          * it should return false; otherwise, it should return true, so that
63          * the caller knows whether the grammar has been adopted.
64          *
65          * @param gramToCache the Grammar to be cached in the grammar pool
66          * @return true if the grammar pool has elected to cache the grammar (in which case
67          * it is assumed to have adopted it); false if it does not cache it
68          *
69          */
70        virtual bool           cacheGrammar(Grammar* const               gramToCache) = 0;
71
72        /**
73          * retrieveGrammar
74          *
75          * @param gramDesc the Grammar Description used to search for grammar
76          *                  cached in the grammar pool
77          *
78          */
79        virtual Grammar*       retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
80
81
82        /**
83          * orphanGrammar
84          *
85          * grammar removed from the grammar pool and owned by the caller
86          *
87          * @param nameSpaceKey Key used to search for grammar in the grammar pool
88          * @return the grammar that was removed from the pool (0 if none)
89          */
90        virtual Grammar*       orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
91
92
93        /**
94         * Get an enumeration of the cached Grammars in the Grammar pool
95         *
96         * @return enumeration of the cached Grammars in Grammar pool
97         */
98        virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
99
100        /**
101          * clear
102          *
103          * all grammars are removed from the grammar pool and deleted.
104          * @return true if the grammar pool was cleared. false if it did not.
105          */
106        virtual bool           clear() = 0;
107
108        /**
109          * lockPool
110          *
111          * When this method is called by the application, the
112          * grammar pool should stop adding new grammars to the cache.
113          * This should result in the grammar pool being sharable
114          * among parsers operating in different threads.
115          *
116          */
117        virtual void           lockPool() = 0;
118
119        /**
120          * unlockPool
121          *
122          * After this method has been called, the grammar pool implementation
123          * should return to its default behaviour when cacheGrammars(...) is called.
124          * One effect, depending on the underlying implementation, is that the grammar pool
125          * may no longer be thread-safe (even on read operations).
126          *
127          * For PSVI support any previous XSModel that was produced will be deleted.
128          */
129        virtual void           unlockPool() = 0;
130
131        //@}
132
133        // -----------------------------------------------------------------------
134        /** @name  Factory interface */
135        // -----------------------------------------------------------------------
136        //@{
137
138        /**
139          * createDTDGrammar
140          *
141          */
142        virtual DTDGrammar*            createDTDGrammar() = 0;
143
144        /**
145          * createSchemaGrammar
146          *
147          */
148        virtual SchemaGrammar*         createSchemaGrammar() = 0;
149
150        /**
151          * createDTDDescription
152          *
153          */
154        virtual XMLDTDDescription*     createDTDDescription(const XMLCh* const systemId) = 0;
155        /**
156          * createSchemaDescription
157          *
158          */
159        virtual XMLSchemaDescription*  createSchemaDescription(const XMLCh* const targetNamespace) = 0;
160
161        //@}
162
163        // -----------------------------------------------------------------------
164        /** @name  schema component model support */
165        // -----------------------------------------------------------------------
166        //@{
167
168        /***
169          * Return an XSModel derived from the components of all SchemaGrammars
170          * in the grammar pool.  If the pool is locked, this should
171          * be a thread-safe operation.
172          *
173          * NOTE: The function should NEVER return NULL.  If there are no grammars in
174          *       the pool it should return an XSModel containing the Schema for Schema.
175          *
176          * Calling getXSModel() on an unlocked grammar pool may result in the
177          * creation of a new XSModel with the old XSModel being deleted.
178          * The bool parameter will indicate if the XSModel was changed.
179          *
180          */
181        virtual XSModel *getXSModel(bool& XSModelWasChanged) = 0;
182
183        // @}
184
185        // -----------------------------------------------------------------------
186        /** @name  Getter */
187        // -----------------------------------------------------------------------
188        //@{
189
190        /**
191          * getMemoryManager
192          *
193          */
194        inline MemoryManager*    getMemoryManager()
195        {
196                return fMemMgr;
197        }
198
199        // @@ DEPRECATED @@ this function is renamed to getStringPool to highlight the fact it is NOT a URI
200        // string pool, but rather a general string pool.
201        virtual XMLStringPool *getURIStringPool() = 0;
202        //@}
203
204        virtual XMLStringPool *getStringPool() = 0;
205
206        // -----------------------------------------------------------------------
207        /** serialization and deserialization support */
208        // -----------------------------------------------------------------------
209
210        /***
211          *
212          * 1. Context: Serialize/Deserialize All Grammars In One Session
213          *
214          *    Since it is common that a declaration in one grammar may reference
215          *    to definitions in other grammars, it is required to serialize those
216          *    related (or interdependent) grammars in to one persistent data store
217          *    in one serialization session (storing), and deserialize them from the
218          *    persistent data store in one deserialization session (loading) back
219          *    to the grammar pool.
220          *
221          * 2. Multiple serializations
222          *
223          *    It is acceptable that client application requests more than one
224          *    grammar serialization on a particular grammar pool, to track the
225          *    different grammars cached, or for whatever reasons that client
226          *    application is interested in.
227          *
228          * 3. Multiple deserializations
229          *
230          *    Request for grammar deserialization either after the grammar pool has
231          *    its own cached grammars, or request for more than one grammar
232          *    deserialization, may cause undesired and unpredictable consequence
233          *    and therefore client application shall be aware that individual
234          *    implementationis may NOT support this.
235          *
236          *    However it is strongly recommended that the client application requests
237          *    no more than one grammar deserialization even a particular implementation
238          *    may allow multiple deserializations.
239          *
240          * 4. Locking
241          *
242          *    Both serialization and deserialization requires to lock the grammar pool
243          *    before operation and unlock after operation. In the case the grammar pool
244          *    is locked by a third party, the request for serialization/deserialization
245          *    will NOT be entertained.
246          *
247          * 5. Versioning
248          *
249          *    The Persistent data store has a version tag to be verified during
250          *    deserialization, thus a grammar pool may decide if it supports
251          *    a binary data created by a different release of Xerces.
252          *
253          * 6. Clean up
254          *
255          *    The client application shall be aware that in the event of an exception
256          *    thrown due to a corrupted data store during deserialization, implementation
257          *    may not be able to clean up all resources allocated, and therefore it is
258          *    client application's responsibility to clean up those unreleased resources.
259          *
260          *
261          */
262        virtual void     serializeGrammars(BinOutputStream* const)  = 0;
263        virtual void     deserializeGrammars(BinInputStream* const) = 0;
264
265        /*
266         * Set/get a flag to not create XSAnnotations when deserializing the grammar.
267         * Defaults to false (create XSAnnotations when deserializing the grammar).
268         */
269        inline void setIgnoreSerializedAnnotations(const bool flag)
270        {
271                fIgnoreSerializedAnnotations = flag;
272        };
273        inline bool getIgnoreSerializedAnnotations() const
274        {
275                return fIgnoreSerializedAnnotations;
276        };
277
278protected :
279        // -----------------------------------------------------------------------
280        /**  Hidden Constructors */
281        // -----------------------------------------------------------------------
282        //@{
283        XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
284        :fMemMgr(memMgr)
285        ,fIgnoreSerializedAnnotations(false)
286        {
287        };
288        //@}
289
290private :
291        // -----------------------------------------------------------------------
292        /** name  Unimplemented copy constructor and operator= */
293        // -----------------------------------------------------------------------
294        //@{
295        XMLGrammarPool(const XMLGrammarPool& );
296        XMLGrammarPool& operator=(const XMLGrammarPool& );
297        //@}
298
299        // -----------------------------------------------------------------------
300        //
301        // fMemMgr: plugged-in (or defaulted-in) memory manager
302        //          not owned
303        //          no reset after initialization
304        //
305        // -----------------------------------------------------------------------
306
307        MemoryManager* const  fMemMgr;
308        bool fIgnoreSerializedAnnotations;
309
310};
311
312XERCES_CPP_NAMESPACE_END
313
314#endif
Note: See TracBrowser for help on using the repository browser.