KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > org > apache > xerces > internal > xni > grammars > XMLGrammarPool


1 /*
2  * The Apache Software License, Version 1.1
3  *
4  *
5  * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
6  * reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Apache Software Foundation (http://www.apache.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Xerces" and "Apache Software Foundation" must
28  * not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation and was
52  * originally based on software copyright (c) 1999, International
53  * Business Machines, Inc., http://www.apache.org. For more
54  * information on the Apache Software Foundation, please see
55  * <http://www.apache.org/>.
56  */
57 package com.sun.org.apache.xerces.internal.xni.grammars;
58
59 /**
60  * <p> This interface specifies how the parser and the application
61  * interact with respect to Grammar objects that the application
62  * possesses--either by having precompiled them or by having stored them
63  * from a previous validation of an instance document. It makes no
64  * assumptions about the kind of Grammar involved, or about how the
65  * application's storage mechanism works.</p>
66  *
67  * <p>The interaction works as follows:
68  * <ul>
69  * <li>When a validator considers a document, it is expected to request
70  * grammars of the type it can handle from this object using the
71  * <code>retrieveInitialGrammarSet</code> method. </li>
72  * <li>If it requires a grammar
73  * not in this set, it will request it from this Object using the
74  * <code>retrieveGrammar</code> method. </li>
75  * <li> After successfully validating an
76  * instance, the validator should make any new grammars it has compiled
77  * available to this object using the <code>cacheGrammars</code>
78  * method; for ease of implementation it may make other Grammars it holds references to as well (i.e.,
79  * it may return some grammars that were retrieved from the GrammarPool in earlier operations). </li> </ul> </p>
80  *
81  * @author Neil Graham, IBM
82  * @version $Id: XMLGrammarPool.java,v 1.3 2003/11/14 16:54:05 mrglavas Exp $
83  */
84
85 public interface XMLGrammarPool {
86
87     // <p>we are trying to make this XMLGrammarPool work for all kinds of
88 // grammars, so we have a parameter "grammarType" for each of the
89 // methods. </p>
90
91     /**
92      * <p> retrieve the initial known set of grammars. this method is
93      * called by a validator before the validation starts. the application
94      * can provide an initial set of grammars available to the current
95      * validation attempt. </p>
96      * @param grammarType the type of the grammar, from the
97      * <code>com.sun.org.apache.xerces.internal.xni.grammars.Grammar</code> interface.
98      * @return the set of grammars the validator may put in its "bucket"
99      */
100     public Grammar[] retrieveInitialGrammarSet(String JavaDoc grammarType);
101
102     /**
103      * <p>return the final set of grammars that the validator ended up
104      * with.
105      * This method is called after the
106      * validation finishes. The application may then choose to cache some
107      * of the returned grammars. </p>
108      * @param grammarType the type of the grammars being returned;
109      * @param grammars an array containing the set of grammars being
110      * returned; order is not significant.
111      */
112     public void cacheGrammars(String JavaDoc grammarType, Grammar[] grammars);
113
114     /**
115      * <p> This method requests that the application retrieve a grammar
116      * corresponding to the given GrammarIdentifier from its cache.
117      * If it cannot do so it must return null; the parser will then
118      * call the EntityResolver. <strong>An application must not call its
119      * EntityResolver itself from this method; this may result in infinite
120      * recursions.</strong>
121      * @param desc The description of the Grammar being requested.
122      * @return the Grammar corresponding to this description or null if
123      * no such Grammar is known.
124      */
125     public Grammar retrieveGrammar(XMLGrammarDescription desc);
126
127     /**
128      * Causes the XMLGrammarPool not to store any grammars when
129      * the cacheGrammars(String, Grammar[[]) method is called.
130      */
131     public void lockPool();
132
133     /**
134      * Allows the XMLGrammarPool to store grammars when its cacheGrammars(String, Grammar[])
135      * method is called. This is the default state of the object.
136      */
137     public void unlockPool();
138
139     /**
140      * Removes all grammars from the pool.
141      */
142     public void clear();
143 } // XMLGrammarPool
144
145
Popular Tags