001: /* Copyright 2000 - 2001 Quadcap Software. All rights reserved.
002: *
003: * This software is distributed under the Quadcap Free Software License.
004: * This software may be used or modified for any purpose, personal or
005: * commercial. Open Source redistributions are permitted. Commercial
006: * redistribution of larger works derived from, or works which bundle
007: * this software requires a "Commercial Redistribution License"; see
008: * http://www.quadcap.com/purchase.
009: *
010: * Redistributions qualify as "Open Source" under one of the following terms:
011: *
012: * Redistributions are made at no charge beyond the reasonable cost of
013: * materials and delivery.
014: *
015: * Redistributions are accompanied by a copy of the Source Code or by an
016: * irrevocable offer to provide a copy of the Source Code for up to three
017: * years at the cost of materials and delivery. Such redistributions
018: * must allow further use, modification, and redistribution of the Source
019: * Code under substantially the same terms as this license.
020: *
021: * Redistributions of source code must retain the copyright notices as they
022: * appear in each source code file, these license terms, and the
023: * disclaimer/limitation of liability set forth as paragraph 6 below.
024: *
025: * Redistributions in binary form must reproduce this Copyright Notice,
026: * these license terms, and the disclaimer/limitation of liability set
027: * forth as paragraph 6 below, in the documentation and/or other materials
028: * provided with the distribution.
029: *
030: * The Software is provided on an "AS IS" basis. No warranty is
031: * provided that the Software is free of defects, or fit for a
032: * particular purpose.
033: *
034: * Limitation of Liability. Quadcap Software shall not be liable
035: * for any damages suffered by the Licensee or any third party resulting
036: * from use of the Software.
037: */
038:
039: // SAX input source.
040: // No warranty; no copyright -- use this as you will.
041: // $Id: InputSource.java,v 1.3 2001/01/06 06:11:02 stan Exp $
042: package org.xml.sax;
043:
044: import java.io.Reader;
045: import java.io.InputStream;
046:
047: /**
048: * A single input source for an XML entity.
049: *
050: * <p>This class allows a SAX application to encapsulate information
051: * about an input source in a single object, which may include
052: * a public identifier, a system identifier, a byte stream (possibly
053: * with a specified encoding), and/or a character stream.</p>
054: *
055: * <p>There are two places that the application will deliver this
056: * input source to the parser: as the argument to the Parser.parse
057: * method, or as the return value of the EntityResolver.resolveEntity
058: * method.</p>
059: *
060: * <p>The SAX parser will use the InputSource object to determine how
061: * to read XML input. If there is a character stream available, the
062: * parser will read that stream directly; if not, the parser will use
063: * a byte stream, if available; if neither a character stream nor a
064: * byte stream is available, the parser will attempt to open a URI
065: * connection to the resource identified by the system
066: * identifier.</p>
067: *
068: * <p>An InputSource object belongs to the application: the SAX parser
069: * shall never modify it in any way (it may modify a copy if
070: * necessary).</p>
071: *
072: * @author David Megginson (ak117@freenet.carleton.ca)
073: * @version 1.0
074: * @see org.xml.sax.Parser#parse
075: * @see org.xml.sax.EntityResolver#resolveEntity
076: * @see java.io.InputStream
077: * @see java.io.Reader
078: */
079: public class InputSource {
080:
081: /**
082: * Zero-argument default constructor.
083: *
084: * @see #setPublicId
085: * @see #setSystemId
086: * @see #setByteStream
087: * @see #setCharacterStream
088: * @see #setEncoding
089: */
090: public InputSource() {
091: }
092:
093: /**
094: * Create a new input source with a system identifier.
095: *
096: * <p>Applications may use setPublicId to include a
097: * public identifier as well, or setEncoding to specify
098: * the character encoding, if known.</p>
099: *
100: * <p>If the system identifier is a URL, it must be full resolved.</p>
101: *
102: * @param systemId The system identifier (URI).
103: * @see #setPublicId
104: * @see #setSystemId
105: * @see #setByteStream
106: * @see #setEncoding
107: * @see #setCharacterStream
108: */
109: public InputSource(String systemId) {
110: setSystemId(systemId);
111: }
112:
113: /**
114: * Create a new input source with a byte stream.
115: *
116: * <p>Application writers may use setSystemId to provide a base
117: * for resolving relative URIs, setPublicId to include a
118: * public identifier, and/or setEncoding to specify the object's
119: * character encoding.</p>
120: *
121: * @param byteStream The raw byte stream containing the document.
122: * @see #setPublicId
123: * @see #setSystemId
124: * @see #setEncoding
125: * @see #setByteStream
126: * @see #setCharacterStream
127: */
128: public InputSource(InputStream byteStream) {
129: setByteStream(byteStream);
130: }
131:
132: /**
133: * Create a new input source with a character stream.
134: *
135: * <p>Application writers may use setSystemId() to provide a base
136: * for resolving relative URIs, and setPublicId to include a
137: * public identifier.</p>
138: *
139: * <p>The character stream shall not include a byte order mark.</p>
140: *
141: * @see #setPublicId
142: * @see #setSystemId
143: * @see #setByteStream
144: * @see #setCharacterStream
145: */
146: public InputSource(Reader characterStream) {
147: setCharacterStream(characterStream);
148: }
149:
150: /**
151: * Set the public identifier for this input source.
152: *
153: * <p>The public identifier is always optional: if the application
154: * writer includes one, it will be provided as part of the
155: * location information.</p>
156: *
157: * @param publicId The public identifier as a string.
158: * @see #getPublicId
159: * @see org.xml.sax.Locator#getPublicId
160: * @see org.xml.sax.SAXParseException#getPublicId
161: */
162: public void setPublicId(String publicId) {
163: this .publicId = publicId;
164: }
165:
166: /**
167: * Get the public identifier for this input source.
168: *
169: * @return The public identifier, or null if none was supplied.
170: * @see #setPublicId
171: */
172: public String getPublicId() {
173: return publicId;
174: }
175:
176: /**
177: * Set the system identifier for this input source.
178: *
179: * <p>The system identifier is optional if there is a byte stream
180: * or a character stream, but it is still useful to provide one,
181: * since the application can use it to resolve relative URIs
182: * and can include it in error messages and warnings (the parser
183: * will attempt to open a connection to the URI only if
184: * there is no byte stream or character stream specified).</p>
185: *
186: * <p>If the application knows the character encoding of the
187: * object pointed to by the system identifier, it can register
188: * the encoding using the setEncoding method.</p>
189: *
190: * <p>If the system ID is a URL, it must be fully resolved.</p>
191: *
192: * @param systemId The system identifier as a string.
193: * @see #setEncoding
194: * @see #getSystemId
195: * @see org.xml.sax.Locator#getSystemId
196: * @see org.xml.sax.SAXParseException#getSystemId
197: */
198: public void setSystemId(String systemId) {
199: this .systemId = systemId;
200: }
201:
202: /**
203: * Get the system identifier for this input source.
204: *
205: * <p>The getEncoding method will return the character encoding
206: * of the object pointed to, or null if unknown.</p>
207: *
208: * <p>If the system ID is a URL, it will be fully resolved.</p>
209: *
210: * @return The system identifier.
211: * @see #setSystemId
212: * @see #getEncoding
213: */
214: public String getSystemId() {
215: return systemId;
216: }
217:
218: /**
219: * Set the byte stream for this input source.
220: *
221: * <p>The SAX parser will ignore this if there is also a character
222: * stream specified, but it will use a byte stream in preference
223: * to opening a URI connection itself.</p>
224: *
225: * <p>If the application knows the character encoding of the
226: * byte stream, it should set it with the setEncoding method.</p>
227: *
228: * @param byteStream A byte stream containing an XML document or
229: * other entity.
230: * @see #setEncoding
231: * @see #getByteStream
232: * @see #getEncoding
233: * @see java.io.InputStream
234: */
235: public void setByteStream(InputStream byteStream) {
236: this .byteStream = byteStream;
237: }
238:
239: /**
240: * Get the byte stream for this input source.
241: *
242: * <p>The getEncoding method will return the character
243: * encoding for this byte stream, or null if unknown.</p>
244: *
245: * @return The byte stream, or null if none was supplied.
246: * @see #getEncoding
247: * @see #setByteStream
248: */
249: public InputStream getByteStream() {
250: return byteStream;
251: }
252:
253: /**
254: * Set the character encoding, if known.
255: *
256: * <p>The encoding must be a string acceptable for an
257: * XML encoding declaration (see section 4.3.3 of the XML 1.0
258: * recommendation).</p>
259: *
260: * <p>This method has no effect when the application provides a
261: * character stream.</p>
262: *
263: * @param encoding A string describing the character encoding.
264: * @see #setSystemId
265: * @see #setByteStream
266: * @see #getEncoding
267: */
268: public void setEncoding(String encoding) {
269: this .encoding = encoding;
270: }
271:
272: /**
273: * Get the character encoding for a byte stream or URI.
274: *
275: * @return The encoding, or null if none was supplied.
276: * @see #setByteStream
277: * @see #getSystemId
278: * @see #getByteStream
279: */
280: public String getEncoding() {
281: return encoding;
282: }
283:
284: /**
285: * Set the character stream for this input source.
286: *
287: * <p>If there is a character stream specified, the SAX parser
288: * will ignore any byte stream and will not attempt to open
289: * a URI connection to the system identifier.</p>
290: *
291: * @param characterStream The character stream containing the
292: * XML document or other entity.
293: * @see #getCharacterStream
294: * @see java.io.Reader
295: */
296: public void setCharacterStream(Reader characterStream) {
297: this .characterStream = characterStream;
298: }
299:
300: /**
301: * Get the character stream for this input source.
302: *
303: * @return The character stream, or null if none was supplied.
304: * @see #setCharacterStream
305: */
306: public Reader getCharacterStream() {
307: return characterStream;
308: }
309:
310: //////////////////////////////////////////////////////////////////////
311: // Internal state.
312: //////////////////////////////////////////////////////////////////////
313:
314: private String publicId;
315: private String systemId;
316: private InputStream byteStream;
317: private String encoding;
318: private Reader characterStream;
319:
320: }
|