001: /*
002: * The Apache Software License, Version 1.1
003: *
004: *
005: * Copyright (c) 2001, 2002 The Apache Software Foundation. All rights
006: * reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Apache Software Foundation (http://www.apache.org/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Xerces" and "Apache Software Foundation" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact apache@apache.org.
031: *
032: * 5. Products derived from this software may not be called "Apache",
033: * nor may "Apache" appear in their name, without prior written
034: * permission of the Apache Software Foundation.
035: *
036: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
040: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: * SUCH DAMAGE.
048: * ====================================================================
049: *
050: * This software consists of voluntary contributions made by many
051: * individuals on behalf of the Apache Software Foundation and was
052: * originally based on software copyright (c) 1999, International
053: * Business Machines, Inc., http://www.apache.org. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package com.sun.xml.stream.xerces.xni.parser;
059:
060: import java.io.IOException;
061: import java.util.Locale;
062:
063: import com.sun.xml.stream.xerces.xni.*;
064:
065: /**
066: * Represents a parser configuration. The parser configuration maintains
067: * a table of recognized features and properties, assembles components
068: * for the parsing pipeline, and is responsible for initiating parsing
069: * of an XML document.
070: * <p>
071: * By separating the configuration of a parser from the specific parser
072: * instance, applications can create new configurations and re-use the
073: * existing parser components and external API generators (e.g. the
074: * DOMParser and SAXParser).
075: * <p>
076: * The internals of any specific parser configuration instance are hidden.
077: * Therefore, each configuration may implement the parsing mechanism any
078: * way necessary. However, the parser configuration should follow these
079: * guidelines:
080: * <ul>
081: * <li>
082: * Call the <code>reset</code> method on each component before parsing.
083: * This is only required if the configuration is re-using existing
084: * components that conform to the <code>XMLComponent</code> interface.
085: * If the configuration uses all custom parts, then it is free to
086: * implement everything as it sees fit as long as it follows the
087: * other guidelines.
088: * </li>
089: * <li>
090: * Call the <code>setFeature</code> and <code>setProperty</code> method
091: * on each component during parsing to propagate features and properties
092: * that have changed. This is only required if the configuration is
093: * re-using existing components that conform to the <code>XMLComponent</code>
094: * interface. If the configuration uses all custom parts, then it is free
095: * to implement everything as it sees fit as long as it follows the other
096: * guidelines.
097: * </li>
098: * <li>
099: * Pass the same unique String references for all symbols that are
100: * propagated to the registered handlers. Symbols include, but may not
101: * be limited to, the names of elements and attributes (including their
102: * uri, prefix, and localpart). This is suggested but not an absolute
103: * must. However, the standard parser components may require access to
104: * the same symbol table for creation of unique symbol references to be
105: * propagated in the XNI pipeline.
106: * </li>
107: * </ul>
108: *
109: * @author Arnaud Le Hors, IBM
110: * @author Andy Clark, IBM
111: *
112: * @version $Id: XMLParserConfiguration.java,v 1.2 2006/04/01 06:01:44 jeffsuttor Exp $
113: */
114: public interface XMLParserConfiguration extends XMLComponentManager {
115:
116: //
117: // XMLParserConfiguration methods
118: //
119:
120: // parsing
121:
122: /**
123: * Parse an XML document.
124: * <p>
125: * The parser can use this method to instruct this configuration
126: * to begin parsing an XML document from any valid input source
127: * (a character stream, a byte stream, or a URI).
128: * <p>
129: * Parsers may not invoke this method while a parse is in progress.
130: * Once a parse is complete, the parser may then parse another XML
131: * document.
132: * <p>
133: * This method is synchronous: it will not return until parsing
134: * has ended. If a client application wants to terminate
135: * parsing early, it should throw an exception.
136: * <p>
137: * When this method returns, all characters streams and byte streams
138: * opened by the parser are closed.
139: *
140: * @param source The input source for the top-level of the
141: * XML document.
142: *
143: * @exception XNIException Any XNI exception, possibly wrapping
144: * another exception.
145: * @exception IOException An IO exception from the parser, possibly
146: * from a byte stream or character stream
147: * supplied by the parser.
148: */
149: public void parse(XMLInputSource inputSource) throws XNIException,
150: IOException;
151:
152: // generic configuration
153:
154: /**
155: * Allows a parser to add parser specific features to be recognized
156: * and managed by the parser configuration.
157: *
158: * @param featureIds An array of the additional feature identifiers
159: * to be recognized.
160: */
161: public void addRecognizedFeatures(String[] featureIds);
162:
163: /**
164: * Sets the state of a feature. This method is called by the parser
165: * and gets propagated to components in this parser configuration.
166: *
167: * @param featureId The feature identifier.
168: * @param state The state of the feature.
169: *
170: * @throws XMLConfigurationException Thrown if there is a configuration
171: * error.
172: */
173: public void setFeature(String featureId, boolean state)
174: throws XMLConfigurationException;
175:
176: /**
177: * Returns the state of a feature.
178: *
179: * @param featureId The feature identifier.
180: *
181: * @throws XMLConfigurationException Thrown if there is a configuration
182: * error.
183: */
184: public boolean getFeature(String featureId)
185: throws XMLConfigurationException;
186:
187: /**
188: * Allows a parser to add parser specific properties to be recognized
189: * and managed by the parser configuration.
190: *
191: * @param propertyIds An array of the additional property identifiers
192: * to be recognized.
193: */
194: public void addRecognizedProperties(String[] propertyIds);
195:
196: /**
197: * Sets the value of a property. This method is called by the parser
198: * and gets propagated to components in this parser configuration.
199: *
200: * @param propertyId The property identifier.
201: * @param value The value of the property.
202: *
203: * @throws XMLConfigurationException Thrown if there is a configuration
204: * error.
205: */
206: public void setProperty(String propertyId, Object value)
207: throws XMLConfigurationException;
208:
209: /**
210: * Returns the value of a property.
211: *
212: * @param propertyId The property identifier.
213: *
214: * @throws XMLConfigurationException Thrown if there is a configuration
215: * error.
216: */
217: public Object getProperty(String propertyId)
218: throws XMLConfigurationException;
219:
220: // handlers
221:
222: /**
223: * Sets the error handler.
224: *
225: * @param errorHandler The error resolver.
226: */
227: public void setErrorHandler(XMLErrorHandler errorHandler);
228:
229: /** Returns the registered error handler. */
230: public XMLErrorHandler getErrorHandler();
231:
232: /**
233: * Sets the document handler to receive information about the document.
234: *
235: * @param documentHandler The document handler.
236: */
237: public void setDocumentHandler(XMLDocumentHandler documentHandler);
238:
239: /** Returns the registered document handler. */
240: public XMLDocumentHandler getDocumentHandler();
241:
242: /**
243: * Sets the DTD handler.
244: *
245: * @param dtdHandler The DTD handler.
246: */
247: public void setDTDHandler(XMLDTDHandler dtdHandler);
248:
249: /** Returns the registered DTD handler. */
250: public XMLDTDHandler getDTDHandler();
251:
252: /**
253: * Sets the DTD content model handler.
254: *
255: * @param dtdContentModelHandler The DTD content model handler.
256: */
257: public void setDTDContentModelHandler(
258: XMLDTDContentModelHandler dtdContentModelHandler);
259:
260: /** Returns the registered DTD content model handler. */
261: public XMLDTDContentModelHandler getDTDContentModelHandler();
262:
263: // other settings
264:
265: /**
266: * Sets the entity resolver.
267: *
268: * @param entityResolver The new entity resolver.
269: */
270: public void setEntityResolver(XMLEntityResolver entityResolver);
271:
272: /** Returns the registered entity resolver. */
273: public XMLEntityResolver getEntityResolver();
274:
275: /**
276: * Set the locale to use for messages.
277: *
278: * @param locale The locale object to use for localization of messages.
279: *
280: * @exception XNIException Thrown if the parser does not support the
281: * specified locale.
282: */
283: public void setLocale(Locale locale) throws XNIException;
284:
285: /** Returns the locale. */
286: public Locale getLocale();
287:
288: } // interface XMLParserConfiguration
|