01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * http://www.apache.org/licenses/LICENSE-2.0
10: *
11: * Unless required by applicable law or agreed to in writing, software
12: * distributed under the License is distributed on an "AS IS" BASIS,
13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14: * See the License for the specific language governing permissions and
15: * limitations under the License.
16: */
17:
18: package org.apache.xerces.xni.parser;
19:
20: import java.io.IOException;
21:
22: import org.apache.xerces.xni.XNIException;
23:
24: /**
25: * Represents a parser configuration that can be used as the
26: * configuration for a "pull" parser. A pull parser allows the
27: * application to drive the parser instead of having document
28: * information events "pushed" to the registered handlers.
29: * <p>
30: * A pull parser using this type of configuration first calls
31: * the <code>setInputSource</code> method. After the input
32: * source is set, the pull parser repeatedly calls the
33: * <code>parse(boolean):boolean</code> method. This method
34: * returns a value of true if there is more to parse in the
35: * document.
36: * <p>
37: * Calling the <code>parse(XMLInputSource)</code> is equivalent
38: * to setting the input source and calling the
39: * <code>parse(boolean):boolean</code> method with a "complete"
40: * value of <code>true</code>.
41: *
42: * @author Andy Clark, IBM
43: *
44: * @version $Id: XMLPullParserConfiguration.java 447244 2006-09-18 05:20:40Z mrglavas $
45: */
46: public interface XMLPullParserConfiguration extends
47: XMLParserConfiguration {
48:
49: //
50: // XMLPullParserConfiguration methods
51: //
52:
53: // parsing
54:
55: /**
56: * Sets the input source for the document to parse.
57: *
58: * @param inputSource The document's input source.
59: *
60: * @exception XMLConfigurationException Thrown if there is a
61: * configuration error when initializing the
62: * parser.
63: * @exception IOException Thrown on I/O error.
64: *
65: * @see #parse(boolean)
66: */
67: public void setInputSource(XMLInputSource inputSource)
68: throws XMLConfigurationException, IOException;
69:
70: /**
71: * Parses the document in a pull parsing fashion.
72: *
73: * @param complete True if the pull parser should parse the
74: * remaining document completely.
75: *
76: * @return True if there is more document to parse.
77: *
78: * @exception XNIException Any XNI exception, possibly wrapping
79: * another exception.
80: * @exception IOException An IO exception from the parser, possibly
81: * from a byte stream or character stream
82: * supplied by the parser.
83: *
84: * @see #setInputSource
85: */
86: public boolean parse(boolean complete) throws XNIException,
87: IOException;
88:
89: /**
90: * If the application decides to terminate parsing before the xml document
91: * is fully parsed, the application should call this method to free any
92: * resource allocated during parsing. For example, close all opened streams.
93: */
94: public void cleanup();
95:
96: } // interface XMLPullParserConfiguration
|