com.sun.xml.internal.stream.XMLEntityReader Maven / Gradle / Ivy
Show all versions of jaxp-ri Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*
*
* This file incorporates work covered by the following copyright and
* permission notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.
*/
/*
* $Id: XMLEntityReader.java,v 1.3 2010-11-01 04:40:40 joehw Exp $
* %W% %E%
*/
package com.sun.xml.internal.stream;
import java.io.IOException;
import com.sun.org.apache.xerces.internal.util.XMLStringBuffer;
import com.sun.org.apache.xerces.internal.xni.*;
/**
* 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.
*
* There is only one entity scanner and entity manager per parser. The
* entity manager could 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
* @version $Id: XMLEntityReader.java,v 1.3 2010-11-01 04:40:40 joehw Exp $
*
* @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.
*
* Note: 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 com.sun.org.apache.xerces.internal.util.EncodingMap
* @see com.sun.org.apache.xerces.internal.util.XMLChar#isValidIANAEncoding
* @see com.sun.org.apache.xerces.internal.util.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.
*
* Note: The character is not 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.
*
* Note: 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.
*
* Note: The NMTOKEN characters are consumed.
*
* Note: 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 com.sun.org.apache.xerces.internal.util.SymbolTable
* @see com.sun.org.apache.xerces.internal.util.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.
*
* Note: The Name characters are consumed.
*
* Note: 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 com.sun.org.apache.xerces.internal.util.SymbolTable
* @see com.sun.org.apache.xerces.internal.util.XMLChar#isName
* @see com.sun.org.apache.xerces.internal.util.XMLChar#isNameStart
*/
public abstract String scanName() throws IOException;
/**
* Scans a qualified name from the input, setting the fields of the
* QName structure appropriately.
*
* Note: The qualified name characters are consumed.
*
* Note: 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 com.sun.org.apache.xerces.internal.util.SymbolTable
* @see com.sun.org.apache.xerces.internal.util.XMLChar#isName
* @see com.sun.org.apache.xerces.internal.util.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.
*
* Note: The characters are consumed.
*
* Note: 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.
*
*
* @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 note 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.
*
* Note: The characters are consumed.
*
* Note: 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.
*
* Note: 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 note 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.
*
* Note: The characters are consumed.
*
* Note: 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.
*
* Note: 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.
*
* Note: 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.
*
* Note: 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.
*
* Note: 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 com.sun.org.apache.xerces.internal.util.XMLChar#isSpace
*/
public abstract boolean skipSpaces() throws IOException;
/**
* Skips the specified string appearing immediately on the input.
*
* Note: 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