Quadcap Embeddable Database

org/xml/sax/InputSource.java

Go to the documentation of this file.

/* Copyright 2000 - 2001 Quadcap Software.  All rights reserved.
 *
 * This software is distributed under the Quadcap Free Software License.
 * This software may be used or modified for any purpose, personal or
 * commercial.  Open Source redistributions are permitted.  Commercial
 * redistribution of larger works derived from, or works which bundle
 * this software requires a "Commercial Redistribution License"; see
 * http://www.quadcap.com/purchase.
 *
 * Redistributions qualify as "Open Source" under  one of the following terms:
 *   
 *    Redistributions are made at no charge beyond the reasonable cost of
 *    materials and delivery.
 *
 *    Redistributions are accompanied by a copy of the Source Code or by an
 *    irrevocable offer to provide a copy of the Source Code for up to three
 *    years at the cost of materials and delivery.  Such redistributions
 *    must allow further use, modification, and redistribution of the Source
 *    Code under substantially the same terms as this license.
 *
 * Redistributions of source code must retain the copyright notices as they
 * appear in each source code file, these license terms, and the
 * disclaimer/limitation of liability set forth as paragraph 6 below.
 *
 * Redistributions in binary form must reproduce this Copyright Notice,
 * these license terms, and the disclaimer/limitation of liability set
 * forth as paragraph 6 below, in the documentation and/or other materials
 * provided with the distribution.
 *
 * The Software is provided on an "AS IS" basis.  No warranty is
 * provided that the Software is free of defects, or fit for a
 * particular purpose.  
 *
 * Limitation of Liability. Quadcap Software shall not be liable
 * for any damages suffered by the Licensee or any third party resulting
 * from use of the Software.
 */

// SAX input source.
// No warranty; no copyright -- use this as you will.
// $Id: InputSource.java,v 1.3 2001/01/06 06:11:02 stan Exp $

package org.xml.sax;

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

/**
  * A single input source for an XML entity.
  *
  * <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>
  *
  * @author David Megginson (ak117@freenet.carleton.ca)
  * @version 1.0
  * @see org.xml.sax.Parser#parse
  * @see org.xml.sax.EntityResolver#resolveEntity
  * @see java.io.InputStream
  * @see java.io.Reader
  */

  /**
    * Zero-argument default constructor.
    *
    * @see #setPublicId
    * @see #setSystemId
    * @see #setByteStream
    * @see #setCharacterStream
    * @see #setEncoding
    */
  {
  }


  /**
    * 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
    */
  {
  }


  /**
    * 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
    */
  {
  }


  /**
    * 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
    */
  {
  }


  /**
    * 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
    */
  {
    this.publicId = publicId;
  }


  /**
    * Get the public identifier for this input source.
    *
    * @return The public identifier, or null if none was supplied.
    * @see #setPublicId
    */
  {
  }


  /**
    * 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
    */
  {
    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
    */
  {
  }


  /**
    * 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
    */
  {
    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
    */
  {
  }


  /** 
    * 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
    */
  {
    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
    */
  {
  }


  /**
    * 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
    */
  {
    this.characterStream = characterStream;
  }


  /**
    * Get the character stream for this input source.
    *
    * @return The character stream, or null if none was supplied.
    * @see #setCharacterStream
    */
  {
  }



  //////////////////////////////////////////////////////////////////////
  // Internal state.
  //////////////////////////////////////////////////////////////////////


}