1 /*
2 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.xml.transform.stream;
27
28 import java.io.File;
29 import java.io.InputStream;
30 import java.io.Reader;
31
32 import javax.xml.transform.Source;
33
34 /**
35 * <p>Acts as an holder for a transformation Source in the form
36 * of a stream of XML markup.</p>
37 *
38 * <p><em>Note:</em> Due to their internal use of either a {@link Reader} or {@link InputStream} instance,
39 * <code>StreamSource</code> instances may only be used once.</p>
40 *
41 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
42 */
43 public class StreamSource implements Source {
44
45 /** If {@link javax.xml.transform.TransformerFactory#getFeature}
46 * returns true when passed this value as an argument,
47 * the Transformer supports Source input of this type.
48 */
49 public static final String FEATURE =
50 "http://javax.xml.transform.stream.StreamSource/feature";
51
52 /**
53 * <p>Zero-argument default constructor. If this constructor is used, and
54 * no Stream source is set using
55 * {@link #setInputStream(java.io.InputStream inputStream)} or
56 * {@link #setReader(java.io.Reader reader)}, then the
57 * <code>Transformer</code> will
58 * create an empty source {@link java.io.InputStream} using
59 * {@link java.io.InputStream#InputStream() new InputStream()}.</p>
60 *
61 * @see javax.xml.transform.Transformer#transform(Source xmlSource, Result outputTarget)
62 */
63 public StreamSource() { }
64
65 /**
66 * Construct a StreamSource from a byte stream. Normally,
67 * a stream should be used rather than a reader, so
68 * the XML parser can resolve character encoding specified
69 * by the XML declaration.
70 *
71 * <p>If this constructor is used to process a stylesheet, normally
72 * setSystemId should also be called, so that relative URI references
73 * can be resolved.</p>
74 *
75 * @param inputStream A valid InputStream reference to an XML stream.
76 */
77 public StreamSource(InputStream inputStream) {
78 setInputStream(inputStream);
79 }
80
81 /**
82 * Construct a StreamSource from a byte stream. Normally,
83 * a stream should be used rather than a reader, so that
84 * the XML parser can resolve character encoding specified
85 * by the XML declaration.
86 *
87 * <p>This constructor allows the systemID to be set in addition
88 * to the input stream, which allows relative URIs
89 * to be processed.</p>
90 *
91 * @param inputStream A valid InputStream reference to an XML stream.
92 * @param systemId Must be a String that conforms to the URI syntax.
93 */
94 public StreamSource(InputStream inputStream, String systemId) {
95 setInputStream(inputStream);
96 setSystemId(systemId);
97 }
98
99 /**
100 * Construct a StreamSource from a character reader. Normally,
101 * a stream should be used rather than a reader, so that
102 * the XML parser can resolve character encoding specified
103 * by the XML declaration. However, in many cases the encoding
104 * of the input stream is already resolved, as in the case of
105 * reading XML from a StringReader.
106 *
107 * @param reader A valid Reader reference to an XML character stream.
108 */
109 public StreamSource(Reader reader) {
110 setReader(reader);
111 }
112
113 /**
114 * Construct a StreamSource from a character reader. Normally,
115 * a stream should be used rather than a reader, so that
116 * the XML parser may resolve character encoding specified
117 * by the XML declaration. However, in many cases the encoding
118 * of the input stream is already resolved, as in the case of
119 * reading XML from a StringReader.
120 *
121 * @param reader A valid Reader reference to an XML character stream.
122 * @param systemId Must be a String that conforms to the URI syntax.
123 */
124 public StreamSource(Reader reader, String systemId) {
125 setReader(reader);
126 setSystemId(systemId);
127 }
128
129 /**
130 * Construct a StreamSource from a URL.
131 *
132 * @param systemId Must be a String that conforms to the URI syntax.
133 */
134 public StreamSource(String systemId) {
135 this.systemId = systemId;
136 }
137
138 /**
139 * Construct a StreamSource from a File.
140 *
141 * @param f Must a non-null File reference.
142 */
143 public StreamSource(File f) {
144 //convert file to appropriate URI, f.toURI().toASCIIString()
145 //converts the URI to string as per rule specified in
146 //RFC 2396,
147 setSystemId(f.toURI().toASCIIString());
148 }
149
150 /**
151 * Set the byte stream to be used as input. Normally,
152 * a stream should be used rather than a reader, so that
153 * the XML parser can resolve character encoding specified
154 * by the XML declaration.
155 *
156 * <p>If this Source object is used to process a stylesheet, normally
157 * setSystemId should also be called, so that relative URL references
158 * can be resolved.</p>
159 *
160 * @param inputStream A valid InputStream reference to an XML stream.
161 */
162 public void setInputStream(InputStream inputStream) {
163 this.inputStream = inputStream;
164 }
165
166 /**
167 * Get the byte stream that was set with setByteStream.
168 *
169 * @return The byte stream that was set with setByteStream, or null
170 * if setByteStream or the ByteStream constructor was not called.
171 */
172 public InputStream getInputStream() {
173 return inputStream;
174 }
175
176 /**
177 * Set the input to be a character reader. Normally,
178 * a stream should be used rather than a reader, so that
179 * the XML parser can resolve character encoding specified
180 * by the XML declaration. However, in many cases the encoding
181 * of the input stream is already resolved, as in the case of
182 * reading XML from a StringReader.
183 *
184 * @param reader A valid Reader reference to an XML CharacterStream.
185 */
186 public void setReader(Reader reader) {
187 this.reader = reader;
188 }
189
190 /**
191 * Get the character stream that was set with setReader.
192 *
193 * @return The character stream that was set with setReader, or null
194 * if setReader or the Reader constructor was not called.
195 */
196 public Reader getReader() {
197 return reader;
198 }
199
200 /**
201 * Set the public identifier for this Source.
202 *
203 * <p>The public identifier is always optional: if the application
204 * writer includes one, it will be provided as part of the
205 * location information.</p>
206 *
207 * @param publicId The public identifier as a string.
208 */
209 public void setPublicId(String publicId) {
210 this.publicId = publicId;
211 }
212
213 /**
214 * Get the public identifier that was set with setPublicId.
215 *
216 * @return The public identifier that was set with setPublicId, or null
217 * if setPublicId was not called.
218 */
219 public String getPublicId() {
220 return publicId;
221 }
222
223 /**
224 * Set the system identifier for this Source.
225 *
226 * <p>The system identifier is optional if there is a byte stream
227 * or a character stream, but it is still useful to provide one,
228 * since the application can use it to resolve relative URIs
229 * and can include it in error messages and warnings (the parser
230 * will attempt to open a connection to the URI only if
231 * there is no byte stream or character stream specified).</p>
232 *
233 * @param systemId The system identifier as a URL string.
234 */
235 public void setSystemId(String systemId) {
236 this.systemId = systemId;
237 }
238
239 /**
240 * Get the system identifier that was set with setSystemId.
241 *
242 * @return The system identifier that was set with setSystemId, or null
243 * if setSystemId was not called.
244 */
245 public String getSystemId() {
246 return systemId;
247 }
248
249 /**
250 * Set the system ID from a File reference.
251 *
252 * @param f Must a non-null File reference.
253 */
254 public void setSystemId(File f) {
255 //convert file to appropriate URI, f.toURI().toASCIIString()
256 //converts the URI to string as per rule specified in
257 //RFC 2396,
258 this.systemId = f.toURI().toASCIIString();
259 }
260
261 //////////////////////////////////////////////////////////////////////
262 // Internal state.
263 //////////////////////////////////////////////////////////////////////
264
265 /**
266 * The public identifier for this input source, or null.
267 */
268 private String publicId;
269
270 /**
271 * The system identifier as a URL string, or null.
272 */
273 private String systemId;
274
275 /**
276 * The byte stream for this Source, or null.
277 */
278 private InputStream inputStream;
279
280 /**
281 * The character stream for this Source, or null.
282 */
283 private Reader reader;
284 }
Save This Page