1 /*

     2  * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.

     3  */

     4 

     5 /*

     6  * Copyright 2005 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.xml.internal.stream;

    22 

    23 import java.io.IOException;

    24 

    25 import com.sun.org.apache.xerces.internal.util.XMLStringBuffer;

    26 import com.sun.org.apache.xerces.internal.xni.*;

    27 

    28 /**

    29  * This class allows various parser scanners to scan basic XML constructs

    30  * from entities. This class works directly with the entity manager to

    31  * provide this functionality.

    32  * <p>

    33  * There is only one entity scanner and entity manager per parser. The

    34  * entity manager <em>could</em> implement the methods to perform entity

    35  * scanning, but the entity scanner class allows a cleaner separation

    36  * between entity management API and entity scanning.

    37  *

    38  * @author Andy Clark, IBM

    39  * @author Neeraj Bajaj Sun Microsystems

    40  * @author K.Venugopal Sun Microsystems

    41  *

    42  * @see XMLEntityHandler

    43  * @see XMLEntityManager

    44  */

    45 public abstract class XMLEntityReader implements XMLLocator {

    46 

    47     //

    48     // Public methods

    49     //

    50 

    51 

    52     /**

    53      * Sets the encoding of the scanner. This method is used by the

    54      * scanners if the XMLDecl or TextDecl line contains an encoding

    55      * pseudo-attribute.

    56      * <p>

    57      * <strong>Note:</strong> The underlying character reader on the

    58      * current entity will be changed to accomodate the new encoding.

    59      * However, the new encoding is ignored if the current reader was

    60      * not constructed from an input stream (e.g. an external entity

    61      * that is resolved directly to the appropriate java.io.Reader

    62      * object).

    63      *

    64      * @param encoding The IANA encoding name of the new encoding.

    65      *

    66      * @throws IOException  Thrown if the new encoding is not supported.

    67      *

    68      * @see com.sun.org.apache.xerces.internal.util.EncodingMap

    69      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isValidIANAEncoding

    70      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isValidJavaEncoding

    71      */

    72     public abstract void setEncoding(String encoding)

    73     throws IOException;

    74 

    75     public abstract String getEncoding() ;

    76 

    77     public abstract int getCharacterOffset() ;

    78 

    79     /** the version of the current entity being scanned or the version of the entity on which reader is operating */

    80     public abstract void setVersion(String version) ;

    81 

    82     /** get the version of the entity on which reader is operating */

    83     public abstract String getVersion() ;

    84 

    85     /** Returns true if the current entity being scanned is external. */

    86     public abstract boolean isExternal();

    87 

    88     /**

    89      * Returns the next character on the input.

    90      * <p>

    91      * <strong>Note:</strong> The character is <em>not</em> consumed.

    92      *

    93      * @throws IOException  Thrown if i/o error occurs.

    94      * @throws EOFException Thrown on end of file.

    95      */

    96     public abstract int peekChar() throws IOException;

    97 

    98     /**

    99      * Returns the next character on the input.

   100      * <p>

   101      * <strong>Note:</strong> The character is consumed.

   102      *

   103      * @throws IOException  Thrown if i/o error occurs.

   104      * @throws EOFException Thrown on end of file.

   105      */

   106     public abstract int scanChar() throws IOException;

   107 

   108     /**

   109      * Returns a string matching the NMTOKEN production appearing immediately

   110      * on the input as a symbol, or null if NMTOKEN Name string is present.

   111      * <p>

   112      * <strong>Note:</strong> The NMTOKEN characters are consumed.

   113      * <p>

   114      * <strong>Note:</strong> The string returned must be a symbol. The

   115      * SymbolTable can be used for this purpose.

   116      *

   117      * @throws IOException  Thrown if i/o error occurs.

   118      * @throws EOFException Thrown on end of file.

   119      *

   120      * @see com.sun.org.apache.xerces.internal.util.SymbolTable

   121      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isName

   122      */

   123     public abstract String scanNmtoken() throws IOException;

   124 

   125     /**

   126      * Returns a string matching the Name production appearing immediately

   127      * on the input as a symbol, or null if no Name string is present.

   128      * <p>

   129      * <strong>Note:</strong> The Name characters are consumed.

   130      * <p>

   131      * <strong>Note:</strong> The string returned must be a symbol. The

   132      * SymbolTable can be used for this purpose.

   133      *

   134      * @throws IOException  Thrown if i/o error occurs.

   135      * @throws EOFException Thrown on end of file.

   136      *

   137      * @see com.sun.org.apache.xerces.internal.util.SymbolTable

   138      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isName

   139      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isNameStart

   140      */

   141     public abstract String scanName() throws IOException;

   142 

   143     /**

   144      * Scans a qualified name from the input, setting the fields of the

   145      * QName structure appropriately.

   146      * <p>

   147      * <strong>Note:</strong> The qualified name characters are consumed.

   148      * <p>

   149      * <strong>Note:</strong> The strings used to set the values of the

   150      * QName structure must be symbols. The SymbolTable can be used for

   151      * this purpose.

   152      *

   153      * @param qname The qualified name structure to fill.

   154      *

   155      * @return Returns true if a qualified name appeared immediately on

   156      *         the input and was scanned, false otherwise.

   157      *

   158      * @throws IOException  Thrown if i/o error occurs.

   159      * @throws EOFException Thrown on end of file.

   160      *

   161      * @see com.sun.org.apache.xerces.internal.util.SymbolTable

   162      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isName

   163      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isNameStart

   164      */

   165     public abstract boolean scanQName(QName qname) throws IOException;

   166 

   167     /**

   168      * CHANGED:

   169      * Scans a range of parsed character data, This function appends the character data to

   170      * the supplied buffer.

   171      * <p>

   172      * <strong>Note:</strong> The characters are consumed.

   173      * <p>

   174      * <strong>Note:</strong> This method does not guarantee to return

   175      * the longest run of parsed character data. This method may return

   176      * before markup due to reaching the end of the input buffer or any

   177      * other reason.

   178      * <p>

   179      *

   180      * @param content The content structure to fill.

   181      *

   182      * @return Returns the next character on the input, if known. This

   183      *         value may be -1 but this does <em>note</em> designate

   184      *         end of file.

   185      *

   186      * @throws IOException  Thrown if i/o error occurs.

   187      * @throws EOFException Thrown on end of file.

   188      */

   189     public abstract int scanContent(XMLString content) throws IOException;

   190 

   191     /**

   192      * Scans a range of attribute value data, setting the fields of the

   193      * XMLString structure, appropriately.

   194      * <p>

   195      * <strong>Note:</strong> The characters are consumed.

   196      * <p>

   197      * <strong>Note:</strong> This method does not guarantee to return

   198      * the longest run of attribute value data. This method may return

   199      * before the quote character due to reaching the end of the input

   200      * buffer or any other reason.

   201      * <p>

   202      * <strong>Note:</strong> The fields contained in the XMLString

   203      * structure are not guaranteed to remain valid upon subsequent calls

   204      * to the entity scanner. Therefore, the caller is responsible for

   205      * immediately using the returned character data or making a copy of

   206      * the character data.

   207      *

   208      * @param quote   The quote character that signifies the end of the

   209      *                attribute value data.

   210      * @param content The content structure to fill.

   211      *

   212      * @return Returns the next character on the input, if known. This

   213      *         value may be -1 but this does <em>note</em> designate

   214      *         end of file.

   215      *

   216      * @throws IOException  Thrown if i/o error occurs.

   217      * @throws EOFException Thrown on end of file.

   218      */

   219     public abstract int scanLiteral(int quote, XMLString content)

   220     throws IOException;

   221 

   222     /**

   223      * Scans a range of character data up to the specicied delimiter,

   224      * setting the fields of the XMLString structure, appropriately.

   225      * <p>

   226      * <strong>Note:</strong> The characters are consumed.

   227      * <p>

   228      * <strong>Note:</strong> This assumes that the internal buffer is

   229      * at least the same size, or bigger, than the length of the delimiter

   230      * and that the delimiter contains at least one character.

   231      * <p>

   232      * <strong>Note:</strong> This method does not guarantee to return

   233      * the longest run of character data. This method may return before

   234      * the delimiter due to reaching the end of the input buffer or any

   235      * other reason.

   236      * <p>

   237      * <strong>Note:</strong> The fields contained in the XMLString

   238      * structure are not guaranteed to remain valid upon subsequent calls

   239      * to the entity scanner. Therefore, the caller is responsible for

   240      * immediately using the returned character data or making a copy of

   241      * the character data.

   242      *

   243      * @param delimiter The string that signifies the end of the character

   244      *                  data to be scanned.

   245      * @param data      The data structure to fill.

   246      *

   247      * @return Returns true if there is more data to scan, false otherwise.

   248      *

   249      * @throws IOException  Thrown if i/o error occurs.

   250      * @throws EOFException Thrown on end of file.

   251      */

   252     public abstract boolean scanData(String delimiter, XMLStringBuffer data)

   253     throws IOException;

   254 

   255     /**

   256      * Skips a character appearing immediately on the input.

   257      * <p>

   258      * <strong>Note:</strong> The character is consumed only if it matches

   259      * the specified character.

   260      *

   261      * @param c The character to skip.

   262      *

   263      * @return Returns true if the character was skipped.

   264      *

   265      * @throws IOException  Thrown if i/o error occurs.

   266      * @throws EOFException Thrown on end of file.

   267      */

   268     public abstract boolean skipChar(int c) throws IOException;

   269 

   270     /**

   271      * Skips space characters appearing immediately on the input.

   272      * <p>

   273      * <strong>Note:</strong> The characters are consumed only if they are

   274      * space characters.

   275      *

   276      * @return Returns true if at least one space character was skipped.

   277      *

   278      * @throws IOException  Thrown if i/o error occurs.

   279      * @throws EOFException Thrown on end of file.

   280      *

   281      * @see com.sun.org.apache.xerces.internal.util.XMLChar#isSpace

   282      */

   283     public abstract boolean skipSpaces() throws IOException;

   284 

   285     /**

   286      * Skips the specified string appearing immediately on the input.

   287      * <p>

   288      * <strong>Note:</strong> The characters are consumed only if they are

   289      * space characters.

   290      *

   291      * @param s The string to skip.

   292      *

   293      * @return Returns true if the string was skipped.

   294      *

   295      * @throws IOException  Thrown if i/o error occurs.

   296      * @throws EOFException Thrown on end of file.

   297      */

   298     public abstract boolean skipString(String s) throws IOException;

   299 

   300     public abstract void registerListener(XMLBufferListener listener);

   301 

   302 } // class XMLEntityScanner