Java tutorial
/* * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code 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 * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ // SAX input source. // http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id: InputSource.java,v 1.2 2004/11/03 22:55:32 jsuttor Exp $ package org.xml.sax; import java.io.IOException; import java.io.Reader; import java.io.InputStream; /** * A single input source for an XML entity. * * <blockquote> * <em>This module, both source code and documentation, is in the * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> * for further information. * </blockquote> * * <p>This class allows a SAX application to encapsulate information * about an input source in a single object, which may include * a public identifier, a system identifier, a byte stream (possibly * with a specified encoding), and/or a character stream.</p> * * <p>There are two places that the application can deliver an * input source to the parser: as the argument to the Parser.parse * method, or as the return value of the EntityResolver.resolveEntity * method.</p> * * <p>The SAX parser will use the InputSource object to determine how * to read XML input. If there is a character stream available, the * parser will read that stream directly, disregarding any text * encoding declaration found in that stream. * If there is no character stream, but there is * a byte stream, the parser will use that byte stream, using the * encoding specified in the InputSource or else (if no encoding is * specified) autodetecting the character encoding using an algorithm * such as the one in the XML specification. If neither a character * stream nor a * byte stream is available, the parser will attempt to open a URI * connection to the resource identified by the system * identifier.</p> * * <p>An InputSource object belongs to the application: the SAX parser * shall never modify it in any way (it may modify a copy if * necessary). However, standard processing of both byte and * character streams is to close them on as part of end-of-parse cleanup, * so applications should not attempt to re-use such streams after they * have been handed to a parser. </p> * * @since 1.4, SAX 1.0 * @author David Megginson * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource) * @see org.xml.sax.EntityResolver#resolveEntity * @see java.io.InputStream * @see java.io.Reader */ public class InputSource { /** * Zero-argument default constructor. * * @see #setPublicId * @see #setSystemId * @see #setByteStream * @see #setCharacterStream * @see #setEncoding */ public InputSource() { } /** * Create a new input source with a system identifier. * * <p>Applications may use setPublicId to include a * public identifier as well, or setEncoding to specify * the character encoding, if known.</p> * * <p>If the system identifier is a URL, it must be fully * resolved (it may not be a relative URL).</p> * * @param systemId The system identifier (URI). * @see #setPublicId * @see #setSystemId * @see #setByteStream * @see #setEncoding * @see #setCharacterStream */ public InputSource(String systemId) { setSystemId(systemId); } /** * Create a new input source with a byte stream. * * <p>Application writers should use setSystemId() to provide a base * for resolving relative URIs, may use setPublicId to include a * public identifier, and may use setEncoding to specify the object's * character encoding.</p> * * @param byteStream The raw byte stream containing the document. * @see #setPublicId * @see #setSystemId * @see #setEncoding * @see #setByteStream * @see #setCharacterStream */ public InputSource(InputStream byteStream) { setByteStream(byteStream); } /** * Create a new input source with a character stream. * * <p>Application writers should use setSystemId() to provide a base * for resolving relative URIs, and may use setPublicId to include a * public identifier.</p> * * <p>The character stream shall not include a byte order mark.</p> * * @see #setPublicId * @see #setSystemId * @see #setByteStream * @see #setCharacterStream */ public InputSource(Reader characterStream) { setCharacterStream(characterStream); } /** * Set the public identifier for this input source. * * <p>The public identifier is always optional: if the application * writer includes one, it will be provided as part of the * location information.</p> * * @param publicId The public identifier as a string. * @see #getPublicId * @see org.xml.sax.Locator#getPublicId * @see org.xml.sax.SAXParseException#getPublicId */ public void setPublicId(String publicId) { this.publicId = publicId; } /** * Get the public identifier for this input source. * * @return The public identifier, or null if none was supplied. * @see #setPublicId */ public String getPublicId() { return publicId; } /** * Set the system identifier for this input source. * * <p>The system identifier is optional if there is a byte stream * or a character stream, but it is still useful to provide one, * since the application can use it to resolve relative URIs * and can include it in error messages and warnings (the parser * will attempt to open a connection to the URI only if * there is no byte stream or character stream specified).</p> * * <p>If the application knows the character encoding of the * object pointed to by the system identifier, it can register * the encoding using the setEncoding method.</p> * * <p>If the system identifier is a URL, it must be fully * resolved (it may not be a relative URL).</p> * * @param systemId The system identifier as a string. * @see #setEncoding * @see #getSystemId * @see org.xml.sax.Locator#getSystemId * @see org.xml.sax.SAXParseException#getSystemId */ public void setSystemId(String systemId) { this.systemId = systemId; } /** * Get the system identifier for this input source. * * <p>The getEncoding method will return the character encoding * of the object pointed to, or null if unknown.</p> * * <p>If the system ID is a URL, it will be fully resolved.</p> * * @return The system identifier, or null if none was supplied. * @see #setSystemId * @see #getEncoding */ public String getSystemId() { return systemId; } /** * Set the byte stream for this input source. * * <p>The SAX parser will ignore this if there is also a character * stream specified, but it will use a byte stream in preference * to opening a URI connection itself.</p> * * <p>If the application knows the character encoding of the * byte stream, it should set it with the setEncoding method.</p> * * @param byteStream A byte stream containing an XML document or * other entity. * @see #setEncoding * @see #getByteStream * @see #getEncoding * @see java.io.InputStream */ public void setByteStream(InputStream byteStream) { this.byteStream = byteStream; } /** * Get the byte stream for this input source. * * <p>The getEncoding method will return the character * encoding for this byte stream, or null if unknown.</p> * * @return The byte stream, or null if none was supplied. * @see #getEncoding * @see #setByteStream */ public InputStream getByteStream() { return byteStream; } /** * Set the character encoding, if known. * * <p>The encoding must be a string acceptable for an * XML encoding declaration (see section 4.3.3 of the XML 1.0 * recommendation).</p> * * <p>This method has no effect when the application provides a * character stream.</p> * * @param encoding A string describing the character encoding. * @see #setSystemId * @see #setByteStream * @see #getEncoding */ public void setEncoding(String encoding) { this.encoding = encoding; } /** * Get the character encoding for a byte stream or URI. * This value will be ignored when the application provides a * character stream. * * @return The encoding, or null if none was supplied. * @see #setByteStream * @see #getSystemId * @see #getByteStream */ public String getEncoding() { return encoding; } /** * Set the character stream for this input source. * * <p>If there is a character stream specified, the SAX parser * will ignore any byte stream and will not attempt to open * a URI connection to the system identifier.</p> * * @param characterStream The character stream containing the * XML document or other entity. * @see #getCharacterStream * @see java.io.Reader */ public void setCharacterStream(Reader characterStream) { this.characterStream = characterStream; } /** * Get the character stream for this input source. * * @return The character stream, or null if none was supplied. * @see #setCharacterStream */ public Reader getCharacterStream() { return characterStream; } /** * Indicates whether the {@code InputSource} object is empty. Empty is * defined as follows: * <ul> * <li>All of the input sources, including the public identifier, system * identifier, byte stream, and character stream, are {@code null}. * </li> * <li>The public identifier and system identifier are {@code null}, and * byte and character stream are either {@code null} or contain no byte * or character. * <p> * Note that this method will reset the byte stream if it is provided, or * the character stream if the byte stream is not provided. * </li> * </ul> * <p> * In case of error while checking the byte or character stream, the method * will return false to allow the XML processor to handle the error. * * @return true if the {@code InputSource} object is empty, false otherwise */ public boolean isEmpty() { return (publicId == null && systemId == null && isStreamEmpty()); } private boolean isStreamEmpty() { boolean empty = true; try { if (byteStream != null) { byteStream.reset(); int bytesRead = byteStream.available(); if (bytesRead > 0) { return false; } } if (characterStream != null) { characterStream.reset(); int c = characterStream.read(); characterStream.reset(); if (c != -1) { return false; } } } catch (IOException ex) { //in case of error, return false return false; } return empty; } //////////////////////////////////////////////////////////////////// // Internal state. //////////////////////////////////////////////////////////////////// private String publicId; private String systemId; private InputStream byteStream; private String encoding; private Reader characterStream; } // end of InputSource.java