1 /* 2 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * 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 */ StreamSource()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 */ StreamSource(InputStream inputStream)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 */ StreamSource(InputStream inputStream, String systemId)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 */ StreamSource(Reader reader)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 */ StreamSource(Reader reader, String systemId)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 */ StreamSource(String systemId)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 */ StreamSource(File f)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 */ setInputStream(InputStream inputStream)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 */ getInputStream()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 */ setReader(Reader reader)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 */ getReader()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 */ setPublicId(String publicId)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 */ getPublicId()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 */ setSystemId(String systemId)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 */ getSystemId()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 */ setSystemId(File f)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 } 285