KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xerces > xni > grammars > XMLGrammarPool


1 /*
2  * Copyright 2000-2002,2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.xerces.xni.grammars;
17
18 /**
19  * <p> This interface specifies how the parser and the application
20  * interact with respect to Grammar objects that the application
21  * possesses--either by having precompiled them or by having stored them
22  * from a previous validation of an instance document. It makes no
23  * assumptions about the kind of Grammar involved, or about how the
24  * application's storage mechanism works.</p>
25  *
26  * <p>The interaction works as follows:
27  * <ul>
28  * <li>When a validator considers a document, it is expected to request
29  * grammars of the type it can handle from this object using the
30  * <code>retrieveInitialGrammarSet</code> method. </li>
31  * <li>If it requires a grammar
32  * not in this set, it will request it from this Object using the
33  * <code>retrieveGrammar</code> method. </li>
34  * <li> After successfully validating an
35  * instance, the validator should make any new grammars it has compiled
36  * available to this object using the <code>cacheGrammars</code>
37  * method; for ease of implementation it may make other Grammars it holds references to as well (i.e.,
38  * it may return some grammars that were retrieved from the GrammarPool in earlier operations). </li> </ul> </p>
39  *
40  * @author Neil Graham, IBM
41  * @version $Id: XMLGrammarPool.java,v 1.4 2004/02/24 23:15:58 mrglavas Exp $
42  */
43
44 public interface XMLGrammarPool {
45
46     // <p>we are trying to make this XMLGrammarPool work for all kinds of
47 // grammars, so we have a parameter "grammarType" for each of the
48 // methods. </p>
49
50     /**
51      * <p> retrieve the initial known set of grammars. this method is
52      * called by a validator before the validation starts. the application
53      * can provide an initial set of grammars available to the current
54      * validation attempt. </p>
55      * @param grammarType the type of the grammar, from the
56      * <code>org.apache.xerces.xni.grammars.Grammar</code> interface.
57      * @return the set of grammars the validator may put in its "bucket"
58      */
59     public Grammar[] retrieveInitialGrammarSet(String JavaDoc grammarType);
60
61     /**
62      * <p>return the final set of grammars that the validator ended up
63      * with.
64      * This method is called after the
65      * validation finishes. The application may then choose to cache some
66      * of the returned grammars. </p>
67      * @param grammarType the type of the grammars being returned;
68      * @param grammars an array containing the set of grammars being
69      * returned; order is not significant.
70      */
71     public void cacheGrammars(String JavaDoc grammarType, Grammar[] grammars);
72
73     /**
74      * <p> This method requests that the application retrieve a grammar
75      * corresponding to the given GrammarIdentifier from its cache.
76      * If it cannot do so it must return null; the parser will then
77      * call the EntityResolver. <strong>An application must not call its
78      * EntityResolver itself from this method; this may result in infinite
79      * recursions.</strong>
80      * @param desc The description of the Grammar being requested.
81      * @return the Grammar corresponding to this description or null if
82      * no such Grammar is known.
83      */
84     public Grammar retrieveGrammar(XMLGrammarDescription desc);
85
86     /**
87      * Causes the XMLGrammarPool not to store any grammars when
88      * the cacheGrammars(String, Grammar[[]) method is called.
89      */
90     public void lockPool();
91
92     /**
93      * Allows the XMLGrammarPool to store grammars when its cacheGrammars(String, Grammar[])
94      * method is called. This is the default state of the object.
95      */
96     public void unlockPool();
97
98     /**
99      * Removes all grammars from the pool.
100      */
101     public void clear();
102 } // XMLGrammarPool
103
104
Popular Tags