org.xml.sax.InputSource Maven / Gradle / Ivy
// SAX input source.
// No warranty; no copyright -- use this as you will.
// $Id: InputSource.java,v 1.1 1999/02/26 21:32:44 mode Exp $
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.
*
* InputSource objects delivered to the Parser.parse method should
* have a System ID in order that the SAX parser may resolve any relative
* URIs in the document. If this is not done, parsing errors will be
* reported when entities specified by relative URIs need to be parsed.
* This is because they can't be fully resolved before being passed to
* the EntityResolver.
*
* 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;
}