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 javax.xml.transform.Result;
29 
30 import java.io.File;
31 import java.io.OutputStream;
32 import java.io.Writer;
33 import java.net.MalformedURLException;
34 
35 /**
36  * <p>Acts as an holder for a transformation result,
37  * which may be XML, plain Text, HTML, or some other form of markup.</p>
38  *
39  * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
40  */
41 public class StreamResult implements Result {
42 
43     /** If {@link javax.xml.transform.TransformerFactory#getFeature}
44      * returns true when passed this value as an argument,
45      * the Transformer supports Result output of this type.
46      */
47     public static final String FEATURE =
48         "http://javax.xml.transform.stream.StreamResult/feature";
49 
50     /**
51      * Zero-argument default constructor.
52      */
StreamResult()53     public StreamResult() {
54     }
55 
56     /**
57      * Construct a StreamResult from a byte stream.  Normally,
58      * a stream should be used rather than a reader, so that
59      * the transformer may use instructions contained in the
60      * transformation instructions to control the encoding.
61      *
62      * @param outputStream A valid OutputStream reference.
63      */
StreamResult(OutputStream outputStream)64     public StreamResult(OutputStream outputStream) {
65         setOutputStream(outputStream);
66     }
67 
68     /**
69      * Construct a StreamResult from a character stream.  Normally,
70      * a stream should be used rather than a reader, so that
71      * the transformer may use instructions contained in the
72      * transformation instructions to control the encoding.  However,
73      * there are times when it is useful to write to a character
74      * stream, such as when using a StringWriter.
75      *
76      * @param writer  A valid Writer reference.
77      */
StreamResult(Writer writer)78     public StreamResult(Writer writer) {
79         setWriter(writer);
80     }
81 
82     /**
83      * Construct a StreamResult from a URL.
84      *
85      * @param systemId Must be a String that conforms to the URI syntax.
86      */
StreamResult(String systemId)87     public StreamResult(String systemId) {
88         this.systemId = systemId;
89     }
90 
91     /**
92      * Construct a StreamResult from a File.
93      *
94      * @param f Must a non-null File reference.
95      */
StreamResult(File f)96     public StreamResult(File f) {
97         //convert file to appropriate URI, f.toURI().toASCIIString()
98         //converts the URI to string as per rule specified in
99         //RFC 2396,
100         setSystemId(f.toURI().toASCIIString());
101     }
102 
103     /**
104      * Set the ByteStream that is to be written to.  Normally,
105      * a stream should be used rather than a reader, so that
106      * the transformer may use instructions contained in the
107      * transformation instructions to control the encoding.
108      *
109      * @param outputStream A valid OutputStream reference.
110      */
setOutputStream(OutputStream outputStream)111     public void setOutputStream(OutputStream outputStream) {
112         this.outputStream = outputStream;
113     }
114 
115     /**
116      * Get the byte stream that was set with setOutputStream.
117      *
118      * @return The byte stream that was set with setOutputStream, or null
119      * if setOutputStream or the ByteStream constructor was not called.
120      */
getOutputStream()121     public OutputStream getOutputStream() {
122         return outputStream;
123     }
124 
125     /**
126      * Set the writer that is to receive the result.  Normally,
127      * a stream should be used rather than a writer, so that
128      * the transformer may use instructions contained in the
129      * transformation instructions to control the encoding.  However,
130      * there are times when it is useful to write to a writer,
131      * such as when using a StringWriter.
132      *
133      * @param writer  A valid Writer reference.
134      */
setWriter(Writer writer)135     public void setWriter(Writer writer) {
136         this.writer = writer;
137     }
138 
139     /**
140      * Get the character stream that was set with setWriter.
141      *
142      * @return The character stream that was set with setWriter, or null
143      * if setWriter or the Writer constructor was not called.
144      */
getWriter()145     public Writer getWriter() {
146         return writer;
147     }
148 
149     /**
150      * Set the systemID that may be used in association
151      * with the byte or character stream, or, if neither is set, use
152      * this value as a writeable URI (probably a file name).
153      *
154      * @param systemId The system identifier as a URI string.
155      */
setSystemId(String systemId)156     public void setSystemId(String systemId) {
157         this.systemId = systemId;
158     }
159 
160     /**
161      * <p>Set the system ID from a <code>File</code> reference.</p>
162      *
163      *
164      * @param f Must a non-null File reference.
165      */
setSystemId(File f)166     public void setSystemId(File f) {
167         //convert file to appropriate URI, f.toURI().toASCIIString()
168         //converts the URI to string as per rule specified in
169         //RFC 2396,
170         this.systemId = f.toURI().toASCIIString();
171     }
172 
173     /**
174      * Get the system identifier that was set with setSystemId.
175      *
176      * @return The system identifier that was set with setSystemId, or null
177      * if setSystemId was not called.
178      */
getSystemId()179     public String getSystemId() {
180         return systemId;
181     }
182 
183     //////////////////////////////////////////////////////////////////////
184     // Internal state.
185     //////////////////////////////////////////////////////////////////////
186 
187     /**
188      * The systemID that may be used in association
189      * with the byte or character stream, or, if neither is set, use
190      * this value as a writeable URI (probably a file name).
191      */
192     private String systemId;
193 
194     /**
195      * The byte stream that is to be written to.
196      */
197     private OutputStream outputStream;
198 
199     /**
200      * The character stream that is to be written to.
201      */
202     private Writer writer;
203 }
204