KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xerces > xni > parser > XMLParserConfiguration


1 /*
2  * Copyright 2001, 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
17 package org.apache.xerces.xni.parser;
18
19 import java.io.IOException JavaDoc;
20 import java.util.Locale JavaDoc;
21
22 import org.apache.xerces.xni.XMLDocumentHandler;
23 import org.apache.xerces.xni.XMLDTDHandler;
24 import org.apache.xerces.xni.XMLDTDContentModelHandler;
25 import org.apache.xerces.xni.XNIException;
26
27 /**
28  * Represents a parser configuration. The parser configuration maintains
29  * a table of recognized features and properties, assembles components
30  * for the parsing pipeline, and is responsible for initiating parsing
31  * of an XML document.
32  * <p>
33  * By separating the configuration of a parser from the specific parser
34  * instance, applications can create new configurations and re-use the
35  * existing parser components and external API generators (e.g. the
36  * DOMParser and SAXParser).
37  * <p>
38  * The internals of any specific parser configuration instance are hidden.
39  * Therefore, each configuration may implement the parsing mechanism any
40  * way necessary. However, the parser configuration should follow these
41  * guidelines:
42  * <ul>
43  * <li>
44  * Call the <code>reset</code> method on each component before parsing.
45  * This is only required if the configuration is re-using existing
46  * components that conform to the <code>XMLComponent</code> interface.
47  * If the configuration uses all custom parts, then it is free to
48  * implement everything as it sees fit as long as it follows the
49  * other guidelines.
50  * </li>
51  * <li>
52  * Call the <code>setFeature</code> and <code>setProperty</code> method
53  * on each component during parsing to propagate features and properties
54  * that have changed. This is only required if the configuration is
55  * re-using existing components that conform to the <code>XMLComponent</code>
56  * interface. If the configuration uses all custom parts, then it is free
57  * to implement everything as it sees fit as long as it follows the other
58  * guidelines.
59  * </li>
60  * <li>
61  * Pass the same unique String references for all symbols that are
62  * propagated to the registered handlers. Symbols include, but may not
63  * be limited to, the names of elements and attributes (including their
64  * uri, prefix, and localpart). This is suggested but not an absolute
65  * must. However, the standard parser components may require access to
66  * the same symbol table for creation of unique symbol references to be
67  * propagated in the XNI pipeline.
68  * </li>
69  * </ul>
70  *
71  * @author Arnaud Le Hors, IBM
72  * @author Andy Clark, IBM
73  *
74  * @version $Id: XMLParserConfiguration.java,v 1.7 2004/10/03 21:58:18 mrglavas Exp $
75  */
76 public interface XMLParserConfiguration
77     extends XMLComponentManager {
78
79     //
80 // XMLParserConfiguration methods
81 //
82
83     // parsing
84
85     /**
86      * Parse an XML document.
87      * <p>
88      * The parser can use this method to instruct this configuration
89      * to begin parsing an XML document from any valid input source
90      * (a character stream, a byte stream, or a URI).
91      * <p>
92      * Parsers may not invoke this method while a parse is in progress.
93      * Once a parse is complete, the parser may then parse another XML
94      * document.
95      * <p>
96      * This method is synchronous: it will not return until parsing
97      * has ended. If a client application wants to terminate
98      * parsing early, it should throw an exception.
99      * <p>
100      * When this method returns, all characters streams and byte streams
101      * opened by the parser are closed.
102      *
103      * @param inputSource The input source for the top-level of the
104      * XML document.
105      *
106      * @exception XNIException Any XNI exception, possibly wrapping
107      * another exception.
108      * @exception IOException An IO exception from the parser, possibly
109      * from a byte stream or character stream
110      * supplied by the parser.
111      */
112     public void parse(XMLInputSource inputSource)
113         throws XNIException, IOException JavaDoc;
114
115     // generic configuration
116
117     /**
118      * Allows a parser to add parser specific features to be recognized
119      * and managed by the parser configuration.
120      *
121      * @param featureIds An array of the additional feature identifiers
122      * to be recognized.
123      */
124     public void addRecognizedFeatures(String JavaDoc[] featureIds);
125
126     /**
127      * Sets the state of a feature. This method is called by the parser
128      * and gets propagated to components in this parser configuration.
129      *
130      * @param featureId The feature identifier.
131      * @param state The state of the feature.
132      *
133      * @throws XMLConfigurationException Thrown if there is a configuration
134      * error.
135      */
136     public void setFeature(String JavaDoc featureId, boolean state)
137         throws XMLConfigurationException;
138
139     /**
140      * Returns the state of a feature.
141      *
142      * @param featureId The feature identifier.
143      *
144      * @throws XMLConfigurationException Thrown if there is a configuration
145      * error.
146      */
147     public boolean getFeature(String JavaDoc featureId)
148         throws XMLConfigurationException;
149
150     /**
151      * Allows a parser to add parser specific properties to be recognized
152      * and managed by the parser configuration.
153      *
154      * @param propertyIds An array of the additional property identifiers
155      * to be recognized.
156      */
157     public void addRecognizedProperties(String JavaDoc[] propertyIds);
158
159     /**
160      * Sets the value of a property. This method is called by the parser
161      * and gets propagated to components in this parser configuration.
162      *
163      * @param propertyId The property identifier.
164      * @param value The value of the property.
165      *
166      * @throws XMLConfigurationException Thrown if there is a configuration
167      * error.
168      */
169     public void setProperty(String JavaDoc propertyId, Object JavaDoc value)
170         throws XMLConfigurationException;
171
172     /**
173      * Returns the value of a property.
174      *
175      * @param propertyId The property identifier.
176      *
177      * @throws XMLConfigurationException Thrown if there is a configuration
178      * error.
179      */
180     public Object JavaDoc getProperty(String JavaDoc propertyId)
181         throws XMLConfigurationException;
182
183     // handlers
184
185     /**
186      * Sets the error handler.
187      *
188      * @param errorHandler The error resolver.
189      */
190     public void setErrorHandler(XMLErrorHandler errorHandler);
191
192     /** Returns the registered error handler. */
193     public XMLErrorHandler getErrorHandler();
194
195     /**
196      * Sets the document handler to receive information about the document.
197      *
198      * @param documentHandler The document handler.
199      */
200     public void setDocumentHandler(XMLDocumentHandler documentHandler);
201
202     /** Returns the registered document handler. */
203     public XMLDocumentHandler getDocumentHandler();
204
205     /**
206      * Sets the DTD handler.
207      *
208      * @param dtdHandler The DTD handler.
209      */
210     public void setDTDHandler(XMLDTDHandler dtdHandler);
211
212     /** Returns the registered DTD handler. */
213     public XMLDTDHandler getDTDHandler();
214
215     /**
216      * Sets the DTD content model handler.
217      *
218      * @param dtdContentModelHandler The DTD content model handler.
219      */
220     public void setDTDContentModelHandler(XMLDTDContentModelHandler dtdContentModelHandler);
221
222     /** Returns the registered DTD content model handler. */
223     public XMLDTDContentModelHandler getDTDContentModelHandler();
224
225     // other settings
226
227     /**
228      * Sets the entity resolver.
229      *
230      * @param entityResolver The new entity resolver.
231      */
232     public void setEntityResolver(XMLEntityResolver entityResolver);
233
234     /** Returns the registered entity resolver. */
235     public XMLEntityResolver getEntityResolver();
236
237     /**
238      * Set the locale to use for messages.
239      *
240      * @param locale The locale object to use for localization of messages.
241      *
242      * @exception XNIException Thrown if the parser does not support the
243      * specified locale.
244      */
245     public void setLocale(Locale JavaDoc locale) throws XNIException;
246
247     /** Returns the locale. */
248     public Locale JavaDoc getLocale();
249
250 } // interface XMLParserConfiguration
251
Popular Tags