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