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