001: /*
002: * (C) Copyright 2002-2003, Andy Clark. All rights reserved.
003: *
004: * This file is distributed under an Apache style license. Please
005: * refer to the LICENSE file for specific details.
006: */
007:
008: package org.cyberneko.pull;
009:
010: import java.io.IOException;
011: import java.util.Locale;
012:
013: import org.apache.xerces.xni.Augmentations;
014: import org.apache.xerces.xni.XNIException;
015: import org.apache.xerces.xni.parser.XMLComponentManager;
016: import org.apache.xerces.xni.parser.XMLConfigurationException;
017: import org.apache.xerces.xni.parser.XMLEntityResolver;
018: import org.apache.xerces.xni.parser.XMLErrorHandler;
019: import org.apache.xerces.xni.parser.XMLInputSource;
020:
021: /**
022: * This interface defines an XML pull parser built on top of the Xerces
023: * Native Interface (XNI). Using a pull parser, an application controls
024: * the parsing of an XML stream by requesting event objects returned by
025: * the <code>nextEvent</code> method of the <code>XMLEventIterator</code>
026: * interface. This is different than the traditional SAX paradigm in
027: * which the application registers handlers and document information is
028: * <em>pushed</em> by the parser to the handlers. For specific details,
029: * refer to the documentation.
030: *
031: * @author Andy Clark
032: *
033: * @version $Id$
034: */
035: public interface XMLPullParser extends XMLEventIterator,
036: XMLComponentManager {
037:
038: //
039: // XMLPullParser methods
040: //
041:
042: // parsing
043:
044: /**
045: * Sets the input source for the document to parse.
046: *
047: * @param inputSource The document's input source.
048: *
049: * @exception XMLConfigurationException Thrown if there is a
050: * configuration error when initializing the
051: * parser.
052: * @exception IOException Thrown on I/O error.
053: *
054: * @see #nextEvent
055: * @see #cleanup
056: */
057: public void setInputSource(XMLInputSource inputSource)
058: throws XMLConfigurationException, IOException;
059:
060: /**
061: * If the application decides to terminate parsing before the xml document
062: * is fully parsed, the application should call this method to free any
063: * resources allocated during parsing. For example, close all opened streams.
064: */
065: public void cleanup();
066:
067: // handlers
068:
069: /**
070: * Sets the error handler.
071: *
072: * @param errorHandler The error resolver.
073: */
074: public void setErrorHandler(XMLErrorHandler errorHandler);
075:
076: /** Returns the registered error handler. */
077: public XMLErrorHandler getErrorHandler();
078:
079: // other settings
080:
081: /**
082: * Sets the entity resolver.
083: *
084: * @param entityResolver The new entity resolver.
085: */
086: public void setEntityResolver(XMLEntityResolver entityResolver);
087:
088: /** Returns the registered entity resolver. */
089: public XMLEntityResolver getEntityResolver();
090:
091: /**
092: * Set the locale to use for messages.
093: *
094: * @param locale The locale object to use for localization of messages.
095: *
096: * @exception XNIException Thrown if the parser does not support the
097: * specified locale.
098: */
099: public void setLocale(Locale locale) throws XNIException;
100:
101: /** Returns the locale. */
102: public Locale getLocale();
103:
104: // generic configuration
105:
106: /**
107: * Sets the state of a feature. This method is called by the parser
108: * and gets propagated to components in this parser configuration.
109: *
110: * @param featureId The feature identifier.
111: * @param state The state of the feature.
112: *
113: * @throws XMLConfigurationException Thrown if there is a configuration
114: * error.
115: */
116: public void setFeature(String featureId, boolean state)
117: throws XMLConfigurationException;
118:
119: /**
120: * Sets the value of a property. This method is called by the parser
121: * and gets propagated to components in this parser configuration.
122: *
123: * @param propertyId The property identifier.
124: * @param value The value of the property.
125: *
126: * @throws XMLConfigurationException Thrown if there is a configuration
127: * error.
128: */
129: public void setProperty(String propertyId, Object value)
130: throws XMLConfigurationException;
131:
132: //
133: // XMLEventIterator methods
134: //
135:
136: /**
137: * Returns the next event in the document or null if there are
138: * no more events.
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: * @see #setInputSource
147: */
148: public XMLEvent nextEvent() throws XNIException, IOException;
149:
150: //
151: // XMLComponentManager methods
152: //
153:
154: /**
155: * Returns the state of a feature.
156: *
157: * @param featureId The feature identifier.
158: *
159: * @throws XMLConfigurationException Thrown if there is a configuration
160: * error.
161: */
162: public boolean getFeature(String featureId)
163: throws XMLConfigurationException;
164:
165: /**
166: * Returns the value of a property.
167: *
168: * @param propertyId The property identifier.
169: *
170: * @throws XMLConfigurationException Thrown if there is a configuration
171: * error.
172: */
173: public Object getProperty(String propertyId)
174: throws XMLConfigurationException;
175:
176: } // interface XMLPullParser
|