All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.xml.sax.InputSource Maven / Gradle / Ivy

There is a newer version: 4.2.4
Show newest version
// SAX input source.
// No warranty; no copyright -- use this as you will.
// $Id: InputSource.java 233605 2001-11-06 18:33:40Z hannes $

package org.xml.sax;

import java.io.Reader;
import java.io.InputStream;

/**
  * A single input source for an XML entity.
  *
  * 

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.

* *

There are two places that the application will deliver this * input source to the parser: as the argument to the Parser.parse * method, or as the return value of the EntityResolver.resolveEntity * method.

* *

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; if not, the parser will use * a byte stream, if available; 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.

* *

An InputSource object belongs to the application: the SAX parser * shall never modify it in any way (it may modify a copy if * necessary).

* * @author David Megginson ([email protected]) * @version 1.0 * @see org.xml.sax.Parser#parse * @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. * *

Applications may use setPublicId to include a * public identifier as well, or setEncoding to specify * the character encoding, if known.

* *

If the system identifier is a URL, it must be full resolved.

* * @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. * *

Application writers may use setSystemId to provide a base * for resolving relative URIs, setPublicId to include a * public identifier, and/or setEncoding to specify the object's * character encoding.

* * @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. * *

Application writers may use setSystemId() to provide a base * for resolving relative URIs, and setPublicId to include a * public identifier.

* *

The character stream shall not include a byte order mark.

* * @see #setPublicId * @see #setSystemId * @see #setByteStream * @see #setCharacterStream */ public InputSource (Reader characterStream) { setCharacterStream(characterStream); } /** * Set the public identifier for this input source. * *

The public identifier is always optional: if the application * writer includes one, it will be provided as part of the * location information.

* * @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. * *

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).

* *

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.

* *

If the system ID is a URL, it must be fully resolved.

* * @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. * *

The getEncoding method will return the character encoding * of the object pointed to, or null if unknown.

* *

If the system ID is a URL, it will be fully resolved.

* * @return The system identifier. * @see #setSystemId * @see #getEncoding */ public String getSystemId () { return systemId; } /** * Set the byte stream for this input source. * *

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.

* *

If the application knows the character encoding of the * byte stream, it should set it with the setEncoding method.

* * @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. * *

The getEncoding method will return the character * encoding for this byte stream, or null if unknown.

* * @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. * *

The encoding must be a string acceptable for an * XML encoding declaration (see section 4.3.3 of the XML 1.0 * recommendation).

* *

This method has no effect when the application provides a * character stream.

* * @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. * * @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. * *

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.

* * @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; } ////////////////////////////////////////////////////////////////////// // Internal state. ////////////////////////////////////////////////////////////////////// private String publicId; private String systemId; private InputStream byteStream; private String encoding; private Reader characterStream; }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy