content: /*
   *  This file is part of AndroidIDE.
   *
   *  AndroidIDE is free software: you can redistribute it and/or modify
   *  it under the terms of the GNU General Public License as published by
   *  the Free Software Foundation, either version 3 of the License, or
   *  (at your option) any later version.
   *
   *  AndroidIDE is distributed in the hope that it will be useful,
   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   *  GNU General Public License for more details.
   *
   *  You should have received a copy of the GNU General Public License
   *   along with AndroidIDE.  If not, see <https://www.gnu.org/licenses/>.
   */
  
  /*
   * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
   */
  
  /*
   * Copyright 2005 The Apache Software Foundation.
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package jaxp.sun.xml.internal.stream;
  
  import java.io.IOException;
  
  import jaxp.sun.org.apache.xerces.internal.util.EncodingMap;
  import jaxp.sun.org.apache.xerces.internal.util.XMLChar;
  import jaxp.sun.org.apache.xerces.internal.util.XMLStringBuffer;
  import jaxp.sun.org.apache.xerces.internal.xni.*;
  
  import jaxp.sun.org.apache.xerces.internal.util.SymbolTable;
  import jaxp.sun.org.apache.xerces.internal.xni.QName;
  import jaxp.sun.org.apache.xerces.internal.xni.XMLLocator;
  import jaxp.sun.org.apache.xerces.internal.xni.XMLString;
  
  /**
   * This class allows various parser scanners to scan basic XML constructs
   * from entities. This class works directly with the entity manager to
   * provide this functionality.
   * <p>
   * There is only one entity scanner and entity manager per parser. The
   * entity manager <em>could</em> implement the methods to perform entity
   * scanning, but the entity scanner class allows a cleaner separation
   * between entity management API and entity scanning.
   *
   * @author Andy Clark, IBM
   * @author Neeraj Bajaj Sun Microsystems
   * @author K.Venugopal Sun Microsystems
   *
   * @see XMLEntityHandler
   * @see XMLEntityManager
   */
  public abstract class XMLEntityReader implements XMLLocator {
  
      //
      // Public methods
      //
  
  
      /**
       * Sets the encoding of the scanner. This method is used by the
       * scanners if the XMLDecl or TextDecl line contains an encoding
       * pseudo-attribute.
       * <p>
       * <strong>Note:</strong> The underlying character reader on the
       * current entity will be changed to accomodate the new encoding.
       * However, the new encoding is ignored if the current reader was
       * not constructed from an input stream (e.g. an external entity
       * that is resolved directly to the appropriate java.io.Reader
       * object).
       *
       * @param encoding The IANA encoding name of the new encoding.
       *
       * @throws IOException  Thrown if the new encoding is not supported.
       *
       * @see EncodingMap
       * @see XMLChar#isValidIANAEncoding
       * @see XMLChar#isValidJavaEncoding
       */
      public abstract void setEncoding(String encoding)
      throws IOException;
  
      public abstract String getEncoding() ;
  
      public abstract int getCharacterOffset() ;
  
      /** the version of the current entity being scanned or the version of the entity on which reader is operating */
      public abstract void setVersion(String version) ;
  
      /** get the version of the entity on which reader is operating */
      public abstract String getVersion() ;
  
      /** Returns true if the current entity being scanned is external. */
      public abstract boolean isExternal();
  
      /**
       * Returns the next character on the input.
       * <p>
       * <strong>Note:</strong> The character is <em>not</em> consumed.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract int peekChar() throws IOException;
  
      /**
       * Returns the next character on the input.
       * <p>
       * <strong>Note:</strong> The character is consumed.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract int scanChar() throws IOException;
  
      /**
       * Returns a string matching the NMTOKEN production appearing immediately
       * on the input as a symbol, or null if NMTOKEN Name string is present.
       * <p>
       * <strong>Note:</strong> The NMTOKEN characters are consumed.
       * <p>
       * <strong>Note:</strong> The string returned must be a symbol. The
       * SymbolTable can be used for this purpose.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       *
       * @see SymbolTable
       * @see XMLChar#isName
       */
      public abstract String scanNmtoken() throws IOException;
  
      /**
       * Returns a string matching the Name production appearing immediately
       * on the input as a symbol, or null if no Name string is present.
       * <p>
       * <strong>Note:</strong> The Name characters are consumed.
       * <p>
       * <strong>Note:</strong> The string returned must be a symbol. The
       * SymbolTable can be used for this purpose.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       *
       * @see SymbolTable
       * @see XMLChar#isName
       * @see XMLChar#isNameStart
       */
      public abstract String scanName() throws IOException;
  
      /**
       * Scans a qualified name from the input, setting the fields of the
       * QName structure appropriately.
       * <p>
       * <strong>Note:</strong> The qualified name characters are consumed.
       * <p>
       * <strong>Note:</strong> The strings used to set the values of the
       * QName structure must be symbols. The SymbolTable can be used for
       * this purpose.
       *
       * @param qname The qualified name structure to fill.
       *
       * @return Returns true if a qualified name appeared immediately on
       *         the input and was scanned, false otherwise.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       *
       * @see SymbolTable
       * @see XMLChar#isName
       * @see XMLChar#isNameStart
       */
      public abstract boolean scanQName(QName qname) throws IOException;
  
      /**
       * CHANGED:
       * Scans a range of parsed character data, This function appends the character data to
       * the supplied buffer.
       * <p>
       * <strong>Note:</strong> The characters are consumed.
       * <p>
       * <strong>Note:</strong> This method does not guarantee to return
       * the longest run of parsed character data. This method may return
       * before markup due to reaching the end of the input buffer or any
       * other reason.
       * <p>
       *
       * @param content The content structure to fill.
       *
       * @return Returns the next character on the input, if known. This
       *         value may be -1 but this does <em>note</em> designate
       *         end of file.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract int scanContent(XMLString content) throws IOException;
  
      /**
       * Scans a range of attribute value data, setting the fields of the
       * XMLString structure, appropriately.
       * <p>
       * <strong>Note:</strong> The characters are consumed.
       * <p>
       * <strong>Note:</strong> This method does not guarantee to return
       * the longest run of attribute value data. This method may return
       * before the quote character due to reaching the end of the input
       * buffer or any other reason.
       * <p>
       * <strong>Note:</strong> The fields contained in the XMLString
       * structure are not guaranteed to remain valid upon subsequent calls
       * to the entity scanner. Therefore, the caller is responsible for
       * immediately using the returned character data or making a copy of
       * the character data.
       *
       * @param quote   The quote character that signifies the end of the
       *                attribute value data.
       * @param content The content structure to fill.
       *
       * @return Returns the next character on the input, if known. This
       *         value may be -1 but this does <em>note</em> designate
       *         end of file.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract int scanLiteral(int quote, XMLString content)
      throws IOException;
  
      /**
       * Scans a range of character data up to the specicied delimiter,
       * setting the fields of the XMLString structure, appropriately.
       * <p>
       * <strong>Note:</strong> The characters are consumed.
       * <p>
       * <strong>Note:</strong> This assumes that the internal buffer is
       * at least the same size, or bigger, than the length of the delimiter
       * and that the delimiter contains at least one character.
       * <p>
       * <strong>Note:</strong> This method does not guarantee to return
       * the longest run of character data. This method may return before
       * the delimiter due to reaching the end of the input buffer or any
       * other reason.
       * <p>
       * <strong>Note:</strong> The fields contained in the XMLString
       * structure are not guaranteed to remain valid upon subsequent calls
       * to the entity scanner. Therefore, the caller is responsible for
       * immediately using the returned character data or making a copy of
       * the character data.
       *
       * @param delimiter The string that signifies the end of the character
       *                  data to be scanned.
       * @param data      The data structure to fill.
       *
       * @return Returns true if there is more data to scan, false otherwise.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract boolean scanData(String delimiter, XMLStringBuffer data)
      throws IOException;
  
      /**
       * Skips a character appearing immediately on the input.
       * <p>
       * <strong>Note:</strong> The character is consumed only if it matches
       * the specified character.
       *
       * @param c The character to skip.
       *
       * @return Returns true if the character was skipped.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract boolean skipChar(int c) throws IOException;
  
      /**
       * Skips space characters appearing immediately on the input.
       * <p>
       * <strong>Note:</strong> The characters are consumed only if they are
       * space characters.
       *
       * @return Returns true if at least one space character was skipped.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       *
       * @see XMLChar#isSpace
       */
      public abstract boolean skipSpaces() throws IOException;
  
      /**
       * Skips the specified string appearing immediately on the input.
       * <p>
       * <strong>Note:</strong> The characters are consumed only if they are
       * space characters.
       *
       * @param s The string to skip.
       *
       * @return Returns true if the string was skipped.
       *
       * @throws IOException  Thrown if i/o error occurs.
       * @throws EOFException Thrown on end of file.
       */
      public abstract boolean skipString(String s) throws IOException;
  
      public abstract void registerListener(XMLBufferListener listener);
  
  } // class XMLEntityScanner
  