/gcc-3.2.3-20040701/libjava/org/xml/sax/InputSource.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