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