001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.transform.stream;
027
028 import java.io.File;
029 import java.io.InputStream;
030 import java.io.Reader;
031
032 import javax.xml.transform.Source;
033
034 /**
035 * <p>Acts as an holder for a transformation Source in the form
036 * of a stream of XML markup.</p>
037 *
038 * <p><em>Note:</em> Due to their internal use of either a {@link Reader} or {@link InputStream} instance,
039 * <code>StreamSource</code> instances may only be used once.</p>
040 *
041 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
042 * @version $Revision: 1.4 $, $Date: 2005/11/03 19:34:27 $
043 */
044 public class StreamSource implements Source {
045
046 /** If {@link javax.xml.transform.TransformerFactory#getFeature}
047 * returns true when passed this value as an argument,
048 * the Transformer supports Source input of this type.
049 */
050 public static final String FEATURE = "http://javax.xml.transform.stream.StreamSource/feature";
051
052 /**
053 * <p>Zero-argument default constructor. If this constructor is used, and
054 * no Stream source is set using
055 * {@link #setInputStream(java.io.InputStream inputStream)} or
056 * {@link #setReader(java.io.Reader reader)}, then the
057 * <code>Transformer</code> will
058 * create an empty source {@link java.io.InputStream} using
059 * {@link java.io.InputStream#InputStream() new InputStream()}.</p>
060 *
061 * @see javax.xml.transform.Transformer#transform(Source xmlSource, Result outputTarget)
062 */
063 public StreamSource() {
064 }
065
066 /**
067 * Construct a StreamSource from a byte stream. Normally,
068 * a stream should be used rather than a reader, so
069 * the XML parser can resolve character encoding specified
070 * by the XML declaration.
071 *
072 * <p>If this constructor is used to process a stylesheet, normally
073 * setSystemId should also be called, so that relative URI references
074 * can be resolved.</p>
075 *
076 * @param inputStream A valid InputStream reference to an XML stream.
077 */
078 public StreamSource(InputStream inputStream) {
079 setInputStream(inputStream);
080 }
081
082 /**
083 * Construct a StreamSource from a byte stream. Normally,
084 * a stream should be used rather than a reader, so that
085 * the XML parser can resolve character encoding specified
086 * by the XML declaration.
087 *
088 * <p>This constructor allows the systemID to be set in addition
089 * to the input stream, which allows relative URIs
090 * to be processed.</p>
091 *
092 * @param inputStream A valid InputStream reference to an XML stream.
093 * @param systemId Must be a String that conforms to the URI syntax.
094 */
095 public StreamSource(InputStream inputStream, String systemId) {
096 setInputStream(inputStream);
097 setSystemId(systemId);
098 }
099
100 /**
101 * Construct a StreamSource from a character reader. Normally,
102 * a stream should be used rather than a reader, so that
103 * the XML parser can resolve character encoding specified
104 * by the XML declaration. However, in many cases the encoding
105 * of the input stream is already resolved, as in the case of
106 * reading XML from a StringReader.
107 *
108 * @param reader A valid Reader reference to an XML character stream.
109 */
110 public StreamSource(Reader reader) {
111 setReader(reader);
112 }
113
114 /**
115 * Construct a StreamSource from a character reader. Normally,
116 * a stream should be used rather than a reader, so that
117 * the XML parser may resolve character encoding specified
118 * by the XML declaration. However, in many cases the encoding
119 * of the input stream is already resolved, as in the case of
120 * reading XML from a StringReader.
121 *
122 * @param reader A valid Reader reference to an XML character stream.
123 * @param systemId Must be a String that conforms to the URI syntax.
124 */
125 public StreamSource(Reader reader, String systemId) {
126 setReader(reader);
127 setSystemId(systemId);
128 }
129
130 /**
131 * Construct a StreamSource from a URL.
132 *
133 * @param systemId Must be a String that conforms to the URI syntax.
134 */
135 public StreamSource(String systemId) {
136 this .systemId = systemId;
137 }
138
139 /**
140 * Construct a StreamSource from a File.
141 *
142 * @param f Must a non-null File reference.
143 */
144 public StreamSource(File f) {
145 //convert file to appropriate URI, f.toURI().toASCIIString()
146 //converts the URI to string as per rule specified in
147 //RFC 2396,
148 setSystemId(f.toURI().toASCIIString());
149 }
150
151 /**
152 * Set the byte stream to be used as input. Normally,
153 * a stream should be used rather than a reader, so that
154 * the XML parser can resolve character encoding specified
155 * by the XML declaration.
156 *
157 * <p>If this Source object is used to process a stylesheet, normally
158 * setSystemId should also be called, so that relative URL references
159 * can be resolved.</p>
160 *
161 * @param inputStream A valid InputStream reference to an XML stream.
162 */
163 public void setInputStream(InputStream inputStream) {
164 this .inputStream = inputStream;
165 }
166
167 /**
168 * Get the byte stream that was set with setByteStream.
169 *
170 * @return The byte stream that was set with setByteStream, or null
171 * if setByteStream or the ByteStream constructor was not called.
172 */
173 public InputStream getInputStream() {
174 return inputStream;
175 }
176
177 /**
178 * Set the input to be a character reader. Normally,
179 * a stream should be used rather than a reader, so that
180 * the XML parser can resolve character encoding specified
181 * by the XML declaration. However, in many cases the encoding
182 * of the input stream is already resolved, as in the case of
183 * reading XML from a StringReader.
184 *
185 * @param reader A valid Reader reference to an XML CharacterStream.
186 */
187 public void setReader(Reader reader) {
188 this .reader = reader;
189 }
190
191 /**
192 * Get the character stream that was set with setReader.
193 *
194 * @return The character stream that was set with setReader, or null
195 * if setReader or the Reader constructor was not called.
196 */
197 public Reader getReader() {
198 return reader;
199 }
200
201 /**
202 * Set the public identifier for this Source.
203 *
204 * <p>The public identifier is always optional: if the application
205 * writer includes one, it will be provided as part of the
206 * location information.</p>
207 *
208 * @param publicId The public identifier as a string.
209 */
210 public void setPublicId(String publicId) {
211 this .publicId = publicId;
212 }
213
214 /**
215 * Get the public identifier that was set with setPublicId.
216 *
217 * @return The public identifier that was set with setPublicId, or null
218 * if setPublicId was not called.
219 */
220 public String getPublicId() {
221 return publicId;
222 }
223
224 /**
225 * Set the system identifier for this Source.
226 *
227 * <p>The system identifier is optional if there is a byte stream
228 * or a character stream, but it is still useful to provide one,
229 * since the application can use it to resolve relative URIs
230 * and can include it in error messages and warnings (the parser
231 * will attempt to open a connection to the URI only if
232 * there is no byte stream or character stream specified).</p>
233 *
234 * @param systemId The system identifier as a URL string.
235 */
236 public void setSystemId(String systemId) {
237 this .systemId = systemId;
238 }
239
240 /**
241 * Get the system identifier that was set with setSystemId.
242 *
243 * @return The system identifier that was set with setSystemId, or null
244 * if setSystemId was not called.
245 */
246 public String getSystemId() {
247 return systemId;
248 }
249
250 /**
251 * Set the system ID from a File reference.
252 *
253 * @param f Must a non-null File reference.
254 */
255 public void setSystemId(File f) {
256 //convert file to appropriate URI, f.toURI().toASCIIString()
257 //converts the URI to string as per rule specified in
258 //RFC 2396,
259 this .systemId = f.toURI().toASCIIString();
260 }
261
262 //////////////////////////////////////////////////////////////////////
263 // Internal state.
264 //////////////////////////////////////////////////////////////////////
265
266 /**
267 * The public identifier for this input source, or null.
268 */
269 private String publicId;
270
271 /**
272 * The system identifier as a URL string, or null.
273 */
274 private String systemId;
275
276 /**
277 * The byte stream for this Source, or null.
278 */
279 private InputStream inputStream;
280
281 /**
282 * The character stream for this Source, or null.
283 */
284 private Reader reader;
285 }
|