001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: // SAX input source.
028: package org.xml.sax;
029:
030: import java.io.Reader;
031: import java.io.InputStream;
032:
033: /**
034: * A single input source for an XML entity.
035: *
036: * <blockquote>
037: * <em>This module, both source code and documentation, is in the
038: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
039: * </blockquote>
040: *
041: * <p>This class allows a SAX application to encapsulate information
042: * about an input source in a single object, which may include
043: * a public identifier, a system identifier, a byte stream (possibly
044: * with a specified encoding), and/or a character stream.</p>
045: *
046: * <p>There are two places that the application will deliver this
047: * input source to the parser: as the argument to the Parser.parse
048: * method, or as the return value of the EntityResolver.resolveEntity
049: * method.</p>
050: *
051: * <p>The SAX parser will use the InputSource object to determine how
052: * to read XML input. If there is a character stream available, the
053: * parser will read that stream directly; if not, the parser will use
054: * a byte stream, if available; if neither a character stream nor a
055: * byte stream is available, the parser will attempt to open a URI
056: * connection to the resource identified by the system
057: * identifier.</p>
058: *
059: * <p>An InputSource object belongs to the application: the SAX parser
060: * shall never modify it in any way (it may modify a copy if
061: * necessary).</p>
062: *
063: * @since SAX 1.0
064: *
065: * @version 2.0r2pre
066: * @see org.xml.sax.Parser#parse
067: * @see org.xml.sax.EntityResolver#resolveEntity
068: * @see java.io.InputStream
069: * @see java.io.Reader
070: */
071: public class InputSource {
072:
073: /**
074: * Zero-argument default constructor.
075: *
076: * @see #setPublicId
077: * @see #setSystemId
078: * @see #setByteStream
079: * @see #setCharacterStream
080: * @see #setEncoding
081: */
082: public InputSource() {
083: }
084:
085: /**
086: * Create a new input source with a system identifier.
087: *
088: * <p>Applications may use setPublicId to include a
089: * public identifier as well, or setEncoding to specify
090: * the character encoding, if known.</p>
091: *
092: * <p>If the system identifier is a URL, it must be full resolved.</p>
093: *
094: * @param systemId The system identifier (URI).
095: * @see #setPublicId
096: * @see #setSystemId
097: * @see #setByteStream
098: * @see #setEncoding
099: * @see #setCharacterStream
100: */
101: public InputSource(String systemId) {
102: setSystemId(systemId);
103: }
104:
105: /**
106: * Create a new input source with a byte stream.
107: *
108: * <p>Application writers may use setSystemId to provide a base
109: * for resolving relative URIs, setPublicId to include a
110: * public identifier, and/or setEncoding to specify the object's
111: * character encoding.</p>
112: *
113: * @param byteStream The raw byte stream containing the document.
114: * @see #setPublicId
115: * @see #setSystemId
116: * @see #setEncoding
117: * @see #setByteStream
118: * @see #setCharacterStream
119: */
120: public InputSource(InputStream byteStream) {
121: setByteStream(byteStream);
122: }
123:
124: /**
125: * Create a new input source with a character stream.
126: *
127: * <p>Application writers may use setSystemId() to provide a base
128: * for resolving relative URIs, and setPublicId to include a
129: * public identifier.</p>
130: *
131: * <p>The character stream shall not include a byte order mark.</p>
132: *
133: * @see #setPublicId
134: * @see #setSystemId
135: * @see #setByteStream
136: * @see #setCharacterStream
137: */
138: public InputSource(Reader characterStream) {
139: setCharacterStream(characterStream);
140: }
141:
142: /**
143: * Set the public identifier for this input source.
144: *
145: * <p>The public identifier is always optional: if the application
146: * writer includes one, it will be provided as part of the
147: * location information.</p>
148: *
149: * @param publicId The public identifier as a string.
150: * @see #getPublicId
151: * @see org.xml.sax.Locator#getPublicId
152: * @see org.xml.sax.SAXParseException#getPublicId
153: */
154: public void setPublicId(String publicId) {
155: this .publicId = publicId;
156: }
157:
158: /**
159: * Get the public identifier for this input source.
160: *
161: * @return The public identifier, or null if none was supplied.
162: * @see #setPublicId
163: */
164: public String getPublicId() {
165: return publicId;
166: }
167:
168: /**
169: * Set the system identifier for this input source.
170: *
171: * <p>The system identifier is optional if there is a byte stream
172: * or a character stream, but it is still useful to provide one,
173: * since the application can use it to resolve relative URIs
174: * and can include it in error messages and warnings (the parser
175: * will attempt to open a connection to the URI only if
176: * there is no byte stream or character stream specified).</p>
177: *
178: * <p>If the application knows the character encoding of the
179: * object pointed to by the system identifier, it can register
180: * the encoding using the setEncoding method.</p>
181: *
182: * <p>If the system ID is a URL, it must be fully resolved.</p>
183: *
184: * @param systemId The system identifier as a string.
185: * @see #setEncoding
186: * @see #getSystemId
187: * @see org.xml.sax.Locator#getSystemId
188: * @see org.xml.sax.SAXParseException#getSystemId
189: */
190: public void setSystemId(String systemId) {
191: this .systemId = systemId;
192: }
193:
194: /**
195: * Get the system identifier for this input source.
196: *
197: * <p>The getEncoding method will return the character encoding
198: * of the object pointed to, or null if unknown.</p>
199: *
200: * <p>If the system ID is a URL, it will be fully resolved.</p>
201: *
202: * @return The system identifier, or null if none was supplied.
203: * @see #setSystemId
204: * @see #getEncoding
205: */
206: public String getSystemId() {
207: return systemId;
208: }
209:
210: /**
211: * Set the byte stream for this input source.
212: *
213: * <p>The SAX parser will ignore this if there is also a character
214: * stream specified, but it will use a byte stream in preference
215: * to opening a URI connection itself.</p>
216: *
217: * <p>If the application knows the character encoding of the
218: * byte stream, it should set it with the setEncoding method.</p>
219: *
220: * @param byteStream A byte stream containing an XML document or
221: * other entity.
222: * @see #setEncoding
223: * @see #getByteStream
224: * @see #getEncoding
225: * @see java.io.InputStream
226: */
227: public void setByteStream(InputStream byteStream) {
228: this .byteStream = byteStream;
229: }
230:
231: /**
232: * Get the byte stream for this input source.
233: *
234: * <p>The getEncoding method will return the character
235: * encoding for this byte stream, or null if unknown.</p>
236: *
237: * @return The byte stream, or null if none was supplied.
238: * @see #getEncoding
239: * @see #setByteStream
240: */
241: public InputStream getByteStream() {
242: return byteStream;
243: }
244:
245: /**
246: * Set the character encoding, if known.
247: *
248: * <p>The encoding must be a string acceptable for an
249: * XML encoding declaration (see section 4.3.3 of the XML 1.0
250: * recommendation).</p>
251: *
252: * <p>This method has no effect when the application provides a
253: * character stream.</p>
254: *
255: * @param encoding A string describing the character encoding.
256: * @see #setSystemId
257: * @see #setByteStream
258: * @see #getEncoding
259: */
260: public void setEncoding(String encoding) {
261: this .encoding = encoding;
262: }
263:
264: /**
265: * Get the character encoding for a byte stream or URI.
266: *
267: * @return The encoding, or null if none was supplied.
268: * @see #setByteStream
269: * @see #getSystemId
270: * @see #getByteStream
271: */
272: public String getEncoding() {
273: return encoding;
274: }
275:
276: /**
277: * Set the character stream for this input source.
278: *
279: * <p>If there is a character stream specified, the SAX parser
280: * will ignore any byte stream and will not attempt to open
281: * a URI connection to the system identifier.</p>
282: *
283: * @param characterStream The character stream containing the
284: * XML document or other entity.
285: * @see #getCharacterStream
286: * @see java.io.Reader
287: */
288: public void setCharacterStream(Reader characterStream) {
289: this .characterStream = characterStream;
290: }
291:
292: /**
293: * Get the character stream for this input source.
294: *
295: * @return The character stream, or null if none was supplied.
296: * @see #setCharacterStream
297: */
298: public Reader getCharacterStream() {
299: return characterStream;
300: }
301:
302: ////////////////////////////////////////////////////////////////////
303: // Internal state.
304: ////////////////////////////////////////////////////////////////////
305:
306: private String publicId;
307: private String systemId;
308: private InputStream byteStream;
309: private String encoding;
310: private Reader characterStream;
311:
312: }
313:
314: // end of InputSource.java
|