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  
25  import com.sun.org.apache.xerces.internal.xni.XNIException;
26  
27  /**
28   * Represents a parser configuration that can be used as the
29   * configuration for a "pull" parser. A pull parser allows the
30   * application to drive the parser instead of having document
31   * information events "pushed" to the registered handlers.
32   * <p>
33   * A pull parser using this type of configuration first calls
34   * the <code>setInputSource</code> method. After the input
35   * source is set, the pull parser repeatedly calls the
36   * <code>parse(boolean):boolean</code> method. This method
37   * returns a value of true if there is more to parse in the
38   * document.
39   * <p>
40   * Calling the <code>parse(XMLInputSource)</code> is equivalent
41   * to setting the input source and calling the
42   * <code>parse(boolean):boolean</code> method with a "complete"
43   * value of <code>true</code>.
44   *
45   * @author Andy Clark, IBM
46   *
47   */
48  public interface XMLPullParserConfiguration
49      extends XMLParserConfiguration {
50  
51      //
52      // XMLPullParserConfiguration methods
53      //
54  
55      // parsing
56  
57      /**
58       * Sets the input source for the document to parse.
59       *
60       * @param inputSource The document's input source.
61       *
62       * @exception XMLConfigurationException Thrown if there is a
63       *                        configuration error when initializing the
64       *                        parser.
65       * @exception IOException Thrown on I/O error.
66       *
67       * @see #parse(boolean)
68       */
69      public void setInputSource(XMLInputSource inputSource)
70          throws XMLConfigurationException, IOException;
71  
72      /**
73       * Parses the document in a pull parsing fashion.
74       *
75       * @param complete True if the pull parser should parse the
76       *                 remaining document completely.
77       *
78       * @return True if there is more document to parse.
79       *
80       * @exception XNIException Any XNI exception, possibly wrapping
81       *                         another exception.
82       * @exception IOException  An IO exception from the parser, possibly
83       *                         from a byte stream or character stream
84       *                         supplied by the parser.
85       *
86       * @see #setInputSource
87       */
88      public boolean parse(boolean complete) throws XNIException, IOException;
89  
90      /**
91       * If the application decides to terminate parsing before the xml document
92       * is fully parsed, the application should call this method to free any
93       * resource allocated during parsing. For example, close all opened streams.
94       */
95      public void cleanup();
96  
97  } // interface XMLPullParserConfiguration