View Javadoc
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