1/*
2 * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
3 */
4/*
5 * Licensed to the Apache Software Foundation (ASF) under one or more
6 * contributor license agreements.  See the NOTICE file distributed with
7 * this work for additional information regarding copyright ownership.
8 * The ASF licenses this file to You under the Apache License, Version 2.0
9 * (the "License"); you may not use this file except in compliance with
10 * the License.  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
22package com.sun.xml.internal.stream;
23
24import java.io.IOException;
25
26import com.sun.org.apache.xerces.internal.util.XMLStringBuffer;
27import com.sun.org.apache.xerces.internal.xni.*;
28
29/**
30 * This class allows various parser scanners to scan basic XML constructs
31 * from entities. This class works directly with the entity manager to
32 * provide this functionality.
33 * <p>
34 * There is only one entity scanner and entity manager per parser. The
35 * entity manager <em>could</em> implement the methods to perform entity
36 * scanning, but the entity scanner class allows a cleaner separation
37 * between entity management API and entity scanning.
38 *
39 * @author Andy Clark, IBM
40 * @author Neeraj Bajaj Sun Microsystems
41 * @author K.Venugopal Sun Microsystems
42 *
43 * @see XMLEntityHandler
44 * @see XMLEntityManager
45 */
46public abstract class XMLEntityReader implements XMLLocator {
47
48    //
49    // Public methods
50    //
51
52
53    /**
54     * Sets the encoding of the scanner. This method is used by the
55     * scanners if the XMLDecl or TextDecl line contains an encoding
56     * pseudo-attribute.
57     * <p>
58     * <strong>Note:</strong> The underlying character reader on the
59     * current entity will be changed to accomodate the new encoding.
60     * However, the new encoding is ignored if the current reader was
61     * not constructed from an input stream (e.g. an external entity
62     * that is resolved directly to the appropriate java.io.Reader
63     * object).
64     *
65     * @param encoding The IANA encoding name of the new encoding.
66     *
67     * @throws IOException  Thrown if the new encoding is not supported.
68     *
69     * @see com.sun.org.apache.xerces.internal.util.EncodingMap
70     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isValidIANAEncoding
71     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isValidJavaEncoding
72     */
73    public abstract void setEncoding(String encoding)
74    throws IOException;
75
76    public abstract String getEncoding() ;
77
78    public abstract int getCharacterOffset() ;
79
80    /** the version of the current entity being scanned or the version of the entity on which reader is operating */
81    public abstract void setVersion(String version) ;
82
83    /** get the version of the entity on which reader is operating */
84    public abstract String getVersion() ;
85
86    /** Returns true if the current entity being scanned is external. */
87    public abstract boolean isExternal();
88
89    /**
90     * Returns the next character on the input.
91     * <p>
92     * <strong>Note:</strong> The character is <em>not</em> consumed.
93     *
94     * @throws IOException  Thrown if i/o error occurs.
95     * @throws EOFException Thrown on end of file.
96     */
97    public abstract int peekChar() throws IOException;
98
99    /**
100     * Returns the next character on the input.
101     * <p>
102     * <strong>Note:</strong> The character is consumed.
103     *
104     * @throws IOException  Thrown if i/o error occurs.
105     * @throws EOFException Thrown on end of file.
106     */
107    public abstract int scanChar() throws IOException;
108
109    /**
110     * Returns a string matching the NMTOKEN production appearing immediately
111     * on the input as a symbol, or null if NMTOKEN Name string is present.
112     * <p>
113     * <strong>Note:</strong> The NMTOKEN characters are consumed.
114     * <p>
115     * <strong>Note:</strong> The string returned must be a symbol. The
116     * SymbolTable can be used for this purpose.
117     *
118     * @throws IOException  Thrown if i/o error occurs.
119     * @throws EOFException Thrown on end of file.
120     *
121     * @see com.sun.org.apache.xerces.internal.util.SymbolTable
122     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isName
123     */
124    public abstract String scanNmtoken() throws IOException;
125
126    /**
127     * Returns a string matching the Name production appearing immediately
128     * on the input as a symbol, or null if no Name string is present.
129     * <p>
130     * <strong>Note:</strong> The Name characters are consumed.
131     * <p>
132     * <strong>Note:</strong> The string returned must be a symbol. The
133     * SymbolTable can be used for this purpose.
134     *
135     * @throws IOException  Thrown if i/o error occurs.
136     * @throws EOFException Thrown on end of file.
137     *
138     * @see com.sun.org.apache.xerces.internal.util.SymbolTable
139     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isName
140     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isNameStart
141     */
142    public abstract String scanName() throws IOException;
143
144    /**
145     * Scans a qualified name from the input, setting the fields of the
146     * QName structure appropriately.
147     * <p>
148     * <strong>Note:</strong> The qualified name characters are consumed.
149     * <p>
150     * <strong>Note:</strong> The strings used to set the values of the
151     * QName structure must be symbols. The SymbolTable can be used for
152     * this purpose.
153     *
154     * @param qname The qualified name structure to fill.
155     *
156     * @return Returns true if a qualified name appeared immediately on
157     *         the input and was scanned, false otherwise.
158     *
159     * @throws IOException  Thrown if i/o error occurs.
160     * @throws EOFException Thrown on end of file.
161     *
162     * @see com.sun.org.apache.xerces.internal.util.SymbolTable
163     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isName
164     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isNameStart
165     */
166    public abstract boolean scanQName(QName qname) throws IOException;
167
168    /**
169     * CHANGED:
170     * Scans a range of parsed character data, This function appends the character data to
171     * the supplied buffer.
172     * <p>
173     * <strong>Note:</strong> The characters are consumed.
174     * <p>
175     * <strong>Note:</strong> This method does not guarantee to return
176     * the longest run of parsed character data. This method may return
177     * before markup due to reaching the end of the input buffer or any
178     * other reason.
179     * <p>
180     *
181     * @param content The content structure to fill.
182     *
183     * @return Returns the next character on the input, if known. This
184     *         value may be -1 but this does <em>note</em> designate
185     *         end of file.
186     *
187     * @throws IOException  Thrown if i/o error occurs.
188     * @throws EOFException Thrown on end of file.
189     */
190    public abstract int scanContent(XMLString content) throws IOException;
191
192    /**
193     * Scans a range of attribute value data, setting the fields of the
194     * XMLString structure, appropriately.
195     * <p>
196     * <strong>Note:</strong> The characters are consumed.
197     * <p>
198     * <strong>Note:</strong> This method does not guarantee to return
199     * the longest run of attribute value data. This method may return
200     * before the quote character due to reaching the end of the input
201     * buffer or any other reason.
202     * <p>
203     * <strong>Note:</strong> The fields contained in the XMLString
204     * structure are not guaranteed to remain valid upon subsequent calls
205     * to the entity scanner. Therefore, the caller is responsible for
206     * immediately using the returned character data or making a copy of
207     * the character data.
208     *
209     * @param quote   The quote character that signifies the end of the
210     *                attribute value data.
211     * @param content The content structure to fill.
212     *
213     * @return Returns the next character on the input, if known. This
214     *         value may be -1 but this does <em>note</em> designate
215     *         end of file.
216     *
217     * @throws IOException  Thrown if i/o error occurs.
218     * @throws EOFException Thrown on end of file.
219     */
220    public abstract int scanLiteral(int quote, XMLString content)
221    throws IOException;
222
223    /**
224     * Scans a range of character data up to the specicied delimiter,
225     * setting the fields of the XMLString structure, appropriately.
226     * <p>
227     * <strong>Note:</strong> The characters are consumed.
228     * <p>
229     * <strong>Note:</strong> This assumes that the internal buffer is
230     * at least the same size, or bigger, than the length of the delimiter
231     * and that the delimiter contains at least one character.
232     * <p>
233     * <strong>Note:</strong> This method does not guarantee to return
234     * the longest run of character data. This method may return before
235     * the delimiter due to reaching the end of the input buffer or any
236     * other reason.
237     * <p>
238     * <strong>Note:</strong> The fields contained in the XMLString
239     * structure are not guaranteed to remain valid upon subsequent calls
240     * to the entity scanner. Therefore, the caller is responsible for
241     * immediately using the returned character data or making a copy of
242     * the character data.
243     *
244     * @param delimiter The string that signifies the end of the character
245     *                  data to be scanned.
246     * @param data      The data structure to fill.
247     *
248     * @return Returns true if there is more data to scan, false otherwise.
249     *
250     * @throws IOException  Thrown if i/o error occurs.
251     * @throws EOFException Thrown on end of file.
252     */
253    public abstract boolean scanData(String delimiter, XMLStringBuffer data)
254    throws IOException;
255
256    /**
257     * Skips a character appearing immediately on the input.
258     * <p>
259     * <strong>Note:</strong> The character is consumed only if it matches
260     * the specified character.
261     *
262     * @param c The character to skip.
263     *
264     * @return Returns true if the character was skipped.
265     *
266     * @throws IOException  Thrown if i/o error occurs.
267     * @throws EOFException Thrown on end of file.
268     */
269    public abstract boolean skipChar(int c) throws IOException;
270
271    /**
272     * Skips space characters appearing immediately on the input.
273     * <p>
274     * <strong>Note:</strong> The characters are consumed only if they are
275     * space characters.
276     *
277     * @return Returns true if at least one space character was skipped.
278     *
279     * @throws IOException  Thrown if i/o error occurs.
280     * @throws EOFException Thrown on end of file.
281     *
282     * @see com.sun.org.apache.xerces.internal.util.XMLChar#isSpace
283     */
284    public abstract boolean skipSpaces() throws IOException;
285
286    /**
287     * Skips the specified string appearing immediately on the input.
288     * <p>
289     * <strong>Note:</strong> The characters are consumed only if they are
290     * space characters.
291     *
292     * @param s The string to skip.
293     *
294     * @return Returns true if the string was skipped.
295     *
296     * @throws IOException  Thrown if i/o error occurs.
297     * @throws EOFException Thrown on end of file.
298     */
299    public abstract boolean skipString(String s) throws IOException;
300
301    public abstract void registerListener(XMLBufferListener listener);
302
303} // class XMLEntityScanner
304