XMLParserConfiguration


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