001: // SAX input source.
002: // http://www.saxproject.org
003: // No warranty; no copyright -- use this as you will.
004: // $Id: InputSource.java,v 1.9 2002/01/30 21:13:45 dbrownell Exp $
005:
006: package org.xml.sax;
007:
008: import java.io.Reader;
009: import java.io.InputStream;
010:
011: /**
012: * A single input source for an XML entity.
013: *
014: * <blockquote>
015: * <em>This module, both source code and documentation, is in the
016: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
017: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
018: * for further information.
019: * </blockquote>
020: *
021: * <p>This class allows a SAX application to encapsulate information
022: * about an input source in a single object, which may include
023: * a public identifier, a system identifier, a byte stream (possibly
024: * with a specified encoding), and/or a character stream.</p>
025: *
026: * <p>There are two places that the application can deliver an
027: * input source to the parser: as the argument to the Parser.parse
028: * method, or as the return value of the EntityResolver.resolveEntity
029: * method.</p>
030: *
031: * <p>The SAX parser will use the InputSource object to determine how
032: * to read XML input. If there is a character stream available, the
033: * parser will read that stream directly, disregarding any text
034: * encoding declaration found in that stream.
035: * If there is no character stream, but there is
036: * a byte stream, the parser will use that byte stream, using the
037: * encoding specified in the InputSource or else (if no encoding is
038: * specified) autodetecting the character encoding using an algorithm
039: * such as the one in the XML specification. If neither a character
040: * stream nor a
041: * byte stream is available, the parser will attempt to open a URI
042: * connection to the resource identified by the system
043: * identifier.</p>
044: *
045: * <p>An InputSource object belongs to the application: the SAX parser
046: * shall never modify it in any way (it may modify a copy if
047: * necessary). However, standard processing of both byte and
048: * character streams is to close them on as part of end-of-parse cleanup,
049: * so applications should not attempt to re-use such streams after they
050: * have been handed to a parser. </p>
051: *
052: * @since SAX 1.0
053: * @author David Megginson
054: * @version 2.0.1 (sax2r2)
055: * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
056: * @see org.xml.sax.EntityResolver#resolveEntity
057: * @see j2me.io.InputStream
058: * @see j2me.io.Reader
059: */
060: public class InputSource {
061:
062: /**
063: * Zero-argument default constructor.
064: *
065: * @see #setPublicId
066: * @see #setSystemId
067: * @see #setByteStream
068: * @see #setCharacterStream
069: * @see #setEncoding
070: */
071: public InputSource() {
072: }
073:
074: /**
075: * Create a new input source with a system identifier.
076: *
077: * <p>Applications may use setPublicId to include a
078: * public identifier as well, or setEncoding to specify
079: * the character encoding, if known.</p>
080: *
081: * <p>If the system identifier is a URL, it must be fully
082: * resolved (it may not be a relative URL).</p>
083: *
084: * @param systemId The system identifier (URI).
085: * @see #setPublicId
086: * @see #setSystemId
087: * @see #setByteStream
088: * @see #setEncoding
089: * @see #setCharacterStream
090: */
091: public InputSource(String systemId) {
092: setSystemId(systemId);
093: }
094:
095: /**
096: * Create a new input source with a byte stream.
097: *
098: * <p>Application writers should use setSystemId() to provide a base
099: * for resolving relative URIs, may use setPublicId to include a
100: * public identifier, and may use setEncoding to specify the object's
101: * character encoding.</p>
102: *
103: * @param byteStream The raw byte stream containing the document.
104: * @see #setPublicId
105: * @see #setSystemId
106: * @see #setEncoding
107: * @see #setByteStream
108: * @see #setCharacterStream
109: */
110: public InputSource(InputStream byteStream) {
111: setByteStream(byteStream);
112: }
113:
114: /**
115: * Create a new input source with a character stream.
116: *
117: * <p>Application writers should use setSystemId() to provide a base
118: * for resolving relative URIs, and may use setPublicId to include a
119: * public identifier.</p>
120: *
121: * <p>The character stream shall not include a byte order mark.</p>
122: *
123: * @see #setPublicId
124: * @see #setSystemId
125: * @see #setByteStream
126: * @see #setCharacterStream
127: */
128: public InputSource(Reader characterStream) {
129: setCharacterStream(characterStream);
130: }
131:
132: /**
133: * Set the public identifier for this input source.
134: *
135: * <p>The public identifier is always optional: if the application
136: * writer includes one, it will be provided as part of the
137: * location information.</p>
138: *
139: * @param publicId The public identifier as a string.
140: * @see #getPublicId
141: * @see org.xml.sax.Locator#getPublicId
142: * @see org.xml.sax.SAXParseException#getPublicId
143: */
144: public void setPublicId(String publicId) {
145: this .publicId = publicId;
146: }
147:
148: /**
149: * Get the public identifier for this input source.
150: *
151: * @return The public identifier, or null if none was supplied.
152: * @see #setPublicId
153: */
154: public String getPublicId() {
155: return publicId;
156: }
157:
158: /**
159: * Set the system identifier for this input source.
160: *
161: * <p>The system identifier is optional if there is a byte stream
162: * or a character stream, but it is still useful to provide one,
163: * since the application can use it to resolve relative URIs
164: * and can include it in error messages and warnings (the parser
165: * will attempt to open a connection to the URI only if
166: * there is no byte stream or character stream specified).</p>
167: *
168: * <p>If the application knows the character encoding of the
169: * object pointed to by the system identifier, it can register
170: * the encoding using the setEncoding method.</p>
171: *
172: * <p>If the system identifier is a URL, it must be fully
173: * resolved (it may not be a relative URL).</p>
174: *
175: * @param systemId The system identifier as a string.
176: * @see #setEncoding
177: * @see #getSystemId
178: * @see org.xml.sax.Locator#getSystemId
179: * @see org.xml.sax.SAXParseException#getSystemId
180: */
181: public void setSystemId(String systemId) {
182: this .systemId = systemId;
183: }
184:
185: /**
186: * Get the system identifier for this input source.
187: *
188: * <p>The getEncoding method will return the character encoding
189: * of the object pointed to, or null if unknown.</p>
190: *
191: * <p>If the system ID is a URL, it will be fully resolved.</p>
192: *
193: * @return The system identifier, or null if none was supplied.
194: * @see #setSystemId
195: * @see #getEncoding
196: */
197: public String getSystemId() {
198: return systemId;
199: }
200:
201: /**
202: * Set the byte stream for this input source.
203: *
204: * <p>The SAX parser will ignore this if there is also a character
205: * stream specified, but it will use a byte stream in preference
206: * to opening a URI connection itself.</p>
207: *
208: * <p>If the application knows the character encoding of the
209: * byte stream, it should set it with the setEncoding method.</p>
210: *
211: * @param byteStream A byte stream containing an XML document or
212: * other entity.
213: * @see #setEncoding
214: * @see #getByteStream
215: * @see #getEncoding
216: * @see j2me.io.InputStream
217: */
218: public void setByteStream(InputStream byteStream) {
219: this .byteStream = byteStream;
220: }
221:
222: /**
223: * Get the byte stream for this input source.
224: *
225: * <p>The getEncoding method will return the character
226: * encoding for this byte stream, or null if unknown.</p>
227: *
228: * @return The byte stream, or null if none was supplied.
229: * @see #getEncoding
230: * @see #setByteStream
231: */
232: public InputStream getByteStream() {
233: return byteStream;
234: }
235:
236: /**
237: * Set the character encoding, if known.
238: *
239: * <p>The encoding must be a string acceptable for an
240: * XML encoding declaration (see section 4.3.3 of the XML 1.0
241: * recommendation).</p>
242: *
243: * <p>This method has no effect when the application provides a
244: * character stream.</p>
245: *
246: * @param encoding A string describing the character encoding.
247: * @see #setSystemId
248: * @see #setByteStream
249: * @see #getEncoding
250: */
251: public void setEncoding(String encoding) {
252: this .encoding = encoding;
253: }
254:
255: /**
256: * Get the character encoding for a byte stream or URI.
257: * This value will be ignored when the application provides a
258: * character stream.
259: *
260: * @return The encoding, or null if none was supplied.
261: * @see #setByteStream
262: * @see #getSystemId
263: * @see #getByteStream
264: */
265: public String getEncoding() {
266: return encoding;
267: }
268:
269: /**
270: * Set the character stream for this input source.
271: *
272: * <p>If there is a character stream specified, the SAX parser
273: * will ignore any byte stream and will not attempt to open
274: * a URI connection to the system identifier.</p>
275: *
276: * @param characterStream The character stream containing the
277: * XML document or other entity.
278: * @see #getCharacterStream
279: * @see j2me.io.Reader
280: */
281: public void setCharacterStream(Reader characterStream) {
282: this .characterStream = characterStream;
283: }
284:
285: /**
286: * Get the character stream for this input source.
287: *
288: * @return The character stream, or null if none was supplied.
289: * @see #setCharacterStream
290: */
291: public Reader getCharacterStream() {
292: return characterStream;
293: }
294:
295: ////////////////////////////////////////////////////////////////////
296: // Internal state.
297: ////////////////////////////////////////////////////////////////////
298:
299: private String publicId;
300: private String systemId;
301: private InputStream byteStream;
302: private String encoding;
303: private Reader characterStream;
304:
305: }
306:
307: // end of InputSource.java
|