001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.xerces.xni.parser;
019:
020: import java.io.IOException;
021: import java.util.Locale;
022:
023: import org.apache.xerces.xni.XMLDocumentHandler;
024: import org.apache.xerces.xni.XMLDTDHandler;
025: import org.apache.xerces.xni.XMLDTDContentModelHandler;
026: import org.apache.xerces.xni.XNIException;
027:
028: /**
029: * Represents a parser configuration. The parser configuration maintains
030: * a table of recognized features and properties, assembles components
031: * for the parsing pipeline, and is responsible for initiating parsing
032: * of an XML document.
033: * <p>
034: * By separating the configuration of a parser from the specific parser
035: * instance, applications can create new configurations and re-use the
036: * existing parser components and external API generators (e.g. the
037: * DOMParser and SAXParser).
038: * <p>
039: * The internals of any specific parser configuration instance are hidden.
040: * Therefore, each configuration may implement the parsing mechanism any
041: * way necessary. However, the parser configuration should follow these
042: * guidelines:
043: * <ul>
044: * <li>
045: * Call the <code>reset</code> method on each component before parsing.
046: * This is only required if the configuration is re-using existing
047: * components that conform to the <code>XMLComponent</code> interface.
048: * If the configuration uses all custom parts, then it is free to
049: * implement everything as it sees fit as long as it follows the
050: * other guidelines.
051: * </li>
052: * <li>
053: * Call the <code>setFeature</code> and <code>setProperty</code> method
054: * on each component during parsing to propagate features and properties
055: * that have changed. This is only required if the configuration is
056: * re-using existing components that conform to the <code>XMLComponent</code>
057: * interface. If the configuration uses all custom parts, then it is free
058: * to implement everything as it sees fit as long as it follows the other
059: * guidelines.
060: * </li>
061: * <li>
062: * Pass the same unique String references for all symbols that are
063: * propagated to the registered handlers. Symbols include, but may not
064: * be limited to, the names of elements and attributes (including their
065: * uri, prefix, and localpart). This is suggested but not an absolute
066: * must. However, the standard parser components may require access to
067: * the same symbol table for creation of unique symbol references to be
068: * propagated in the XNI pipeline.
069: * </li>
070: * </ul>
071: *
072: * @author Arnaud Le Hors, IBM
073: * @author Andy Clark, IBM
074: *
075: * @version $Id: XMLParserConfiguration.java 447244 2006-09-18 05:20:40Z mrglavas $
076: */
077: public interface XMLParserConfiguration extends XMLComponentManager {
078:
079: //
080: // XMLParserConfiguration methods
081: //
082:
083: // parsing
084:
085: /**
086: * Parse an XML document.
087: * <p>
088: * The parser can use this method to instruct this configuration
089: * to begin parsing an XML document from any valid input source
090: * (a character stream, a byte stream, or a URI).
091: * <p>
092: * Parsers may not invoke this method while a parse is in progress.
093: * Once a parse is complete, the parser may then parse another XML
094: * document.
095: * <p>
096: * This method is synchronous: it will not return until parsing
097: * has ended. If a client application wants to terminate
098: * parsing early, it should throw an exception.
099: * <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) throws XNIException,
113: IOException;
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[] 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 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 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[] 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 propertyId, Object 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 getProperty(String 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(
221: XMLDTDContentModelHandler dtdContentModelHandler);
222:
223: /** Returns the registered DTD content model handler. */
224: public XMLDTDContentModelHandler getDTDContentModelHandler();
225:
226: // other settings
227:
228: /**
229: * Sets the entity resolver.
230: *
231: * @param entityResolver The new entity resolver.
232: */
233: public void setEntityResolver(XMLEntityResolver entityResolver);
234:
235: /** Returns the registered entity resolver. */
236: public XMLEntityResolver getEntityResolver();
237:
238: /**
239: * Set the locale to use for messages.
240: *
241: * @param locale The locale object to use for localization of messages.
242: *
243: * @exception XNIException Thrown if the parser does not support the
244: * specified locale.
245: */
246: public void setLocale(Locale locale) throws XNIException;
247:
248: /** Returns the locale. */
249: public Locale getLocale();
250:
251: } // interface XMLParserConfiguration
|