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

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

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