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