322 lines
9.4 KiB
Java
322 lines
9.4 KiB
Java
// SAX input source.
|
||
// No warranty; no copyright -- use this as you will.
|
||
// $Id: InputSource.java,v 1.1 2000/10/02 02:43:17 sboag Exp $
|
||
|
||
package org.xml.sax;
|
||
|
||
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>
|
||
* </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 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.</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; 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.</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).</p>
|
||
*
|
||
* @since SAX 1.0
|
||
* @author David Megginson,
|
||
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
|
||
* @version 2.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.
|
||
*
|
||
* <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 full resolved.</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 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.</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 may use setSystemId() to provide a base
|
||
* for resolving relative URIs, and 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 ID is a URL, it must be fully resolved.</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.
|
||
* @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.
|
||
*
|
||
* @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;
|
||
}
|
||
|
||
|
||
|
||
////////////////////////////////////////////////////////////////////
|
||
// Internal state.
|
||
////////////////////////////////////////////////////////////////////
|
||
|
||
private String publicId;
|
||
private String systemId;
|
||
private InputStream byteStream;
|
||
private String encoding;
|
||
private Reader characterStream;
|
||
|
||
}
|
||
|
||
// end of InputSource.java
|