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