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